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

# Api
<a name="sam-property-function-api"></a>

描述 `Api` 事件源类型的对象。如果定义了 [AWS::Serverless::Api](sam-resource-api.md) 资源，则路径和方法值必须与 API 的 OpenAPI 定义中的操作相对应。

如果未定义 [AWS::Serverless::Api](sam-resource-api.md)，则函数的输入和输出表示 HTTP 请求和 HTTP 响应。

例如，使用 JavaScript API，可以通过返回带有 statusCode 和 body 密钥的对象来控制响应的状态代码和正文。

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

要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。

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

```
  [Auth](#sam-function-api-auth): ApiFunctionAuth
  [Method](#sam-function-api-method): String
  [Path](#sam-function-api-path): String
  [RequestModel](#sam-function-api-requestmodel): RequestModel
  [RequestParameters](#sam-function-api-requestparameters): List of [ String | RequestParameter ]
  [RestApiId](#sam-function-api-restapiid): String
  [ResponseTransferMode](#sam-function-api-responsetransfermode): String
  TimeoutInMillis: Integer
```

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

 `Auth`   <a name="sam-function-api-auth"></a>
此特定 Api\$1路径\$1方法的身份验证配置。  
对于未指定 `DefaultAuthorizer` 时覆盖在单个路径上 API 的 `DefaultAuthorizer` 设置身份验证配置或覆盖默认 `ApiKeyRequired` 设置很有用。  
*类型*：[ApiFunctionAuth](sam-property-function-apifunctionauth.md)  
*必需*：否  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

 `Method`   <a name="sam-function-api-method"></a>
调用此函数的 HTTP 方法。选项包括 `DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST`、`PUT` 和 `ANY`。有关详细信息，请参阅*《API Gateway 开发人员指南》*中的[设置 HTTP 方法](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-settings-method-request.html#setup-method-add-http-method)。  
*类型*：字符串  
*是否必需*：是  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

 `Path`   <a name="sam-function-api-path"></a>
调用此函数的 URI 路径。必须以 `/` 开头。  
*类型*：字符串  
*是否必需*：是  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

 `RequestModel`   <a name="sam-function-api-requestmodel"></a>
用于此特定 Api\$1路径\$1方法 的请求模型。这应该引用 [AWS::Serverless::Api](sam-resource-api.md) 资源 `Models` 部分中指定的模型的名称。  
*类型*：[RequestModel](sam-property-function-requestmodel.md)  
*必需*：否  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

 `RequestParameters`   <a name="sam-function-api-requestparameters"></a>
此特定 Api\$1Path\$1Method 的请求参数配置。所有参数名称必须以 `method.request` 开头，且必须限制为 `method.request.header`、`method.request.querystring`、或`method.request.path`。  
列表既可以包含参数名称字符串，也可以包含[RequestParameter](sam-property-function-requestparameter.md)对象。对于字符串，`Required` 和 `Caching` 属性将默认为 `false`。  
*类型*：[字符串 \$1 [RequestParameter](sam-property-function-requestparameter.md)] 列表  
*必需*：否  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

 `RestApiId`   <a name="sam-function-api-restapiid"></a>
 RestApi 资源的标识符，必须包含具有给定路径和方法的操作。通常，将其设置为引用此模板中定义的 [AWS::Serverless::Api](sam-resource-api.md) 资源。  
如果未定义此属性，则使用生成的`OpenApi`文档 AWS SAM 创建默认[AWS::Serverless::Api](sam-resource-api.md)资源。该资源包含所有路径和方法的并集，这些路径和方法由同一模板中的 `Api` 事件定义，但未指定 `RestApiId`。  
这不能引用其他模板中定义的 [AWS::Serverless::Api](sam-resource-api.md) 资源。  
*类型*：字符串  
*必需*：否  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

`ResponseTransferMode`  <a name="sam-function-api-responsetransfermode"></a>
Lambda 函数集成的响应传输模式。设置`RESPONSE_STREAM`为可启用通过 API Gateway 进行的 Lambda 响应流式传输，从而允许该函数将响应流回客户端。设置为时`RESPONSE_STREAM`，API Gateway 使用 Lambda InvokeWithResponseStreaming API。  
*类型*：字符串  
*必需*：否  
*有效值*：`BUFFERED` \$1 `RESPONSE_STREAM`  
*CloudFormation 兼容性*：此属性直接传递给的[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-method-integration.html#cfn-apigateway-method-integration-responsetransfermode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-method-integration.html#cfn-apigateway-method-integration-responsetransfermode)属性`AWS::ApiGateway::Method Integration`。

`TimeoutInMillis`  <a name="sam-function-api-timeoutinmillis"></a>
自定义超时值，范围在 50 到 29,000 毫秒之间。  
当您指定此属性时， AWS SAM 会修改您的 OpenAPI 定义。必须使用 `DefinitionBody` 属性内联指定 OpenAPI 定义。
*类型*：整数  
*必需*：否  
*默认值*：29,000 毫秒或 29 秒  
*CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。

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

### 基本示例
<a name="sam-property-function-api--examples--apievent"></a>

#### YAML
<a name="sam-property-function-api--examples--apievent--yaml"></a>

```
Events:
  ApiEvent:
    Type: Api
    Properties:
      Path: /path
      Method: get
      RequestParameters:
        - method.request.header.Authorization
        - method.request.querystring.keyword:
            Required: true
            Caching: false
```