本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# ApiFunctionAuth
<a name="sam-property-function-apifunctionauth"></a>

為特定 API、路徑和方法設定事件層級的授權。

## 語法
<a name="sam-property-function-apifunctionauth-syntax"></a>

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

### YAML
<a name="sam-property-function-apifunctionauth-syntax.yaml"></a>

```
  [ApiKeyRequired](#sam-function-apifunctionauth-apikeyrequired): Boolean
  [AuthorizationScopes](#sam-function-apifunctionauth-authorizationscopes): List
  [Authorizer](#sam-function-apifunctionauth-authorizer): String
  [InvokeRole](#sam-function-apifunctionauth-invokerole): String
  OverrideApiAuth: Boolean
  [ResourcePolicy](#sam-function-apifunctionauth-resourcepolicy): ResourcePolicyStatement
```

## Properties
<a name="sam-property-function-apifunctionauth-properties"></a>

 `ApiKeyRequired`   <a name="sam-function-apifunctionauth-apikeyrequired"></a>
此 API、路徑和方法需要 API 金鑰。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 AWS SAM 是唯一的，並且沒有 CloudFormation 同等的。

 `AuthorizationScopes`   <a name="sam-function-apifunctionauth-authorizationscopes"></a>
要套用至此 API、路徑和方法的授權範圍。  
如果您已指定 屬性套用的任何範圍，您指定的範圍將會覆寫該`DefaultAuthorizer`屬性所套用的任何範圍。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 AWS SAM 是唯一的，並且沒有 CloudFormation 同等的。

 `Authorizer`   <a name="sam-function-apifunctionauth-authorizer"></a>
特定函數`Authorizer`的 。  
如果您為`AWS::Serverless::Api`資源指定了全域授權方，則可以將 `Authorizer`設定為 來覆寫授權方`NONE`。如需範例，請參閱 [覆寫 Amazon API Gateway REST API 的全域授權方](#sam-property-function-apifunctionauth--examples--override)。  
如果您使用 `AWS::Serverless::Api` 資源的 `DefinitionBody` 屬性來描述 API，則必須使用 `OverrideApiAuth`搭配 `Authorizer` 來覆寫您的全域授權方。如需詳細資訊，請參閱`OverrideApiAuth`。
*有效值*：`AWS_IAM`、 `NONE`或 AWS SAM 範本中定義之任何授權方的邏輯 ID。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 AWS SAM 是唯一的，並且沒有 CloudFormation 同等的。

 `InvokeRole`   <a name="sam-function-apifunctionauth-invokerole"></a>
指定`InvokeRole`用於`AWS_IAM`授權的 。  
*類型：*字串  
*必要*：否  
*預設*：`CALLER_CREDENTIALS`  
*CloudFormation 相容性*：此屬性對 AWS SAM 是唯一的，並且沒有 CloudFormation 同等屬性。  
*其他備註*：`CALLER_CREDENTIALS`映射至 `arn:aws:iam:::<user>/`，這會使用呼叫者登入資料來叫用端點。

`OverrideApiAuth`  <a name="sam-function-apifunctionauth-overrideapiauth"></a>
將 指定為 `true`以覆寫`AWS::Serverless::Api`資源的全域授權方組態。只有在您指定全域授權方並使用 `AWS::Serverless::Api` 資源的 屬性來描述 API 時，才需要此`DefinitionBody`屬性。  
當您將 指定`OverrideApiAuth`為 時`true`， AWS SAM 會使用為 `ApiKeyRequired`、 `Authorizer`或 提供的任何值來覆寫您的全域授權方`ResourcePolicy`。因此，使用 時，至少也必須指定其中一個屬性`OverrideApiAuth`。如需範例，請參閱 [指定 DefinitionBody for AWS::Serverless::Api 時覆寫全域授權方](#sam-property-function-apifunctionauth--examples--override2)。
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `ResourcePolicy`   <a name="sam-function-apifunctionauth-resourcepolicy"></a>
在 API 上設定此路徑的資源政策。  
*類型*：[ResourcePolicyStatement](sam-property-function-resourcepolicystatement.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 AWS SAM 是唯一的，且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-function-apifunctionauth--examples"></a>

### Function-Auth
<a name="sam-property-function-apifunctionauth--examples--function-auth"></a>

下列範例會在函數層級指定授權。

#### YAML
<a name="sam-property-function-apifunctionauth--examples--function-auth--yaml"></a>

```
Auth:
  ApiKeyRequired: true
  Authorizer: NONE
```

### 覆寫 Amazon API Gateway REST API 的全域授權方
<a name="sam-property-function-apifunctionauth--examples--override"></a>

您可以為您的`AWS::Serverless::Api`資源指定全域授權方。以下是設定全域預設授權方的範例：

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth
```

若要覆寫 AWS Lambda 函數的預設授權方，您可以將 指定`Authorizer`為 `NONE`。以下是範例：

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  ...
  MyFn:
    Type: AWS::Serverless::Function
    Properties:
      ...
      Events:
        LambdaRequest:
          Type: Api
          Properties:
            RestApiId: !Ref MyApiWithLambdaRequestAuth
            Method: GET
            Auth:
              Authorizer: NONE
```

### 指定 DefinitionBody for AWS::Serverless::Api 時覆寫全域授權方
<a name="sam-property-function-apifunctionauth--examples--override2"></a>

使用 `DefinitionBody` 屬性描述`AWS::Serverless::Api`資源時，先前的覆寫方法無法運作。以下是將 `DefinitionBody` 屬性用於 `AWS::Serverless::Api` 資源的範例：

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      DefinitionBody:
        swagger: 2.0
        ...
        paths:
          /lambda-request:
            ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth
```

若要覆寫全域授權方，請使用 `OverrideApiAuth` 屬性。以下是使用 `OverrideApiAuth`以 提供的 值覆寫全域授權方的範例`Authorizer`：

```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
...
Resources:
  MyApiWithLambdaRequestAuth:
    Type: AWS::Serverless::Api
    Properties:
      ...
      DefinitionBody:
        swagger: 2-0
        ...
        paths:
          /lambda-request:
            ...
      Auth:
        Authorizers:
          MyLambdaRequestAuth:
            FunctionArn: !GetAtt MyAuthFn.Arn
        DefaultAuthorizer: MyLambdaRequestAuth
    
    MyAuthFn:
      Type: AWS::Serverless::Function
      ...
    
    MyFn:
      Type: AWS::Serverless::Function
        Properties:
          ...
          Events:
            LambdaRequest:
              Type: Api
              Properties:
                RestApiId: !Ref MyApiWithLambdaRequestAuth
                Method: GET
                Auth:
                  Authorizer: NONE
                  OverrideApiAuth: true
                Path: /lambda-token
```

# ResourcePolicyStatement
<a name="sam-property-function-resourcepolicystatement"></a>

為 API 的所有方法和路徑設定資源政策。如需資源政策的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的使用 API Gateway 資源政策控制對 API 的存取](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)。 **

## 語法
<a name="sam-property-function-resourcepolicystatement-syntax"></a>

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

### YAML
<a name="sam-property-function-resourcepolicystatement-syntax.yaml"></a>

```
  [AwsAccountBlacklist](#sam-function-resourcepolicystatement-awsaccountblacklist): List
  [AwsAccountWhitelist](#sam-function-resourcepolicystatement-awsaccountwhitelist): List
  [CustomStatements](#sam-function-resourcepolicystatement-customstatements): List
  [IntrinsicVpcBlacklist](#sam-function-resourcepolicystatement-intrinsicvpcblacklist): List
  [IntrinsicVpcWhitelist](#sam-function-resourcepolicystatement-intrinsicvpcwhitelist): List
  [IntrinsicVpceBlacklist](#sam-function-resourcepolicystatement-intrinsicvpceblacklist): List
  [IntrinsicVpceWhitelist](#sam-function-resourcepolicystatement-intrinsicvpcewhitelist): List
  [IpRangeBlacklist](#sam-function-resourcepolicystatement-iprangeblacklist): List
  [IpRangeWhitelist](#sam-function-resourcepolicystatement-iprangewhitelist): List
  [SourceVpcBlacklist](#sam-function-resourcepolicystatement-sourcevpcblacklist): List
  [SourceVpcWhitelist](#sam-function-resourcepolicystatement-sourcevpcwhitelist): List
```

## Properties
<a name="sam-property-function-resourcepolicystatement-properties"></a>

 `AwsAccountBlacklist`   <a name="sam-function-resourcepolicystatement-awsaccountblacklist"></a>
要封鎖 AWS 的帳戶。  
*類型*：字串的清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `AwsAccountWhitelist`   <a name="sam-function-resourcepolicystatement-awsaccountwhitelist"></a>
要允許 AWS 的帳戶。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型*：字串的清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `CustomStatements`   <a name="sam-function-resourcepolicystatement-customstatements"></a>
要套用至此 API 的自訂資源政策陳述式清單。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `IntrinsicVpcBlacklist`   <a name="sam-function-resourcepolicystatement-intrinsicvpcblacklist"></a>
要封鎖的虛擬私有雲端 (VPCs) 清單，其中每個 VPC 指定為參考，例如[動態參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)或`Ref`[內部函數](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `IntrinsicVpcWhitelist`   <a name="sam-function-resourcepolicystatement-intrinsicvpcwhitelist"></a>
要允許的 VPCs 清單，其中每個 VPC 指定為參考，例如[動態參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)或`Ref`[內部函數](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `IntrinsicVpceBlacklist`   <a name="sam-function-resourcepolicystatement-intrinsicvpceblacklist"></a>
要封鎖的 VPC 端點清單，其中每個 VPC 端點指定為參考，例如[動態參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)或`Ref`[內部函數](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `IntrinsicVpceWhitelist`   <a name="sam-function-resourcepolicystatement-intrinsicvpcewhitelist"></a>
要允許的 VPC 端點清單，其中每個 VPC 端點指定為參考，例如[動態參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)或`Ref`[內部函數](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `IpRangeBlacklist`   <a name="sam-function-resourcepolicystatement-iprangeblacklist"></a>
要封鎖的 IP 地址或地址範圍。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `IpRangeWhitelist`   <a name="sam-function-resourcepolicystatement-iprangewhitelist"></a>
要允許的 IP 地址或地址範圍。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `SourceVpcBlacklist`   <a name="sam-function-resourcepolicystatement-sourcevpcblacklist"></a>
要封鎖的來源 VPC 或 VPC 端點。來源 VPC 名稱必須以 開頭`"vpc-"`，來源 VPC 端點名稱必須以 開頭`"vpce-"`。如需此屬性的範例使用方式，請參閱此頁面底部的範例區段。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `SourceVpcWhitelist`   <a name="sam-function-resourcepolicystatement-sourcevpcwhitelist"></a>
要允許的來源 VPC 或 VPC 端點。來源 VPC 名稱必須以 開頭`"vpc-"`，來源 VPC 端點名稱必須以 開頭`"vpce-"`。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-function-resourcepolicystatement--examples"></a>

### 資源政策範例
<a name="sam-property-function-resourcepolicystatement--examples--resource-policy-example"></a>

下列範例會封鎖兩個 IP 地址和來源 VPC，並允許 AWS 帳戶。

#### YAML
<a name="sam-property-function-resourcepolicystatement--examples--resource-policy-example--yaml"></a>

```
Auth:
  ResourcePolicy:
    CustomStatements: [{
                         "Effect": "Allow",
                         "Principal": "*",
                         "Action": "execute-api:Invoke",
                         "Resource": "execute-api:/Prod/GET/pets",
                         "Condition": {
                           "IpAddress": {
                             "aws:SourceIp": "1.2.3.4"
                           }
                         }
                       }]
    IpRangeBlacklist:
      - "10.20.30.40"
      - "1.2.3.4"
    SourceVpcBlacklist:
      - "vpce-1a2b3c4d"
    AwsAccountWhitelist:
      - "111122223333"
    IntrinsicVpcBlacklist:
      - "{{resolve:ssm:SomeVPCReference:1}}" 
      - !Ref MyVPC
    IntrinsicVpceWhitelist:
      - "{{resolve:ssm:SomeVPCEReference:1}}" 
      - !Ref MyVPCE
```