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

# 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
```