本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

在事件级别为特定 API、路径和方法配置授权。

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

要在 Amazon Serverless Application Model (Amazon 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 密钥。  
*类型*：布尔值  
*必需*：否  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon CloudFormation 等效属性。

 `AuthorizationScopes`   <a name="sam-function-apifunctionauth-authorizationscopes"></a>
适用于此 API、路径和方法的授权范围。  
如果您已指定 `DefaultAuthorizer` 属性，则您指定的范围将覆盖该属性应用的所有范围。  
*类型*：列表  
*必需*：否  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon 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`、或 Amazon SAM 模板中定义的任何授权者的逻辑 ID。  
*类型*：字符串  
*必需*：否  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon CloudFormation 等效属性。

 `InvokeRole`   <a name="sam-function-apifunctionauth-invokerole"></a>
指定用于 `AWS_IAM` 授权的 `InvokeRole`。  
*类型*：字符串  
*必需*：否  
*默认值*：`CALLER_CREDENTIALS`  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon CloudFormation 等效属性。  
*附加说明*：`CALLER_CREDENTIALS` 映射到 `arn:aws:iam:::<user>/`，后者使用调用者凭证来调用端点。

`OverrideApiAuth`  <a name="sam-function-apifunctionauth-overrideapiauth"></a>
指定为 `true` 以覆盖 `AWS::Serverless::Api` 资源的全局授权方配置。只有在您指定全局授权方并使用 `AWS::Serverless::Api` 资源的 `DefinitionBody` 属性来描述您的 API 时，才需要此属性。  
当你指定`OverrideApiAuth`为时`true`， Amazon SAM 将使用为、或`ResourcePolicy`提供的任何值覆盖你的全局授权`ApiKeyRequired`者`Authorizer`。因此，使用 `OverrideApiAuth` 时还必须指定其中至少一个属性。有关示例，请参阅[指定 for 时 DefinitionBody 覆盖全局授权 AWS::Serverless::Api 方](#sam-property-function-apifunctionauth--examples--override2)。
*类型*：布尔值  
*必需*：否  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon CloudFormation 等效属性。

 `ResourcePolicy`   <a name="sam-function-apifunctionauth-resourcepolicy"></a>
在 API 上为此路径配置资源策略。  
*类型*：[ResourcePolicyStatement](sam-property-function-resourcepolicystatement.md)  
*必需*：否  
*Amazon CloudFormation 兼容性*：此属性是独有的 Amazon SAM ，没有 Amazon CloudFormation 等效属性。

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

### 函数身份验证
<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
```

要覆盖 Amazon 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
```

### 指定 for 时 DefinitionBody 覆盖全局授权 AWS::Serverless::Api 方
<a name="sam-property-function-apifunctionauth--examples--override2"></a>

当使用 `DefinitionBody` 属性描述 `AWS::Serverless::Api` 资源时，之前的覆盖方法不起作用。以下是对 `AWS::Serverless::Api` 资源使用 `DefinitionBody` 属性的示例：

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