本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS::Serverless::Api 创建一组可通过 HTTPS 端点调用的 Amazon API Gateway 资源和方法。无需将[AWS::Serverless::Api](#sam-resource-api)资源明确添加到 AWS 无服务器应用程序定义模板中。这种类型的资源是通过 [AWS::Serverless::Function](sam-resource-function.md) 资源上定义的 Api 事件的并集隐式创建的，这些资源定义于未引用 [AWS::Serverless::Api](#sam-resource-api) 资源的模板。应使用[AWS::Serverless::Api](#sam-resource-api)资源来定义和记录 API OpenApi，这样可以更好地配置底层 Amazon API Gateway 资源。我们建议您使用 CloudFormation 挂钩或 IAM 策略来验证 API Gateway 资源是否附加了授权者来控制对它们的访问。有关使用 CloudFormation 挂钩的更多信息，请参阅 *CloudFormation CLI 用户指南*和[apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub 存储库中的[注册挂钩](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html)。有关使用 IAM 策略的更多信息，请参阅*《API Gateway 开发人员指南》*中的[要求 API 路由具有授权](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization)。 **注意** 部署到时 AWS CloudFormation， AWS SAM 会将您的 AWS SAM 资源转换为 CloudFormation 资源。有关更多信息，请参阅 [生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` Type: AWS::Serverless::Api Properties: [AccessLogSetting](#sam-api-accesslogsetting): [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting) AlwaysDeploy: Boolean [ApiKeySourceType](#sam-api-apikeysourcetype): String [Auth](#sam-api-auth): ApiAuth [BinaryMediaTypes](#sam-api-binarymediatypes): List [CacheClusterEnabled](#sam-api-cacheclusterenabled): Boolean [CacheClusterSize](#sam-api-cacheclustersize): String [CanarySetting](#sam-api-canarysetting): [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting) [Cors](#sam-api-cors): String | CorsConfiguration [DefinitionBody](#sam-api-definitionbody): JSON [DefinitionUri](#sam-api-definitionuri): String | ApiDefinition [Description](#sam-api-description): String [DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): Boolean [Domain](#sam-api-domain): DomainConfiguration [EndpointConfiguration](#sam-api-endpointconfiguration): EndpointConfiguration [FailOnWarnings](#sam-api-failonwarnings): Boolean [GatewayResponses](#sam-api-gatewayresponses): Map MergeDefinitions: Boolean [MethodSettings](#sam-api-methodsettings): MethodSettings [MinimumCompressionSize](#sam-api-minimumcompressionsize): Integer [Mode](#sam-api-mode): String [Models](#sam-api-models): Map [Name](#sam-api-name): String [OpenApiVersion](#sam-api-openapiversion): String PropagateTags: Boolean [Policy](#sam-api-policy): JSON [StageName](#sam-api-stagename): String [Tags](#sam-api-tags): Map [TracingEnabled](#sam-api-tracingenabled): Boolean [Variables](#sam-api-variables): Map ``` ## Properties `AccessLogSetting` 配置某个阶段的访问日志设置。 *类型*：[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting) *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)`属性。 `AlwaysDeploy` 即使未检测到 API 的更改，也要始终部署 API。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ApiKeySourceType` 用于根据使用计划对请求进行计量的 API 键的源。有效值为 `HEADER` 和 `AUTHORIZER`。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype)`属性。 `Auth` 配置授权，以控制对 API Gateway API 的访问。有关使用配置访问权限的更多信息， AWS SAM 请参阅[使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。有关如何覆盖全局授权方的示例，请参阅 [覆盖 Amazon API Gateway REST API 的全局授权方](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override)。 *类型*：[ApiAuth](sam-property-api-apiauth.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `BinaryMediaTypes` 您的 API 可能返回的 MIME 类型列表。使用它来启用对的二进制支持APIs。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::RestApi`资源的`[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)`属性。的列表 BinaryMediaTypes 已添加到 CloudFormation 资源和 OpenAPI 文档中。 `CacheClusterEnabled` 指示是否为阶段启用缓存。要缓存响应，还必须在 `MethodSettings` 下将 `CachingEnabled` 设置为 `true`。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)`属性。 `CacheClusterSize` 阶段的缓存群集大小。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)`属性。 `CanarySetting` 将金丝雀设置配置为常规部署的某个阶段。 *类型*：[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting) *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)`属性。 `Cors` 管理所有 API Gateway 的跨源资源共享 (CORS)。 APIs使用字符串指定允许使用的域，或使用其他 Cors 配置指定词典。 CORS AWS SAM 需要修改你的 OpenAPI 定义。在 `DefinitionBody` 中创建内联 OpenAPI 定义以开启 CORS。有关 CORS 的更多信息，请参阅*《API Gateway 开发人员指南》*中的[为 API Gateway REST API 资源启用 CORS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html)。 *类型*：字符串 \$1 [CorsConfiguration](sam-property-api-corsconfiguration.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `DefinitionBody` 描述您的 API 的 OpenAPI 规范。如果 `DefinitionUri` 和 `DefinitionBody` 均未指定，SAM 将根据模板配置为您生成 `DefinitionBody`。要引用定义 API 的本地 OpenAPI 文件，请使用 `AWS::Include` 转换。要了解更多信息，请参阅[如何 AWS SAM 上传本地文件](deploy-upload-local-files.md)。 *类型*：JSON *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::RestApi`资源的`[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)`属性。如果提供了某些属性，则可以在将内容传递给DefinitionBody 之前在中插入或修改内容 CloudFormation。属性包括 `Auth`、`BinaryMediaTypes`、`Cors`、`GatewayResponses`、`Models`、和 `AWS::Serverless::Function` 相应 Api 类型的 `EventSource`。 `DefinitionUri` Amazon S3 Uri、本地文件路径或定义 API 的 OpenAPI 文档的位置对象。此属性引用的 Amazon S3 对象必须是有效的 OpenAPI 文件。如果 `DefinitionUri` 和 `DefinitionBody` 均未指定，SAM 将根据模板配置为您生成 `DefinitionBody`。如果提供了本地文件路径，则模板必须经过包含 `sam deploy` 或 `sam package` 命令的工作流程，才能使定义正确转换。引用的外部 OpenApi 文件不支持内部函数。`DefinitionUri`改用带[有 Include 转换](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html)的`DefinitionBody`属性将 OpenApi 定义导入到模板中。 *类型*：字符串 \$1 [ApiDefinition](sam-property-api-apidefinition.md) *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::RestApi`资源的`[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location)`属性。嵌套的 Amazon S3 属性的命名有所不同。 `Description` Api 资源的描述。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)`属性。 `DisableExecuteApiEndpoint` 指定客户端是否可以使用默认 `execute-api` 端点调用您的 API。默认情况下，客户端可以使用默认 `https://{api_id}.execute-api.{region}.amazonaws.com` 调用您的 API。如果要求客户端使用自定义域名来调用 API，请指定 `True`。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::RestApi`资源的`[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)`属性。它直接传递给 `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` 扩展的 `disableExecuteApiEndpoint` 属性，然后添加到 `AWS::ApiGateway::RestApi` 资源的 ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` 属性中。 `Domain` 为此 API Gateway API 配置自定义域。 *类型*：[DomainConfiguration](sam-property-api-domainconfiguration.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `EndpointConfiguration` REST API 的端点类型。 *类型*：[EndpointConfiguration](sam-property-api-endpointconfiguration.md) *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::RestApi`资源的`[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)`属性。嵌套配置属性的命名有所不同。 `FailOnWarnings` 指定在遇到警告时是回滚 (`true`) 还是不回滚 (`false`) API 创建。默认值为 `false`。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)`属性。 `GatewayResponses` 为 API 配置网关响应。网关响应是 API Gateway 直接返回或使用 Lambda 授权方返回的响应。有关更多信息，请参阅[网关响应的 Api Gateway OpenApi 扩展](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html)文档。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `MergeDefinitions` AWS SAM 从您的 API 事件源生成OpenAPI规范。指定`true`将其 AWS SAM 合并到`AWS::Serverless::Api`资源中定义的内联OpenAPI规范中。指定 `false` 以不合并。 `MergeDefinitions` 需要定义 `AWS::Serverless::Api` 的 `DefinitionBody` 属性。`MergeDefinitions` 与 `AWS::Serverless::Api` 的 `DefinitionUri` 属性不兼容。 *默认值*：`false` *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `MethodSettings` 配置 API 阶段的所有设置，包括日志、指标、CacheTTL、节流。 *类型*：[ MethodSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html) 列表 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)`属性。 `MinimumCompressionSize` 允许根据客户端的 Accept-Encoding 标头压缩响应正文。当响应正文大小大于或等于您配置的阈值时，就会触发压缩。最大正文大小阈值为 10 MB（10,485,760 字节）。- 支持以下压缩类型：gzip、deflate 和身份。 *类型*：整数 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)`属性。 `Mode` 此属性仅在您使用 OpenAPI 定义 REST API 时才适用。`Mode` 确定 API Gateway 如何处理资源更新。有关更多信息，请参阅 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html) 资源类型的[模式](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)属性。 *有效值*：`overwrite` 或 `merge` *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)`属性。 `Models` 您的 API 方法要使用的架构。可以使用 JSON 或 YAML 描述这些架构。有关示例模型，请参阅本页底部的“示例”部分。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Name` API Gateway RestApi 资源的名称 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的`[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name)`属性。 `OpenApiVersion` OpenApi 要使用的版本。这可以是 `2.0` Swagger 规范，也可以是 OpenApi 3.0 版本之一，比如。`3.0.1`有关 OpenAPI 的更多信息，请参阅 [OpenAPI 规范](https://swagger.io/specification/)。 AWS SAM 创建一个默认情况下名为`Stage`的阶段。将此属性设置为任何有效值将阻止阶段 `Stage` 的创建。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `PropagateTags` 指明是否将 `Tags` 属性中的标签传递给 [AWS::Serverless::Api](sam-specification-generated-resources-api.md) 生成的资源。指定 `True` 以在生成的资源中传播标签。 *类型*：布尔值 *必需*：否 *默认值*：`False` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Policy` 一个策略文档，其中包含 API 的权限。要设置策略的 ARN，请使用 `!Join` 内部函数（`""` 作为分隔符）以及值 `"execute-api:/"` 和 `"*"`。 *类型*：JSON *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi`资源的 P [ol](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) icy 属性。 `StageName` 阶段的名称，API Gateway 将它用作调用的统一资源标识符 (URI) 中的第一个路径部分。要引用阶段资源，请使用 `.Stage`。有关指定 [AWS::Serverless::Api](#sam-resource-api) 资源时引用生成资源的更多信息，请参阅 [CloudFormation 指定时AWS::Serverless::Api生成的资源](sam-specification-generated-resources-api.md)。有关生成的 CloudFormation 资源的一般信息，请参阅[生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::Stage`资源的`[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename)`属性。它在 SAM 中为必需，但在 API Gateway 中并非必需 *附加说明*：隐式 API 的阶段名称为 “Prod”。 `Tags` 指定要添加到此 API Gateway 阶段的标签的映射（字符串到字符串）。有关标签的有效键和值的详细信息，请参阅*《AWS CloudFormation 用户指南》*中的[资源标签](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::Stage`资源的`[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags)`属性。SAM 中的 Tags 属性由 Key: Value CloudFormation 对组成；其中包含标签对象的列表。 `TracingEnabled` 指示是否为阶段启用通过 X-Ray 进行的主动跟踪。有关 X-Ray 的更多信息，请参阅 *API Gateway 开发者指南中的 APIs 使用 X-Ray* [跟踪用户向 REST 发出的请求](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html)。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled)`属性。 `Variables` 一个定义阶段变量的映射 (字符串到字符串)，其中变量名作为键，变量值作为值。变量名称只能包含字母数字字符。值必须匹配以下正则表达式：`[A-Za-z0-9._~:/?#&=,-]+`。 *类型*：映射 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::Stage`资源的`[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables)`属性。 ## 返回值 ### Ref 当向 `Ref` 内置函数提供此资源的逻辑 ID 时，它将返回底层 API Gateway API 的 ID。有关使用 `Ref` 函数的更多信息，请参阅*《AWS CloudFormation 用户指南》*中的 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)。 ### Fn:: GetAtt `Fn::GetAtt` 返回一个此类型指定属性的值。以下为可用属性和示例返回值。有关使用 `Fn::GetAtt` 的更多信息，请参阅*《AWS CloudFormation 用户指南》*中的 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html)。 `RootResourceId` `RestApi` 资源的根资源 ID，例如 `a0bc123d4e`。 ## 示例 ### SimpleApiExample 一个 Hello World AWS SAM 模板文件，其中包含带有 API 端点的 Lambda 函数。这是正在运行的无服务器应用程序的完整 AWS SAM 模板文件。 #### YAML ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} ``` ### ApiCorsExample 一个 AWS SAM 模板片段，其中包含在外部 Swagger 文件中定义的 API 以及 Lambda 集成和 CORS 配置。这只是显示[AWS::Serverless::Api](#sam-resource-api)定义的 AWS SAM 模板文件的一部分。 #### YAML ``` Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod # Allows www.example.com to call these APIs # SAM will automatically add AllowMethods with a list of methods for this API Cors: "'www.example.com'" DefinitionBody: # Pull in an OpenApi definition from S3 'Fn::Transform': Name: 'AWS::Include' # Replace "bucket" with your bucket name Parameters: Location: s3://bucket/swagger.yaml ``` ### ApiCognitoAuthExample 包含使用 Amazon Cognito 授权针对该 API 的请求的 API 的 AWS SAM 模板片段。这只是显示[AWS::Serverless::Api](#sam-resource-api)定义的 AWS SAM 模板文件的一部分。 #### YAML ``` Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn] ``` ### ApiModelsExample 带有包含模型架构的 API 的 AWS SAM 模板片段。这只是 AWS SAM 模板文件的一部分，显示了一个包含两个模型架构的[AWS::Serverless::Api](#sam-resource-api)定义。 #### YAML ``` Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Models: User: type: object required: - username - employee_id properties: username: type: string employee_id: type: integer department: type: string Item: type: object properties: count: type: integer category: type: string price: type: integer ``` ### 缓存示例一个 Hello World AWS SAM 模板文件，其中包含带有 API 端点的 Lambda 函数。API 已为一种资源和方法启用缓存。有关缓存的更多信息，请参阅的*《API Gateway 开发人员指南》*中的[启用 API 缓存以增强响应能力](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html)。 #### YAML ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition with caching turned on Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 Tags: CacheMethods: All ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} ``` ### 带私有 API 的自定义域示例一个 Hello World AWS SAM 模板文件，其中包含一个 Lambda 函数，该函数的 API 终端节点映射到私有域。该模板在 VPC 端点与私有域之间创建域访问关联。有关更多信息，请参阅 [API Gateway APIs 中的私有自定义域名](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html)。 #### YAML ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template configured with a custom domain using a private API Parameters: DomainName: Type: String Default: mydomain.example.com CertificateArn: Type: String HostedZoneId: Type: String VpcEndpointId: Type: String VpcEndpointDomainName: Type: String VpcEndpointHostedZoneId: Type: String Resources: MyFunction: Type: AWS::Serverless::Function Properties: InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200} Handler: index.handler Runtime: python3.13 Events: Fetch: Type: Api Properties: RestApiId: Ref: MyApi Method: Get Path: /get MyApi: Type: AWS::Serverless::Api Properties: StageName: Prod EndpointConfiguration: Type: PRIVATE VPCEndpointIds: - !Ref VpcEndpointId Policy: Version: '2012-10-17 ' Statement: - Effect: Allow Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* - Effect: Deny Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* Condition: StringNotEquals: aws:SourceVpce: !Ref VpcEndpointId Domain: DomainName: !Ref DomainName CertificateArn: !Ref CertificateArn EndpointConfiguration: PRIVATE BasePath: - / Route53: HostedZoneId: !Ref HostedZoneId VpcEndpointDomainName: !Ref VpcEndpointDomainName VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId AccessAssociation: VpcEndpointId: !Ref VpcEndpointId Policy: Version: '2012-10-17 ' Statement: - Effect: Allow Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* - Effect: Deny Principal: '*' Action: execute-api:Invoke Resource: execute-api:/* Condition: StringNotEquals: aws:SourceVpce: !Ref VpcEndpointId ``` # ApiAuth 配置授权，以控制对 API Gateway API 的访问。有关使用配置访问权限的更多信息和示例， AWS SAM 请参阅[使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` AddApiKeyRequiredToCorsPreflight: Boolean [AddDefaultAuthorizerToCorsPreflight](#sam-api-apiauth-adddefaultauthorizertocorspreflight): Boolean [ApiKeyRequired](#sam-api-apiauth-apikeyrequired): Boolean [Authorizers](#sam-api-apiauth-authorizers): CognitoAuthorizer | LambdaTokenAuthorizer | LambdaRequestAuthorizer | AWS_IAM [DefaultAuthorizer](#sam-api-apiauth-defaultauthorizer): String [InvokeRole](#sam-api-apiauth-invokerole): String [ResourcePolicy](#sam-api-apiauth-resourcepolicy): ResourcePolicyStatement [UsagePlan](#sam-api-apiauth-usageplan): ApiUsagePlan ``` **注意** 该 `Authorizers` 属性包含 `AWS_IAM`，但无需为 `AWS_IAM` 进行额外配置。有关示例，请参阅[AWS IAM](#sam-property-api-apiauth--examples--aws_iam)。 ## Properties `AddApiKeyRequiredToCorsPreflight` 如果设置了 `ApiKeyRequired` 和 `Cors` 属性，则设置 `AddApiKeyRequiredToCorsPreflight` 会导致 API 密钥被添加到 `Options` 属性中。 *类型*：布尔值 *必需*：否 *默认值*：`True` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `AddDefaultAuthorizerToCorsPreflight` 如果设置了 `DefaultAuthorizer` 和 `Cors` 属性，则设置 `AddDefaultAuthorizerToCorsPreflight` 会导致默认授权方被添加到 OpenAPI 部分的 `Options` 属性中。 *类型*：布尔值 *必需*：否 *默认值*：True *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ApiKeyRequired` 如果设置为 true，则所有 API 事件都需要 API 密钥。有关 API 密钥的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API 密钥创建和使用使用计划](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Authorizers` 用于控制对 API Gateway API 的访问的授权方。有关更多信息，请参阅 [使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。 *类型*:[CognitoAuthorizer](sam-property-api-cognitoauthorizer.md)\$1 [LambdaTokenAuthorizer](sam-property-api-lambdatokenauthorizer.md)\$1 [LambdaRequestAuthorizer](sam-property-api-lambdarequestauthorizer.md)\$1 AWS\$1IAM *必需*：否 *默认值*：无 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 *其他说明*：SAM 在 Api 的 OpenApi 定义中添加了授权方。 `DefaultAuthorizer` 为 API Gateway API 指定默认授权方，默认情况下，该授权方将用于授权 API 调用。如果将与此 API EventSource 关联的函数的 Api 配置为使用 IAM 权限，则必须将此属性设置为`AWS_IAM`，否则将导致错误。 *类型*：字符串 *必需*：否 *默认值*：无 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `InvokeRole` 将所有资源和方法的集成凭证设置为此值。 `CALLER_CREDENTIALS` 映射到 `arn:aws:iam:::/`，后者使用调用者凭证来调用端点。 *有效值*: `CALLER_CREDENTIALS`, `NONE`, `IAMRoleArn` *类型*：字符串 *必需*：否 *默认值*：`CALLER_CREDENTIALS` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ResourcePolicy` 为 API 中的所有方法和路径配置资源策略。 *类型*：[ResourcePolicyStatement](sam-property-api-resourcepolicystatement.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 *附加说明*：也可以使用 [ApiFunctionAuth](sam-property-function-apifunctionauth.md) 在各个 `AWS::Serverless::Function` 中定义此设置。这是 with 所必需 APIs 的`EndpointConfiguration: PRIVATE`。 `UsagePlan` 配置与此 API 关联的使用计划。有关使用计划的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API 密钥创建和使用使用计划](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。设置此 AWS SAM 属性后，此属性会额外生成三个 CloudFormation 资源：a [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、a 和[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html)。有关此场景的更多信息，请参阅[UsagePlan 属性已指定](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-usage-plan)。有关生成的 CloudFormation 资源的一般信息，请参阅[生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。 *类型*：[ApiUsagePlan](sam-property-api-apiusageplan.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### CognitoAuth Cognito 身份验证示例 #### YAML ``` Auth: Authorizers: MyCognitoAuth: UserPoolArn: Fn::GetAtt: - MyUserPool - Arn AuthType: "COGNITO_USER_POOLS" DefaultAuthorizer: MyCognitoAuth InvokeRole: CALLER_CREDENTIALS AddDefaultAuthorizerToCorsPreflight: false ApiKeyRequired: false ResourcePolicy: CustomStatements: [{ "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "execute-api:/Prod/GET/pets", "Condition": { "IpAddress": { "aws:SourceIp": "1.2.3.4" } } }] IpRangeDenylist: - "10.20.30.40" ``` ### AWS IAM AWS IAM 示例 #### YAML ``` Auth: Authorizers: AWS_IAM ``` # ApiUsagePlan 为 API Gateway API 配置使用计划。有关使用计划的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API 密钥创建和使用使用计划](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [CreateUsagePlan](#sam-api-apiusageplan-createusageplan): String [Description](#sam-api-apiusageplan-description): String [Quota](#sam-api-apiusageplan-quota): [QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota) [Tags](#sam-api-apiusageplan-tags): List [Throttle](#sam-api-apiusageplan-throttle): [ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle) [UsagePlanName](#sam-api-apiusageplan-usageplanname): String ``` ## Properties `CreateUsagePlan` 确定如何配置此使用计划。有效值包括 `PER_API`、`SHARED` 和 `NONE`。 `PER_API` 会创建特定于此 API 的 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html) 和 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html) 资源。这些资源的逻辑 IDs 分别为`UsagePlan``ApiKey``UsagePlanKey`、和。 `SHARED`创建[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、和[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html)资源，这些资源在同一 AWS SAM 模板`CreateUsagePlan: SHARED`中也包含的任何 API 之间共享。这些资源的逻辑 IDs 分别为`ServerlessUsagePlan``ServerlessApiKey``ServerlessUsagePlanKey`、和。如果您使用此选项，我们建议您仅在一个 API 资源中为此使用计划添加其他配置，以避免定义冲突和状态不确定性。 `NONE` 禁止创建使用计划或将使用计划与此 API 关联。在 [模板的 “全局” 部分 AWS SAM](sam-specification-template-anatomy-globals.md) 中指定了 `SHARED` 或 `PER_API` 的情况下才需要这样做。 *有效值*：`PER_API`、`SHARED` 和 `NONE` *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Description` 使用计划的描述。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::UsagePlan`资源的`[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-description)`属性。 `Quota` 配置用户可在指定时间间隔内发出的请求的数量。 *类型*：[QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota) *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::UsagePlan`资源的`[Quota](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)`属性。 `Tags` 与使用计划关联的任意标签（键值对）的数组。此属性使用[CloudFormation 标签类型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::UsagePlan`资源的`[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-tags)`属性。 `Throttle` 配置整体请求速率（每秒平均请求数）和突发容量。 *类型*：[ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle) *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::UsagePlan`资源的`[Throttle](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)`属性。 `UsagePlanName` 使用计划的名称。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::UsagePlan`资源的`[UsagePlanName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-usageplanname)`属性。 ## 示例 ### UsagePlan 以下是使用计划示例。 #### YAML ``` Auth: UsagePlan: CreateUsagePlan: PER_API Description: Usage plan for this API Quota: Limit: 500 Period: MONTH Throttle: BurstLimit: 100 RateLimit: 50 Tags: - Key: TagName Value: TagValue ``` # CognitoAuthorizer 定义 Amazon Cognito 用户群体授权方。有关更多信息以及示例，请参阅 [使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [AuthorizationScopes](#sam-api-cognitoauthorizer-authorizationscopes): List [Identity](#sam-api-cognitoauthorizer-identity): CognitoAuthorizationIdentity [UserPoolArn](#sam-api-cognitoauthorizer-userpoolarn): String ``` ## Properties `AuthorizationScopes` 此授权方的授权范围列表。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Identity` 此属性可用于在授权方传入请求中指定 `IdentitySource`。 *类型*：[CognitoAuthorizationIdentity](sam-property-api-cognitoauthorizationidentity.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `UserPoolArn` 可以指用户 pool/specify 一个你想向其添加这个 cognito 授权者的用户池 arn *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### CognitoAuth Cognito 身份验证示例 #### YAML ``` Auth: Authorizers: MyCognitoAuth: AuthorizationScopes: - scope1 - scope2 UserPoolArn: Fn::GetAtt: - MyCognitoUserPool - Arn Identity: Header: MyAuthorizationHeader ValidationExpression: myauthvalidationexpression ``` # CognitoAuthorizationIdentity 此属性可用于在授权方的传入请求 IdentitySource 中指定。有关更多信息， IdentitySource 请参阅 A [ApiGateway uthorizer OpenApi 扩展](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [Header](#sam-api-cognitoauthorizationidentity-header): String [ReauthorizeEvery](#sam-api-cognitoauthorizationidentity-reauthorizeevery): Integer [ValidationExpression](#sam-api-cognitoauthorizationidentity-validationexpression): String ``` ## Properties `Header` 在 OpenApi 定义中为 “授权” 指定标题名称。 *类型*：字符串 *必需*：否 *默认值*：Authorization *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ReauthorizeEvery` time-to-live(TTL) 周期，以秒为单位，用于指定 API Gateway 缓存授权方结果的时长。如果您指定一个大于 0 的值，API Gateway 将缓存授权方响应。默认情况下，API Gateway 将此属性设为 300。最大值为 3600 秒（1 小时）。 *类型*：整数 *必需*：否 *默认值*：300 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ValidationExpression` 指定验证传入身份的验证表达式 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### CognitoAuthIdentity #### YAML ``` Identity: Header: MyCustomAuthHeader ValidationExpression: Bearer.* ReauthorizeEvery: 30 ``` # LambdaRequestAuthorizer 配置 Lambda 授权方以通过 Lambda 函数控制对 API 的访问。有关更多信息以及示例，请参阅 [使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` DisableFunctionDefaultPermissions: Boolean [FunctionArn](#sam-api-lambdarequestauthorizer-functionarn): String [FunctionInvokeRole](#sam-api-lambdarequestauthorizer-functioninvokerole): String [FunctionPayloadType](#sam-api-lambdarequestauthorizer-functionpayloadtype): String [Identity](#sam-api-lambdarequestauthorizer-identity): LambdaRequestAuthorizationIdentity ``` ## Properties `DisableFunctionDefaultPermissions` 指定`true`以 AWS SAM 防止自动创建`AWS::Lambda::Permissions`资源以在您的`AWS::Serverless::Api`资源和授权者 Lambda 函数之间配置权限。 *默认值*：`false` *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionArn` 指定 Lambda 函数的函数 ARN，该函数为 API 提供授权。 AWS SAM 当为指定`AWS::Lambda::Permissions`资源时`FunctionArn`，将自动创建资源`AWS::Serverless::Api`。该 `AWS::Lambda::Permissions` 资源在您的 API 和授权方 Lambda 函数之间配置权限。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionInvokeRole` 将授权者凭证添加到 Lambda 授权方的 OpenApi 定义中。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionPayloadType` 此属性可用于定义 API 的 Lambda 授权方的类型。 *有效值*：`TOKEN` 或 `REQUEST` *类型*：字符串 *必需*：否 *默认值*：`TOKEN` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Identity` 此属性可用于在授权方传入请求中指定 `IdentitySource`。仅当属性 `FunctionPayloadType` 为 `REQUEST` 时，该属性是必需属性。 *类型*：[LambdaRequestAuthorizationIdentity](sam-property-api-lambdarequestauthorizationidentity.md) *必需*：条件 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### LambdaRequestAuth #### YAML ``` Authorizers: MyLambdaRequestAuth: FunctionPayloadType: REQUEST FunctionArn: Fn::GetAtt: - MyAuthFunction - Arn FunctionInvokeRole: Fn::GetAtt: - LambdaAuthInvokeRole - Arn Identity: Headers: - Authorization1 ``` # LambdaRequestAuthorizationIdentity 此属性可用于在授权方的传入请求 IdentitySource 中指定。有关更多信息， IdentitySource 请参阅 A [ApiGateway uthorizer OpenApi 扩展](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [Context](#sam-api-lambdarequestauthorizationidentity-context): List [Headers](#sam-api-lambdarequestauthorizationidentity-headers): List [QueryStrings](#sam-api-lambdarequestauthorizationidentity-querystrings): List [ReauthorizeEvery](#sam-api-lambdarequestauthorizationidentity-reauthorizeevery): Integer [StageVariables](#sam-api-lambdarequestauthorizationidentity-stagevariables): List ``` ## Properties `Context` 将给定的上下文字符串转换为格式 `context.contextString` 的映射表达式。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Headers` 将标头转换为格式 `method.request.header.name` 的映射表达式的逗号分隔字符串。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `QueryStrings` 将给定的查询字符串转换为格式 `method.request.querystring.queryString` 的映射表达式的逗号分隔字符串。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ReauthorizeEvery` time-to-live(TTL) 周期，以秒为单位，用于指定 API Gateway 缓存授权方结果的时长。如果您指定一个大于 0 的值，API Gateway 将缓存授权方响应。默认情况下，API Gateway 将此属性设为 300。最大值为 3600 秒（1 小时）。 *类型*：整数 *必需*：否 *默认值*：300 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `StageVariables` 将给定的阶段变量转换为格式 `stageVariables.stageVariable` 的映射表达式的逗号分隔字符串。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### LambdaRequestIdentity #### YAML ``` Identity: QueryStrings: - auth Headers: - Authorization StageVariables: - VARIABLE Context: - authcontext ReauthorizeEvery: 100 ``` # LambdaTokenAuthorizer 配置 Lambda 授权方以通过 Lambda 函数控制对 API 的访问。有关更多信息以及示例，请参阅 [使用您的 AWS SAM 模板控制 API 访问权限](serverless-controlling-access-to-apis.md)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` DisableFunctionDefaultPermissions: Boolean [FunctionArn](#sam-api-lambdatokenauthorizer-functionarn): String [FunctionInvokeRole](#sam-api-lambdatokenauthorizer-functioninvokerole): String [FunctionPayloadType](#sam-api-lambdatokenauthorizer-functionpayloadtype): String [Identity](#sam-api-lambdatokenauthorizer-identity): LambdaTokenAuthorizationIdentity ``` ## Properties `DisableFunctionDefaultPermissions` 指定`true`以 AWS SAM 防止自动创建`AWS::Lambda::Permissions`资源以在您的`AWS::Serverless::Api`资源和授权者 Lambda 函数之间配置权限。 *默认值*：`false` *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionArn` 指定 Lambda 函数的函数 ARN，该函数为 API 提供授权。 AWS SAM 当为指定`AWS::Lambda::Permissions`资源时`FunctionArn`，将自动创建资源`AWS::Serverless::Api`。该 `AWS::Lambda::Permissions` 资源在您的 API 和授权方 Lambda 函数之间配置权限。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionInvokeRole` 将授权者凭证添加到 Lambda 授权方的 OpenApi 定义中。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `FunctionPayloadType` 此属性可用于定义 Api 的 Lambda 授权方的类型。 *有效值*：`TOKEN` 或 `REQUEST` *类型*：字符串 *必需*：否 *默认值*：`TOKEN` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Identity` 此属性可用于在授权方传入请求中指定 `IdentitySource`。仅当属性 `FunctionPayloadType` 为 `REQUEST` 时，该属性是必需属性。 *类型*：[LambdaTokenAuthorizationIdentity](sam-property-api-lambdatokenauthorizationidentity.md) *必需*：条件 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### LambdaTokenAuth #### YAML ``` Authorizers: MyLambdaTokenAuth: FunctionArn: Fn::GetAtt: - MyAuthFunction - Arn Identity: Header: MyCustomAuthHeader # OPTIONAL; Default: 'Authorization' ValidationExpression: mycustomauthexpression # OPTIONAL ReauthorizeEvery: 20 # OPTIONAL; Service Default: 300 ``` ### BasicLambdaTokenAuth #### YAML ``` Authorizers: MyLambdaTokenAuth: FunctionArn: Fn::GetAtt: - MyAuthFunction - Arn ``` # LambdaTokenAuthorizationIdentity 此属性可用于在授权方的传入请求 IdentitySource 中指定。有关更多信息， IdentitySource 请参阅[ApiGateway 授权器 OpenApi 扩展](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [Header](#sam-api-lambdatokenauthorizationidentity-header): String [ReauthorizeEvery](#sam-api-lambdatokenauthorizationidentity-reauthorizeevery): Integer [ValidationExpression](#sam-api-lambdatokenauthorizationidentity-validationexpression): String ``` ## Properties `Header` 在 OpenApi 定义中为授权指定标题名称。 *类型*：字符串 *必需*：否 *默认值*：Authorization *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ReauthorizeEvery` time-to-live(TTL) 周期，以秒为单位，用于指定 API Gateway 缓存授权方结果的时长。如果您指定一个大于 0 的值，API Gateway 将缓存授权方响应。默认情况下，API Gateway 将此属性设为 300。最大值为 3600 秒（1 小时）。 *类型*：整数 *必需*：否 *默认值*：300 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `ValidationExpression` 指定验证传入身份的验证表达式。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### LambdaTokenIdentity #### YAML ``` Identity: Header: MyCustomAuthHeader ValidationExpression: Bearer.* ReauthorizeEvery: 30 ``` # ResourcePolicyStatement 为 API 的所有方法和路径配置资源策略。有关资源策略的更多信息，请参阅*《API Gateway 开发人员指南》*中的[使用 API Gateway 资源策略控制 API 的访问权限](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [AwsAccountBlacklist](#sam-api-resourcepolicystatement-awsaccountblacklist): List [AwsAccountWhitelist](#sam-api-resourcepolicystatement-awsaccountwhitelist): List [CustomStatements](#sam-api-resourcepolicystatement-customstatements): List [IntrinsicVpcBlacklist](#sam-api-resourcepolicystatement-intrinsicvpcblacklist): List [IntrinsicVpcWhitelist](#sam-api-resourcepolicystatement-intrinsicvpcwhitelist): List [IntrinsicVpceBlacklist](#sam-api-resourcepolicystatement-intrinsicvpceblacklist): List [IntrinsicVpceWhitelist](#sam-api-resourcepolicystatement-intrinsicvpcewhitelist): List [IpRangeBlacklist](#sam-api-resourcepolicystatement-iprangeblacklist): List [IpRangeWhitelist](#sam-api-resourcepolicystatement-iprangewhitelist): List [SourceVpcBlacklist](#sam-api-resourcepolicystatement-sourcevpcblacklist): List [SourceVpcWhitelist](#sam-api-resourcepolicystatement-sourcevpcwhitelist): List ``` ## Properties `AwsAccountBlacklist` 要封锁的 AWS 账户。 *类型*：字符串列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `AwsAccountWhitelist` 要允许的 AWS 账户。有关此属性的使用示例，请参阅本页底部的“示例”部分。 *类型*：字符串列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `CustomStatements` 适用于此 API 的自定义资源策略语句列表。有关此属性的使用示例，请参阅本页底部的“示例”部分。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `IntrinsicVpcBlacklist` 要屏蔽的虚拟私有云列表 (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` 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` 要阻止的 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` 要允许的 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` 要阻止的 IP 地址或地址范围。有关此属性的使用示例，请参阅本页底部的“示例”部分。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `IpRangeWhitelist` 要允许的 IP 地址或地址范围。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `SourceVpcBlacklist` 要阻止的源 VPC 或 VPC 端点。源 VPC 名称必须以 `"vpc-"` 开头，源 VPC 端点名称必须以 `"vpce-"` 开头。有关此属性的使用示例，请参阅本页底部的“示例”部分。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `SourceVpcWhitelist` 要允许的源 VPC 或 VPC 端点。源 VPC 名称必须以 `"vpc-"` 开头，源 VPC 端点名称必须以 `"vpce-"` 开头。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### 资源策略示例以下示例屏蔽两个 IP 地址和一个源 VPC，并允许一个 AWS 账户。 #### YAML ``` 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 ``` # ApiDefinition 定义 API 的 OpenAPI 文档。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [Bucket](#sam-api-apidefinition-bucket): String [Key](#sam-api-apidefinition-key): String [Version](#sam-api-apidefinition-version): String ``` ## Properties `Bucket` 存储了 OpenAPI 文件的 Amazon S3 桶的名称。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``S3Location`数据类型的`[Bucket](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-bucket)`属性。 `Key` OpenAPI 文件的 Amazon S3 密钥。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``S3Location`数据类型的`[Key](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-key)`属性。 `Version` 对于受版本控制的对象，是 OpenAPI 文件的版本。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``S3Location`数据类型的`[Version](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-s3location.html#cfn-apigateway-restapi-s3location-version)`属性。 ## 示例 ### 定义 Uri 示例 API 定义示例 #### YAML ``` DefinitionUri: Bucket: amzn-s3-demo-bucket-name Key: mykey-name Version: 121212 ``` # CorsConfiguration 管理 API Gateway 的跨源资源共享 (CORS)。 APIs使用字符串指定允许使用的域，或使用其他 Cors 配置指定词典。 **注意** CORS AWS SAM 需要修改你的 OpenAPI 定义。在 `DefinitionBody` 中创建内联 OpenAPI 定义以开启 CORS。如果在 `CorsConfiguration` OpenAPI 定义中和属性级别设置了，则将其 AWS SAM 合并。属性级别优先于 OpenAPI 定义。有关 CORS 的更多信息，请参阅*《API Gateway 开发人员指南》*中的[为 API Gateway REST API 资源启用 CORS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [AllowCredentials](#sam-api-corsconfiguration-allowcredentials): Boolean [AllowHeaders](#sam-api-corsconfiguration-allowheaders): String [AllowMethods](#sam-api-corsconfiguration-allowmethods): String [AllowOrigin](#sam-api-corsconfiguration-alloworigin): String [MaxAge](#sam-api-corsconfiguration-maxage): String ``` ## Properties `AllowCredentials` 表示是否允许请求包含凭证的布尔值。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `AllowHeaders` 允许的标头字符串。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `AllowMethods` 包含允许的 HTTP 方法的字符串。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `AllowOrigin` 允许的源字符串。这可以是字符串格式的逗号分隔的列表。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `MaxAge` 包含缓存 CORS 预检请求的秒数的字符串。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 ## 示例 ### CorsConfiguration CORS 配置示例。这只是 AWS SAM 模板文件的一部分，其中显示了配置了 CORS 的[AWS::Serverless::Api](sam-resource-api.md)定义和. [AWS::Serverless::Function](sam-resource-function.md) 如果您使用 Lambda 代理集成或 HTTP 代理集成，则您的后端必须返回 `Access-Control-Allow-Origin`、`Access-Control-Allow-Methods` 和 `Access-Control-Allow-Headers` 标头。 #### YAML ``` Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: AllowMethods: "'POST, GET'" AllowHeaders: "'X-Forwarded-For'" AllowOrigin: "'https://example.com'" MaxAge: "'600'" AllowCredentials: true ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | import json def handler(event, context): return { 'statusCode': 200, 'headers': { 'Access-Control-Allow-Headers': 'Content-Type', 'Access-Control-Allow-Origin': 'https://example.com', 'Access-Control-Allow-Methods': 'POST, GET' }, 'body': json.dumps('Hello from Lambda!') } ``` # DomainConfiguration 为 API 配置自定义域。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [AccessAssociation](#sam-api-domainconfiguration-domainaccessassociation): DomainAccessAssociation [BasePath](#sam-api-domainconfiguration-basepath): List [CertificateArn](#sam-api-domainconfiguration-certificatearn): String [DomainName](#sam-api-domainconfiguration-domainname): String [EndpointConfiguration](#sam-api-domainconfiguration-endpointconfiguration): String [MutualTlsAuthentication](#sam-api-domainconfiguration-mutualtlsauthentication): [MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication) [NormalizeBasePath](#sam-api-domainconfiguration-normalizebasepath): Boolean [OwnershipVerificationCertificateArn](#sam-api-domainconfiguration-ownershipverificationcertificatearn): String [Policy: ](#sam-api-domainconfiguration-policy)Json [Route53](#sam-api-domainconfiguration-route53): Route53Configuration [SecurityPolicy](#sam-api-domainconfiguration-securitypolicy): String ``` ## Properties `AccessAssociation` 生成 ` AWS::ApiGateway::DomainNameAccessAssociation` 资源所需的配置。 AWS SAM 设置此属性时会生成[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html)资源。有关生成的 CloudFormation 资源的信息，请参阅[生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。 *类型*：[DomainAccessAssociation](sam-property-api-domainaccessassociation.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `BasePath` 要使用 Amazon API Gateway 域名配置的基本路径列表。 *类型*：列表 *必需*：否 *默认值*：/ *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::BasePathMapping`资源的`[BasePath](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-basepathmapping.html#cfn-apigateway-basepathmapping-basepath)`属性。 AWS SAM 创建多个`AWS::ApiGateway::BasePathMapping`资源，每个资源在此属性中`BasePath`指定一个。 `CertificateArn` AWS 托管证书的亚马逊资源名称 (ARN) 此域名的终端节点。 AWS Certificate Manager 是唯一支持的来源。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性类似于`AWS::ApiGateway::DomainName`资源的`[CertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-certificatearn)`属性。如果设置`EndpointConfiguration`为`REGIONAL`（默认值），则`CertificateArn`映射到 [RegionalCertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-regionalcertificatearn)in `AWS::ApiGateway::DomainName`。如果设置`EndpointConfiguration`为`EDGE`，则`CertificateArn`映射到 [CertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-certificatearn)in `AWS::ApiGateway::DomainName`。如果设置`EndpointConfiguration`为`PRIVATE`，则此属性将传递给 [AWS::ApiGateway::DomainNameV2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2) 资源。 *其他说明*：对于终`EDGE`端节点，您必须在`us-east-1` AWS 区域中创建证书。 `DomainName` API Gateway API 的自定义域名。不支持大写字母。 AWS SAM 设置此属性时会生成[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html)资源。有关此场景的更多信息，请参阅[DomainName 属性已指定](sam-specification-generated-resources-api.md#sam-specification-generated-resources-api-domain-name)。有关生成的 CloudFormation 资源的信息，请参阅[生成的 CloudFormation 资源用于 AWS SAM](sam-specification-generated-resources.md)。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::DomainName`资源的`[DomainName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-domainname)`属性，或者在设置为[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)时传递给 EndpointConfiguration 该属性`PRIVATE`。 `EndpointConfiguration` 定义要映射到自定义域的 API Gateway 端点的类型。此属性的值决定了该`CertificateArn`属性的映射方式 CloudFormation。 *有效值*：`EDGE`、`REGIONAL` 或 `PRIVATE` *类型*：字符串 *必需*：否 *默认值*：`REGIONAL` *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `MutualTlsAuthentication` 自定义域名的相互传输层安全性协议（TLS）身份验证配置。 *类型*：[MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication) *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::DomainName`资源的`[MutualTlsAuthentication](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-mutualtlsauthentication)`属性。 `NormalizeBasePath` 表示 `BasePath` 属性定义的基本路径中是否允许非字母数字字符。如果设置为 `True`，则将从基本路径中移除非字母数字字符。针对 `BasePath` 属性使用 `NormalizeBasePath`。 *类型*：布尔值 *必需*：否 *默认值*：True *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `OwnershipVerificationCertificateArn` ACM 颁发的用于验证自定义域所有权的公有证书的 ARN。只有在配置双向 TLS 并且为 `CertificateArn` 指定了 ACM 导入的或私有 CA 证书 ARN 时才需要。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::DomainName`资源的`[OwnershipVerificationCertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-ownershipverificationcertificatearn)`属性。 `Policy` 要附加到该 AP Gateway 域名的 IAM 策略。仅当 `EndpointConfiguration` 设置为 `PRIVATE` 时适用。 *类型*：Json *必需*：否 *CloudFormation 兼容性*：当设置为时`EndpointConfiguration`，此`Policy`属性将直接传递给`AWS::ApiGateway::DomainNameV2`资源的属性`PRIVATE`。有关有效政策文件的示例，请参阅 [AWS::ApiGateway::DomainNameV2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)。 `Route53` 定义 Amazon Route 53 配置。 *类型*：[Route53Configuration](sam-property-api-route53configuration.md) *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `SecurityPolicy` 此域名的 TLS 版本加密码套件。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::DomainName`资源的`[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-securitypolicy)`属性，或者在设置为[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)时传递给`EndpointConfiguration`该属性`PRIVATE`。对于`PRIVATE` 端点，仅支持 TLS\$11\$12。 ## 示例 ### DomainName DomainName 示例 #### YAML ``` Domain: DomainName: www.example.com CertificateArn: arn-example EndpointConfiguration: EDGE Route53: HostedZoneId: Z1PA6795UKMFR9 BasePath: - foo - bar ``` # DomainAccessAssociation 配置访问关联源与私有自定义域名之间的域访问关联。唯一支持的访问关联源是 VPC 端点 ID。有关更多信息，请参阅 [API Gateway APIs 中的私有自定义域名](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html)。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` VpcEndpointId: String ``` ## Properties `VpcEndpointId` 与 API Gateway VPC 服务关联的 VPC 接口端点的端点 ID。 *类型*：字符串 *是否必需*：是 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::DomainNameAccessAssociation`资源的`[ AccessAssociationSource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnameaccessassociation.html#cfn-apigateway-domainnameaccessassociation-accessassociationsource)`属性。 # Route53Configuration 为 API 配置 Route53 记录集。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [DistributionDomainName](#sam-api-route53configuration-distributiondomainname): String [EvaluateTargetHealth](#sam-api-route53configuration-evaluatetargethealth): Boolean [HostedZoneId](#sam-api-route53configuration-hostedzoneid): String [HostedZoneName](#sam-api-route53configuration-hostedzonename): String [IpV6](#sam-api-route53configuration-ipv6): Boolean Region: String SetIdentifier: String VpcEndpointDomainName: String VpcEndpointHostedZoneId: String ``` ## Properties `DistributionDomainName` 配置 API 自定义域名的自定义分配。 *类型*：字符串 *必需*：否 *默认*：使用 API Gateway 分配。 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup AliasTarget`资源的`[DNSName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-aliastarget-1.html#cfn-route53-aliastarget-dnshostname)`属性。 *其他说明*：[CloudFront分配](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html)的域名。 `EvaluateTargetHealth` 如果 EvaluateTargetHealth 为 true，则别名记录将继承引用 AWS 资源的运行状况，例如 Elastic Load Balancing 负载均衡器或托管区域中的其他记录。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup AliasTarget`资源的`[EvaluateTargetHealth](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-aliastarget.html#cfn-route53-aliastarget-evaluatetargethealth)`属性。 *其他说明*：当别名目标为 CloudFront 分布时，您不能 EvaluateTargetHealth 将其设置为 true。 `HostedZoneId` 要在其中创建记录的托管区的 ID。指定 `HostedZoneName` 或 `HostedZoneId`，但不能同时指定两者。如果您拥有多个使用相同域名的托管区域，则必须使用 `HostedZoneId` 指定托管区。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup RecordSet`资源的`[HostedZoneId](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-hostedzoneid)`属性。 `HostedZoneName` 要在其中创建记录的托管区的名称。指定 `HostedZoneName` 或 `HostedZoneId`，但不能同时指定两者。如果您拥有多个使用相同域名的托管区域，则必须使用 `HostedZoneId` 指定托管区。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup RecordSet`资源的`[HostedZoneName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-hostedzonename)`属性。 `IpV6` 设置此属性后，将 AWS SAM 创建一个`AWS::Route53::RecordSet`资源并将提供的资源的 [Type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset.html#cfn-route53-recordset-type) 设置`AAAA`为 HostedZone。 *类型*：布尔值 *必需*：否 *CloudFormation 兼容性*：此属性是独有的 AWS SAM ，没有 CloudFormation 等效属性。 `Region` *仅限基于延迟的资源记录集*：您创建此资源记录集所引用的资源的亚马逊 EC2 区域。资源通常是 AWS 资源，例如 EC2 实例或 ELB 负载均衡器，并由 IP 地址或 DNS 域名引用，具体取决于记录类型。当 Amazon Route 53 收到针对您已为其创建延迟资源记录集的域名和类型的 DNS 查询时，Route 53 会选择最终用户与关联亚马逊 EC2 地区之间延迟最低的延迟资源记录集。然后，Route 53 会返回与所选资源记录集相关的值。注意以下几点： + 您只能为每个延迟资源记录集指定一个 `ResourceRecord`。 + 您只能为每个 Amazon EC2 地区创建一个延迟资源记录集。 + 您无需为所有 Amazon EC2 区域创建延迟资源记录集。Route 53 会从您已创建延迟资源记录集的区域中选择延迟性能最佳的区域。 + 您不能创建 `Name` 和 `Type` 元素的值与延迟资源记录集相同的非延迟资源记录集。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup``RecordSet`数据类型的`[ Region](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-region)`属性。 `SetIdentifier` *具有简单策略以外的路由策略的资源记录集：*用于区分具有相同名称和类型组合的多个资源记录集的标识符，如名为 acme.example.com 且类型为 A 的多个加权资源记录集。在一组具有相同名称和类型的资源记录集中，每个资源记录集的 `SetIdentifier` 值必须唯一。有关路由策略的信息，请参阅*《Amazon Route 53 开发人员指南》*中的[选择路由策略](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html)。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSetGroup``RecordSet`数据类型的`[ SetIdentifier](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-1.html#cfn-route53-recordset-setidentifier)`属性。 `VpcEndpointDomainName` 与 API Gateway VPC 服务关联的 VPC 接口端点的 DNS 名称。仅私有域需要该属性。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSet``AliasTarget`字段的`[DNSName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-aliastarget.html)`属性。 `VpcEndpointHostedZoneId` 与 API Gateway VPC 服务关联的 VPC 接口端点的托管区。仅私有域需要该属性。 *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::Route53::RecordSet``AliasTarget`字段的`[HostedZoneId](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-aliastarget.html)`属性。 ## 示例 ### 基本示例在此示例中，我们为 API 配置了自定义域和 Route 53 记录集。 #### YAML ``` Resources: MyApi: Type: AWS::Serverless::Api Properties: StageName: Prod Domain: DomainName: www.example.com CertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890 EndpointConfiguration: REGIONAL Route53: HostedZoneId: ABCDEFGHIJKLMNOP ``` # EndpointConfiguration REST API 的端点类型。 ## 语法要在 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。 ### YAML ``` [IpAddressType](#sam-api-endpointconfiguration-ipaddresstype): String [Type](#sam-api-endpointconfiguration-type): String [VPCEndpointIds](#sam-api-endpointconfiguration-vpcendpointids): List ``` ## Properties `IpAddressType` 可以调用 API 的 IP 地址类型 (RestApi)。 *有效值*：`ipv4` 或 `dualstack` *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``EndpointConfiguration`数据类型的`[IpAddressType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-ipaddresstype)`属性。 `Type` REST API 的端点类型。 *有效值*：`EDGE` 或 `REGIONAL` 或 `PRIVATE` *类型*：字符串 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``EndpointConfiguration`数据类型的`[Types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-types)`属性。 `VPCEndpointIds` 用于创建 Route53 IDs 别名的 REST API 的 VPC 终端节点列表。 *类型*：列表 *必需*：否 *CloudFormation 兼容性*：此属性直接传递给`AWS::ApiGateway::RestApi``EndpointConfiguration`数据类型的`[VpcEndpointIds](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html#cfn-apigateway-restapi-endpointconfiguration-vpcendpointids)`属性。 ## 示例 ### EndpointConfiguration 端点配置示例 #### YAML ``` EndpointConfiguration: Type: PRIVATE VPCEndpointIds: - vpce-123a123a - vpce-321a321a ```