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

# AWS::Serverless::Api
<a name="sam-resource-api"></a>

建立可透過 HTTPS 端點叫用之 Amazon API Gateway 資源和方法的集合。

資源[AWS::Serverless::Api](#sam-resource-api)不需要明確新增至無 AWS 伺服器應用程式定義範本。此類型的資源是從在範本中未參考 [AWS::Serverless::Api](#sam-resource-api) 資源所定義[AWS::Serverless::Function](sam-resource-function.md)資源上定義的 Api 事件聯集隱含建立的。

應使用 [AWS::Serverless::Api](#sam-resource-api) 資源來定義和記錄使用 OpenApi 的 API，以便更能夠設定基礎 Amazon API Gateway 資源。

我們建議您使用 CloudFormation 勾點或 IAM 政策來驗證 API Gateway 資源是否已連接授權方，以控制對它們的存取。

如需使用 CloudFormation 勾點的詳細資訊，請參閱 *CloudFormation CLI 使用者指南*中的[註冊勾點](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html)和 [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub 儲存庫。

如需使用 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)。

## 語法
<a name="sam-resource-api-syntax"></a>

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

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

```
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
<a name="sam-resource-api-properties"></a>

 `AccessLogSetting`   <a name="sam-api-accesslogsetting"></a>
設定階段的存取日誌設定。  
*類型*：[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`   <a name="sam-api-alwaysdeploy"></a>
即使未偵測到 API 的變更，也一律部署 API。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `ApiKeySourceType`   <a name="sam-api-apikeysourcetype"></a>
根據用量計畫進行量測請求的 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`   <a name="sam-api-auth"></a>
設定授權以控制對 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`   <a name="sam-api-binarymediatypes"></a>
您的 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`   <a name="sam-api-cacheclusterenabled"></a>
指出是否已為階段啟用快取。若要快取回應，您還必須在 `true`下`CachingEnabled`將 設定為 `MethodSettings`。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::Stage` 資源的 `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` 屬性。

 `CacheClusterSize`   <a name="sam-api-cacheclustersize"></a>
階段的快取叢集大小。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::Stage` 資源的 `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)` 屬性。

 `CanarySetting`   <a name="sam-api-canarysetting"></a>
將 Canary 設定設定為一般部署的階段。  
*類型*：[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`   <a name="sam-api-cors"></a>
管理所有 API Gateway APIs 的跨來源資源共用 (CORS)。指定要允許做為字串的網域，或指定具有其他 Cors 組態的字典。  
CORS 需要 AWS SAM 修改您的 OpenAPI 定義。在 中建立內嵌 OpenAPI 定義`DefinitionBody`以開啟 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`   <a name="sam-api-definitionbody"></a>
描述 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)` 屬性。如果提供特定屬性，內容可能會在傳遞至 CloudFormation 之前插入或修改至 DefinitionBody。屬性包括 `Auth`、`BinaryMediaTypes`、`Models`、、`Cors``GatewayResponses`，以及對應 `EventSource`的 Api 類型 `AWS::Serverless::Function`。

 `DefinitionUri`   <a name="sam-api-definitionuri"></a>
定義 API 之 OpenAPI 文件的 Amazon S3 Uri、本機檔案路徑或位置物件。此屬性參考的 Amazon S3 物件必須是有效的 OpenAPI 檔案。如果既未指定`DefinitionUri`也`DefinitionBody`未指定，SAM 會根據範本組態`DefinitionBody`為您產生 。  
如果提供本機檔案路徑，範本必須經過包含 `sam deploy`或 `sam package`命令的工作流程，才能正確轉換定義。  
參考的外部 OpenApi 檔案不支援內部函數`DefinitionUri`。使用 `DefinitionBody` 屬性搭配[包含轉換](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html)，將 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`   <a name="sam-api-description"></a>
Api 資源的描述。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)` 屬性。

 `DisableExecuteApiEndpoint`   <a name="sam-api-disableexecuteapiendpoint"></a>
指定用戶端是否可以使用預設 `execute-api` 端點叫用您的 API。根據預設，用戶端可以使用預設的 叫用您的 API`https://{api_id}.execute-api.{region}.amazonaws.com`。如要要求用戶端使用自訂網域名稱來叫用 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`   <a name="sam-api-domain"></a>
設定此 API Gateway API 的自訂網域。  
*類型*：[DomainConfiguration](sam-property-api-domainconfiguration.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `EndpointConfiguration`   <a name="sam-api-endpointconfiguration"></a>
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`   <a name="sam-api-failonwarnings"></a>
指定在遇到警告時是否要轉返 API 建立 (`true`) 與否 (`false`)。預設值為 `false`。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)` 屬性。

 `GatewayResponses`   <a name="sam-api-gatewayresponses"></a>
設定 API 的閘道回應。Gateway 回應是由 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`   <a name="sam-api-mergedefinitions"></a>
AWS SAM 會從 API 事件來源產生OpenAPI規格。指定 AWS SAM `true`讓 將此合併到 `AWS::Serverless::Api` 資源中定義的內嵌OpenAPI規格。指定 `false`不合併。  
`MergeDefinitions` 需要`AWS::Serverless::Api`定義 的 `DefinitionBody` 屬性。 `MergeDefinitions` 與 的 `DefinitionUri` 屬性不相容`AWS::Serverless::Api`。  
*預設值*：`false`  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `MethodSettings`   <a name="sam-api-methodsettings"></a>
設定 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`   <a name="sam-api-minimumcompressionsize"></a>
允許根據用戶端的 Accept-Encoding 標頭壓縮回應內文。當回應內文大小大於或等於您設定的閾值時，就會觸發壓縮。主體大小閾值上限為 10 MB (10，485，760 個位元組）。- 支援下列壓縮類型：gzip、deflate 和 identity。  
*類型*：整數  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)` 屬性。

 `Mode`   <a name="sam-api-mode"></a>
只有當您使用 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`   <a name="sam-api-models"></a>
您的 API 方法要使用的結構描述。您可以使用 JSON 或 YAML 描述這些結構描述。如需範例模型，請參閱此頁面底部的範例一節。  
*類型*：映射  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Name`   <a name="sam-api-name"></a>
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`   <a name="sam-api-openapiversion"></a>
要使用的 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`  <a name="sam-api-propagatetags"></a>
指出是否要將標籤從 `Tags` 屬性傳遞至您[AWS::Serverless::Api](sam-specification-generated-resources-api.md)產生的資源。指定 `True` 在產生的資源中傳播標籤。  
*類型*：布林值  
*必要*：否  
*預設*：`False`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

`Policy`  <a name="sam-api-policy"></a>
包含 API 許可的政策文件。若要設定政策的 ARN，請使用 `!Join` 內部函數搭配 `""` 做為分隔符號，並使用值 `"execute-api:/"` 和 `"*"`。  
*類型*：JSON  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 [ 政策](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy)屬性。

 `StageName`   <a name="sam-api-stagename"></a>
API Gateway 做為叫用統一資源識別符 (URI) 中第一個路徑區段的階段名稱。  
若要參考階段資源，請使用 `<api-logical-id>.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`   <a name="sam-api-tags"></a>
映射 （字串到字串），指定要新增至此 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 中的標籤屬性包含 Key：Value 對；在 CloudFormation 中包含標籤物件清單。

 `TracingEnabled`   <a name="sam-api-tracingenabled"></a>
指出是否已針對階段啟用使用 X-Ray 的主動追蹤。如需 X-Ray 的詳細資訊，請參閱《 [ APIs Gateway 開發人員指南》中的使用 X-Ray 追蹤使用者對 REST API 的請求](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 name="sam-api-variables"></a>
定義階段變數的映射 （字串到字串），其中變數名稱是索引鍵，而變數值是值。變數名稱限制為英數字元。值必須符合下列規則表達式：`[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)` 屬性。

## 傳回值
<a name="sam-resource-api-return-values"></a>

### Ref
<a name="sam-resource-api-return-values-ref"></a>

當將此資源的邏輯 ID 提供給`Ref`內部 函數時，它會傳回基礎 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
<a name="sam-resource-api-return-values-fn--getatt"></a>

`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`  <a name="RootResourceId-fn::getatt"></a>
`RestApi` 資源的根資源 ID，例如：`a0bc123d4e`。

## 範例
<a name="sam-resource-api--examples"></a>

### SimpleApiExample
<a name="sam-resource-api--examples--simpleapiexample"></a>

Hello World AWS SAM 範本檔案，其中包含具有 API 端點的 Lambda 函數。這是運作中無伺服器應用程式的完整 AWS SAM 範本檔案。

#### YAML
<a name="sam-resource-api--examples--simpleapiexample--yaml"></a>

```
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
<a name="sam-resource-api--examples--apicorsexample"></a>

具有外部 Swagger 檔案中定義之 API 的 AWS SAM 範本程式碼片段，以及 Lambda 整合和 CORS 組態。這只是 AWS SAM 範本檔案的一部分，顯示 [AWS::Serverless::Api](#sam-resource-api)定義。

#### YAML
<a name="sam-resource-api--examples--apicorsexample--yaml"></a>

```
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
<a name="sam-resource-api--examples--apicognitoauthexample"></a>

具有 API 的 AWS SAM 範本程式碼片段，該 API 使用 Amazon Cognito 來授權對 API 的請求。這只是 AWS SAM 範本檔案的一部分，顯示 [AWS::Serverless::Api](#sam-resource-api)定義。

#### YAML
<a name="sam-resource-api--examples--apicognitoauthexample--yaml"></a>

```
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]
```

### ApiModelsExample
<a name="sam-resource-api--examples--apimodelsexample"></a>

包含模型結構描述之 API 的 AWS SAM 範本程式碼片段。這只是 AWS SAM 範本檔案的一部分，顯示具有兩個模型結構描述[AWS::Serverless::Api](#sam-resource-api)的定義。

#### YAML
<a name="sam-resource-api--examples--apimodelsexample--yaml"></a>

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

### 快取範例
<a name="sam-resource-api--examples--caching-example"></a>

Hello World AWS SAM 範本檔案，其中包含具有 API 端點的 Lambda 函數。API 已針對一個資源和方法啟用快取。如需快取的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的啟用 API 快取以增強回應能力](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html)。 **

#### YAML
<a name="sam-resource-api--examples--caching-example--yaml"></a>

```
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 範例的自訂網域
<a name="sam-resource-api--examples--custom-domain-example"></a>

Hello World AWS SAM 範本檔案，其中包含與私有網域對應之 API 端點的 Lambda 函數。範本會在 VPC 端點與私有網域之間建立網域存取關聯。如需詳細資訊，請參閱 [API Gateway 中私有 APIs的自訂網域名稱](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html)。

#### YAML
<a name="sam-resource-api--examples--custom-domain-example--yaml"></a>

```
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
<a name="sam-property-api-apiauth"></a>

設定授權以控制對 API Gateway API 的存取。

如需使用 設定存取權的詳細資訊和範例， AWS SAM 請參閱 [使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。

## 語法
<a name="sam-property-api-apiauth-syntax"></a>

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

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

```
  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
<a name="sam-property-api-apiauth-properties"></a>

 `AddApiKeyRequiredToCorsPreflight`   <a name="sam-api-apiauth-addapikeyrequiredtocorspreflight"></a>
如果已設定 `ApiKeyRequired`和 `Cors` 屬性，則設定`AddApiKeyRequiredToCorsPreflight`會導致 API 金鑰新增至 `Options` 屬性。  
*類型*：布林值  
*必要*：否  
*預設*：`True`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `AddDefaultAuthorizerToCorsPreflight`   <a name="sam-api-apiauth-adddefaultauthorizertocorspreflight"></a>
如果已設定 `DefaultAuthorizer`和 `Cors` 屬性，則設定`AddDefaultAuthorizerToCorsPreflight`會導致預設授權方新增至 OpenAPI 區段中的 `Options` 屬性。  
*類型*：布林值  
*必要*：否  
*預設*：True  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `ApiKeyRequired`   <a name="sam-api-apiauth-apikeyrequired"></a>
如果設定為 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`   <a name="sam-api-apiauth-authorizers"></a>
用於控制 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`   <a name="sam-api-apiauth-defaultauthorizer"></a>
指定 API Gateway API 的預設授權方，該 API Gateway API 預設將用於授權 API 呼叫。  
如果與此 API 相關聯之函數的 Api EventSource 設定為使用 IAM 許可，則此屬性必須設定為 `AWS_IAM`，否則會產生錯誤。
*類型：*字串  
*必要*：否  
*預設*：無  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `InvokeRole`   <a name="sam-api-apiauth-invokerole"></a>
將所有資源和方法的整合登入資料設定為此值。  
`CALLER_CREDENTIALS` 會映射到 `arn:aws:iam:::<user>/`，使用呼叫者登入資料來叫用端點。  
*有效值*：`CALLER_CREDENTIALS`、`NONE`、 `IAMRoleArn`  
*類型：*字串  
*必要*：否  
*預設*：`CALLER_CREDENTIALS`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `ResourcePolicy`   <a name="sam-api-apiauth-resourcepolicy"></a>
設定 API 上所有方法和路徑的資源政策。  
*類型*：[ResourcePolicyStatement](sam-property-api-resourcepolicystatement.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。  
*其他備註*：您也可以`AWS::Serverless::Function`使用 在個別 上定義此設定[ApiFunctionAuth](sam-property-function-apifunctionauth.md)。對於具有 APIs，這是必要的`EndpointConfiguration: PRIVATE`。

 `UsagePlan`   <a name="sam-api-apiauth-usageplan"></a>
設定與此 API 相關聯的用量計劃。如需用量計劃的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的使用 API 金鑰建立和使用用量計劃](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 **  
此 AWS SAM 屬性會在設定此屬性時產生三個額外的 CloudFormation 資源：[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)和 [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 同等屬性。

## 範例
<a name="sam-property-api-apiauth--examples"></a>

### CognitoAuth
<a name="sam-property-api-apiauth--examples--cognitoauth"></a>

Cognito 驗證範例

#### YAML
<a name="sam-property-api-apiauth--examples--cognitoauth--yaml"></a>

```
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
<a name="sam-property-api-apiauth--examples--aws_iam"></a>

AWS IAM 範例

#### YAML
<a name="sam-property-api-apiauth--examples--cognitoauth--yaml"></a>

```
Auth:
  Authorizers: AWS_IAM
```

# ApiUsagePlan
<a name="sam-property-api-apiusageplan"></a>

設定 API Gateway API 的用量計劃。如需用量計劃的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的使用 API 金鑰建立和使用用量計劃](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 **

## 語法
<a name="sam-property-api-apiusageplan-syntax"></a>

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

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

```
  [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
<a name="sam-property-api-apiusageplan-properties"></a>

 `CreateUsagePlan`   <a name="sam-api-apiusageplan-createusageplan"></a>
決定此用量計劃的設定方式。有效值為 `PER_API`、`SHARED` 和 `NONE`。  
`PER_API` 會建立此 API 特有的 [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-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) 資源。這些資源的邏輯 IDs `<api-logical-id>UsagePlanKey`分別為 `<api-logical-id>UsagePlan`、 `<api-logical-id>ApiKey`和 。  
`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-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) 資源，這些資源在相同 AWS SAM 範本`CreateUsagePlan: SHARED`中也有 的任何 API 之間共用。這些資源的邏輯 IDs `ServerlessUsagePlanKey`分別為 `ServerlessUsagePlan`、 `ServerlessApiKey`和 。如果您使用此選項，建議您僅針對一個 API 資源新增此用量計劃的其他組態，以避免衝突的定義和不確定狀態。  
`NONE` 會停用與此 API 建立或關聯用量計劃。只有在 中指定 `PER_API` `SHARED`或 時，才需要這樣做[AWS SAM 範本的全域區段](sam-specification-template-anatomy-globals.md)。  
*有效值*：`PER_API`、`SHARED` 與 `NONE`  
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Description`   <a name="sam-api-apiusageplan-description"></a>
用量計劃的描述。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-description)` 屬性。

 `Quota`   <a name="sam-api-apiusageplan-quota"></a>
設定使用者可在指定間隔內發出的請求數。  
*類型*：[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`   <a name="sam-api-apiusageplan-tags"></a>
要與用量計劃關聯的任意標籤陣列 (金鑰值對)。  
此屬性使用 [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`   <a name="sam-api-apiusageplan-throttle"></a>
設定整體請求速率 (每秒平均請求數) 和高載容量。  
*類型*：[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`   <a name="sam-api-apiusageplan-usageplanname"></a>
用量計劃的名稱。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[UsagePlanName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-usageplanname)` 屬性。

## 範例
<a name="sam-property-api-apiusageplan--examples"></a>

### UsagePlan
<a name="sam-property-api-apiusageplan--examples--usageplan"></a>

以下是用量計劃範例。

#### YAML
<a name="sam-property-api-apiusageplan--examples--usageplan--yaml"></a>

```
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
<a name="sam-property-api-cognitoauthorizer"></a>

定義 Amazon Cognito 使用者集區授權方。

如需詳細資訊和範例，請參閱 [使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。

## 語法
<a name="sam-property-api-cognitoauthorizer-syntax"></a>

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

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

```
  [AuthorizationScopes](#sam-api-cognitoauthorizer-authorizationscopes): List
  [Identity](#sam-api-cognitoauthorizer-identity): CognitoAuthorizationIdentity
  [UserPoolArn](#sam-api-cognitoauthorizer-userpoolarn): String
```

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

 `AuthorizationScopes`   <a name="sam-api-cognitoauthorizer-authorizationscopes"></a>
此授權方的授權範圍清單。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Identity`   <a name="sam-api-cognitoauthorizer-identity"></a>
此屬性可用於在 授權方的傳入請求`IdentitySource`中指定 。  
*類型*：[CognitoAuthorizationIdentity](sam-property-api-cognitoauthorizationidentity.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `UserPoolArn`   <a name="sam-api-cognitoauthorizer-userpoolarn"></a>
可以參考使用者集區/指定您要新增此 cognito 授權方的使用者集區  
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-cognitoauthorizer--examples"></a>

### CognitoAuth
<a name="sam-property-api-cognitoauthorizer--examples--cognitoauth"></a>

Cognito 驗證範例

#### YAML
<a name="sam-property-api-cognitoauthorizer--examples--cognitoauth--yaml"></a>

```
Auth:
  Authorizers:
    MyCognitoAuth:
      AuthorizationScopes:
        - scope1
        - scope2
      UserPoolArn:
        Fn::GetAtt:
          - MyCognitoUserPool
          - Arn
      Identity:
        Header: MyAuthorizationHeader
        ValidationExpression: myauthvalidationexpression
```

# CognitoAuthorizationIdentity
<a name="sam-property-api-cognitoauthorizationidentity"></a>

此屬性可用於在 授權方的傳入請求中指定 IdentitySource。如需 IdentitySource 的詳細資訊，請參閱 [ApiGateway 授權方 OpenApi 延伸](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。

## 語法
<a name="sam-property-api-cognitoauthorizationidentity-syntax"></a>

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

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

```
  [Header](#sam-api-cognitoauthorizationidentity-header): String
  [ReauthorizeEvery](#sam-api-cognitoauthorizationidentity-reauthorizeevery): Integer
  [ValidationExpression](#sam-api-cognitoauthorizationidentity-validationexpression): String
```

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

 `Header`   <a name="sam-api-cognitoauthorizationidentity-header"></a>
在 OpenApi 定義中指定授權的標頭名稱。  
*類型：*字串  
*必要*：否  
*預設*：授權  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `ReauthorizeEvery`   <a name="sam-api-cognitoauthorizationidentity-reauthorizeevery"></a>
存活期 (TTL) 期間 (秒)，指定 API Gateway 快取授權方結果的時間。如果您指定的值大於 0，則 API Gateway 會快取授權方回應。根據預設，API Gateway 會將此屬性設為 300。值的上限為 3600 (1 小時)。  
*類型*：整數  
*必要*：否  
*預設*：300  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `ValidationExpression`   <a name="sam-api-cognitoauthorizationidentity-validationexpression"></a>
指定驗證表達式以驗證傳入的 Identity  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-cognitoauthorizationidentity--examples"></a>

### CognitoAuthIdentity
<a name="sam-property-api-cognitoauthorizationidentity--examples--cognitoauthidentity"></a>

#### YAML
<a name="sam-property-api-cognitoauthorizationidentity--examples--cognitoauthidentity--yaml"></a>

```
Identity:
  Header: MyCustomAuthHeader
  ValidationExpression: Bearer.*
  ReauthorizeEvery: 30
```

# LambdaRequestAuthorizer
<a name="sam-property-api-lambdarequestauthorizer"></a>

設定 Lambda 授權方，以使用 Lambda 函數控制對 API 的存取。

如需詳細資訊和範例，請參閱 [使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。

## 語法
<a name="sam-property-api-lambdarequestauthorizer-syntax"></a>

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

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

```
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
<a name="sam-property-api-lambdarequestauthorizer-properties"></a>

 `DisableFunctionDefaultPermissions`   <a name="sam-api-lambdarequestauthorizer-disablefunctiondefaultpermissions"></a>
指定 `true` AWS SAM 以防止 自動建立 `AWS::Lambda::Permissions` 資源，在您的`AWS::Serverless::Api`資源和授權方 Lambda 函數之間佈建許可。  
*預設值*：`false`  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionArn`   <a name="sam-api-lambdarequestauthorizer-functionarn"></a>
指定提供 API 授權的 Lambda 函數的函數 ARN。  
AWS SAM 當 `FunctionArn` 針對 指定 時， 會自動建立 `AWS::Lambda::Permissions` 資源`AWS::Serverless::Api`。`AWS::Lambda::Permissions` 資源會在您的 API 和授權方 Lambda 函數之間佈建許可。
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionInvokeRole`   <a name="sam-api-lambdarequestauthorizer-functioninvokerole"></a>
將授權方憑證新增至 Lambda 授權方的 OpenApi 定義。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionPayloadType`   <a name="sam-api-lambdarequestauthorizer-functionpayloadtype"></a>
此屬性可用來定義 API 的 Lambda 授權方類型。  
*有效值*：`TOKEN` 或 `REQUEST`  
*類型：*字串  
*必要*：否  
*預設*：`TOKEN`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Identity`   <a name="sam-api-lambdarequestauthorizer-identity"></a>
此屬性可用於在 授權方的傳入請求`IdentitySource`中指定 。只有在 屬性設定為 時，才需要此`FunctionPayloadType`屬性`REQUEST`。  
*類型*：[LambdaRequestAuthorizationIdentity](sam-property-api-lambdarequestauthorizationidentity.md)  
*必要*：有條件  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-lambdarequestauthorizer--examples"></a>

### LambdaRequestAuth
<a name="sam-property-api-lambdarequestauthorizer--examples--lambdarequestauth"></a>

#### YAML
<a name="sam-property-api-lambdarequestauthorizer--examples--lambdarequestauth--yaml"></a>

```
Authorizers:
  MyLambdaRequestAuth:
    FunctionPayloadType: REQUEST
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
    FunctionInvokeRole:
      Fn::GetAtt:
        - LambdaAuthInvokeRole
        - Arn
    Identity:
      Headers:
        - Authorization1
```

# LambdaRequestAuthorizationIdentity
<a name="sam-property-api-lambdarequestauthorizationidentity"></a>

此屬性可用於在 授權方的傳入請求中指定 IdentitySource。如需 IdentitySource 的詳細資訊，請參閱 [ApiGateway 授權方 OpenApi 延伸](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。

## 語法
<a name="sam-property-api-lambdarequestauthorizationidentity-syntax"></a>

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

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

```
  [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
<a name="sam-property-api-lambdarequestauthorizationidentity-properties"></a>

 `Context`   <a name="sam-api-lambdarequestauthorizationidentity-context"></a>
將指定的內容字串轉換為格式 的映射表達式`context.contextString`。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Headers`   <a name="sam-api-lambdarequestauthorizationidentity-headers"></a>
將標頭轉換為格式 映射表達式的逗號分隔字串`method.request.header.name`。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `QueryStrings`   <a name="sam-api-lambdarequestauthorizationidentity-querystrings"></a>
將指定的查詢字串轉換為格式 映射表達式的逗號分隔字串`method.request.querystring.queryString`。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `ReauthorizeEvery`   <a name="sam-api-lambdarequestauthorizationidentity-reauthorizeevery"></a>
存活期 (TTL) 期間 (秒)，指定 API Gateway 快取授權方結果的時間。如果您指定的值大於 0，則 API Gateway 會快取授權方回應。根據預設，API Gateway 會將此屬性設為 300。值的上限為 3600 (1 小時)。  
*類型*：整數  
*必要*：否  
*預設*：300  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `StageVariables`   <a name="sam-api-lambdarequestauthorizationidentity-stagevariables"></a>
將指定的階段變數轉換為以逗號分隔的格式映射表達式字串`stageVariables.stageVariable`。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-lambdarequestauthorizationidentity--examples"></a>

### LambdaRequestIdentity
<a name="sam-property-api-lambdarequestauthorizationidentity--examples--lambdarequestidentity"></a>

#### YAML
<a name="sam-property-api-lambdarequestauthorizationidentity--examples--lambdarequestidentity--yaml"></a>

```
Identity:
  QueryStrings:
    - auth
  Headers:
    - Authorization
  StageVariables:
    - VARIABLE
  Context:
    - authcontext
  ReauthorizeEvery: 100
```

# LambdaTokenAuthorizer
<a name="sam-property-api-lambdatokenauthorizer"></a>

設定 Lambda 授權方，以使用 Lambda 函數控制對 API 的存取。

如需詳細資訊和範例，請參閱 [使用 AWS SAM 範本控制 API 存取](serverless-controlling-access-to-apis.md)。

## 語法
<a name="sam-property-api-lambdatokenauthorizer-syntax"></a>

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

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

```
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
<a name="sam-property-api-lambdatokenauthorizer-properties"></a>

 `DisableFunctionDefaultPermissions`   <a name="sam-api-lambdatokenauthorizer-disablefunctiondefaultpermissions"></a>
指定 `true` AWS SAM 以防止 自動建立 `AWS::Lambda::Permissions` 資源，在您的`AWS::Serverless::Api`資源和授權方 Lambda 函數之間佈建許可。  
*預設值*：`false`  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionArn`   <a name="sam-api-lambdatokenauthorizer-functionarn"></a>
指定提供 API 授權的 Lambda 函數的函數 ARN。  
AWS SAM 當 `FunctionArn` 針對 指定 時， 會自動建立 `AWS::Lambda::Permissions` 資源`AWS::Serverless::Api`。`AWS::Lambda::Permissions` 資源會在您的 API 和授權方 Lambda 函數之間佈建許可。
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionInvokeRole`   <a name="sam-api-lambdatokenauthorizer-functioninvokerole"></a>
將授權方憑證新增至 Lambda 授權方的 OpenApi 定義。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `FunctionPayloadType`   <a name="sam-api-lambdatokenauthorizer-functionpayloadtype"></a>
此屬性可用來定義 Api 的 Lambda 授權方類型。  
*有效值*：`TOKEN` 或 `REQUEST`  
*類型：*字串  
*必要*：否  
*預設*：`TOKEN`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Identity`   <a name="sam-api-lambdatokenauthorizer-identity"></a>
此屬性可用於在 授權方的傳入請求`IdentitySource`中指定 。只有在 屬性設定為 時，才需要此`FunctionPayloadType`屬性`REQUEST`。  
*類型*：[LambdaTokenAuthorizationIdentity](sam-property-api-lambdatokenauthorizationidentity.md)  
*必要*：有條件  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-lambdatokenauthorizer--examples"></a>

### LambdaTokenAuth
<a name="sam-property-api-lambdatokenauthorizer--examples--lambdatokenauth"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizer--examples--lambdatokenauth--yaml"></a>

```
Authorizers:
  MyLambdaTokenAuth:
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
    Identity:
      Header: MyCustomAuthHeader # OPTIONAL; Default: 'Authorization'
      ValidationExpression: mycustomauthexpression # OPTIONAL
      ReauthorizeEvery: 20 # OPTIONAL; Service Default: 300
```

### BasicLambdaTokenAuth
<a name="sam-property-api-lambdatokenauthorizer--examples--basiclambdatokenauth"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizer--examples--basiclambdatokenauth--yaml"></a>

```
Authorizers:
  MyLambdaTokenAuth:
    FunctionArn:
      Fn::GetAtt:
        - MyAuthFunction
        - Arn
```

# LambdaTokenAuthorizationIdentity
<a name="sam-property-api-lambdatokenauthorizationidentity"></a>

此屬性可用於在 授權方的傳入請求中指定 IdentitySource。如需 IdentitySource 的詳細資訊，請參閱 [ApiGateway 授權方 OpenApi 延伸](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-authorizer.html)。

## 語法
<a name="sam-property-api-lambdatokenauthorizationidentity-syntax"></a>

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

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

```
  [Header](#sam-api-lambdatokenauthorizationidentity-header): String
  [ReauthorizeEvery](#sam-api-lambdatokenauthorizationidentity-reauthorizeevery): Integer
  [ValidationExpression](#sam-api-lambdatokenauthorizationidentity-validationexpression): String
```

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

 `Header`   <a name="sam-api-lambdatokenauthorizationidentity-header"></a>
在 OpenApi 定義中指定授權的標頭名稱。  
*類型：*字串  
*必要*：否  
*預設*：授權  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `ReauthorizeEvery`   <a name="sam-api-lambdatokenauthorizationidentity-reauthorizeevery"></a>
存活期 (TTL) 期間 (秒)，指定 API Gateway 快取授權方結果的時間。如果您指定的值大於 0，則 API Gateway 會快取授權方回應。根據預設，API Gateway 會將此屬性設為 300。值的上限為 3600 (1 小時)。  
*類型*：整數  
*必要*：否  
*預設*：300  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `ValidationExpression`   <a name="sam-api-lambdatokenauthorizationidentity-validationexpression"></a>
指定驗證表達式以驗證傳入的 Identity。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

## 範例
<a name="sam-property-api-lambdatokenauthorizationidentity--examples"></a>

### LambdaTokenIdentity
<a name="sam-property-api-lambdatokenauthorizationidentity--examples--lambdatokenidentity"></a>

#### YAML
<a name="sam-property-api-lambdatokenauthorizationidentity--examples--lambdatokenidentity--yaml"></a>

```
Identity:
  Header: MyCustomAuthHeader
  ValidationExpression: Bearer.*
  ReauthorizeEvery: 30
```

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

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

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

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

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

```
  [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
<a name="sam-property-api-resourcepolicystatement-properties"></a>

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

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

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

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

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

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

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

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

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

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

#### YAML
<a name="sam-property-api-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
```

# ApiDefinition
<a name="sam-property-api-apidefinition"></a>

定義 API 的 OpenAPI 文件。

## 語法
<a name="sam-property-api-apidefinition-syntax"></a>

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

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

```
  [Bucket](#sam-api-apidefinition-bucket): String
  [Key](#sam-api-apidefinition-key): String
  [Version](#sam-api-apidefinition-version): String
```

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

 `Bucket`   <a name="sam-api-apidefinition-bucket"></a>
存放 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`   <a name="sam-api-apidefinition-key"></a>
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`   <a name="sam-api-apidefinition-version"></a>
對於版本控制的物件，則為 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)` 屬性。

## 範例
<a name="sam-property-api-apidefinition--examples"></a>

### 定義 Uri 範例
<a name="sam-property-api-apidefinition--examples--definition-uri-example"></a>

API 定義範例

#### YAML
<a name="sam-property-api-apidefinition--examples--definition-uri-example--yaml"></a>

```
DefinitionUri:
  Bucket: amzn-s3-demo-bucket-name
  Key: mykey-name
  Version: 121212
```

# CorsConfiguration
<a name="sam-property-api-corsconfiguration"></a>

管理 API Gateway APIs 的跨來源資源共用 (CORS)。指定要允許做為字串的網域，或指定具有其他 Cors 組態的字典。

**注意**  
CORS 需要 AWS SAM 修改您的 OpenAPI 定義。在 中建立內嵌 OpenAPI 定義`DefinitionBody`以開啟 CORS。如果在 OpenAPI 定義和屬性層級設定 `CorsConfiguration` ， 會 AWS SAM 合併它們。屬性層級優先於 OpenAPI 定義。

如需 CORS 的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的為 API Gateway REST API 資源啟用 CORS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html)。 **

## 語法
<a name="sam-property-api-corsconfiguration-syntax"></a>

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

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

```
  [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
<a name="sam-property-api-corsconfiguration-properties"></a>

 `AllowCredentials`   <a name="sam-api-corsconfiguration-allowcredentials"></a>
布林值，指出是否允許請求包含登入資料。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `AllowHeaders`   <a name="sam-api-corsconfiguration-allowheaders"></a>
要允許的標頭字串。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `AllowMethods`   <a name="sam-api-corsconfiguration-allowmethods"></a>
包含要允許之 HTTP 方法的字串。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `AllowOrigin`   <a name="sam-api-corsconfiguration-alloworigin"></a>
要允許的原始伺服器字串。這可以是字串格式的逗號分隔清單。  
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `MaxAge`   <a name="sam-api-corsconfiguration-maxage"></a>
包含快取 CORS 預檢請求秒數的字串。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

## 範例
<a name="sam-property-api-corsconfiguration--examples"></a>

### CorsConfiguration
<a name="sam-property-api-corsconfiguration--examples--corsconfiguration"></a>

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
<a name="sam-property-api-corsconfiguration--examples--corsconfiguration--yaml"></a>

```
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
<a name="sam-property-api-domainconfiguration"></a>

設定 API 的自訂網域。

## 語法
<a name="sam-property-api-domainconfiguration-syntax"></a>

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

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

```
  [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
<a name="sam-property-api-domainconfiguration-properties"></a>

 `AccessAssociation`   <a name="sam-api-domainconfiguration-domainaccessassociation"></a>
產生` 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`   <a name="sam-api-domainconfiguration-basepath"></a>
使用 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`   <a name="sam-api-domainconfiguration-certificatearn"></a>
此網域名稱端點 AWS 受管憑證的 Amazon Resource Name (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)`AWS::ApiGateway::DomainName`。如果 `EndpointConfiguration` 設定為 `EDGE`， 會`CertificateArn`映射至 中的 [CertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-certificatearn)`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`   <a name="sam-api-domainconfiguration-domainname"></a>
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)` 屬性，或在 EndpointConfiguration 設定為 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)時傳遞至 `PRIVATE`。

 `EndpointConfiguration`   <a name="sam-api-domainconfiguration-endpointconfiguration"></a>
定義要映射到自訂網域的 API Gateway 端點類型。此屬性的值會決定`CertificateArn`屬性的映射方式 CloudFormation。  
*有效值*：`EDGE`、`REGIONAL` 或 `PRIVATE`  
*類型：*字串  
*必要*：否  
*預設*：`REGIONAL`  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `MutualTlsAuthentication`   <a name="sam-api-domainconfiguration-mutualtlsauthentication"></a>
自訂網域名稱的相互 Transport Layer Security (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`   <a name="sam-api-domainconfiguration-normalizebasepath"></a>
指出`BasePath`屬性定義的 Basepaths 中是否允許非英數字元。設為 時`True`，會從 basepaths 中移除非英數字元。  
`NormalizeBasePath` 搭配 `BasePath` 屬性使用 。  
*類型*：布林值  
*必要*：否  
*預設*：True  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `OwnershipVerificationCertificateArn`   <a name="sam-api-domainconfiguration-ownershipverificationcertificatearn"></a>
ACM 核發之公有憑證的 ARN，用於驗證您的自訂網域的擁有權。只有在您設定交互 TLS 並指定 的 ACM 匯入或私有 CA 憑證 ARN 時才需要`CertificateArn`。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::DomainName` 資源的 `[OwnershipVerificationCertificateArn](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-ownershipverificationcertificatearn)` 屬性。

 `Policy`   <a name="sam-api-domainconfiguration-policy"></a>
要連接至 API Gateway 網域名稱的 IAM 政策。僅適用於 `EndpointConfiguration` 設定為 時`PRIVATE`。  
*類型*：Json  
*必要*：否  
*CloudFormation 相容性*：`EndpointConfiguration`當 設定為 時，此屬性會直接傳遞至 `AWS::ApiGateway::DomainNameV2` 資源的 `Policy` 屬性`PRIVATE`。如需有效政策文件的範例，請參閱 [AWS：：ApiGateway：：DomainNameV2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)。

 `Route53`   <a name="sam-api-domainconfiguration-route53"></a>
定義 Amazon Route 53 組態。  
*類型*：[Route53Configuration](sam-property-api-route53configuration.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `SecurityPolicy`   <a name="sam-api-domainconfiguration-securitypolicy"></a>
此網域名稱的 TLS 版本加上密碼套件。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::DomainName` 資源的 `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainname.html#cfn-apigateway-domainname-securitypolicy)` 屬性，或在 `EndpointConfiguration` 設定為 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-domainnamev2)時傳遞至 `PRIVATE`。對於`PRIVATE`端點，僅支援 TLS\$11\$12。

## 範例
<a name="sam-property-api-domainconfiguration--examples"></a>

### DomainName
<a name="sam-property-api-domainconfiguration--examples--domainname"></a>

DomainName 範例

#### YAML
<a name="sam-property-api-domainconfiguration--examples--domainname--yaml"></a>

```
Domain:
  DomainName: www.example.com
  CertificateArn: arn-example
  EndpointConfiguration: EDGE
  Route53:
    HostedZoneId: Z1PA6795UKMFR9
  BasePath:
    - foo
    - bar
```

# DomainAccessAssociation
<a name="sam-property-api-domainaccessassociation"></a>

設定存取關聯來源與私有自訂網域名稱之間的網域存取關聯。唯一支援的存取關聯來源是 VPC 端點 ID。如需詳細資訊，請參閱 [API Gateway 中私有 APIs的自訂網域名稱](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html)。

## 語法
<a name="sam-property-api-domainaccessassociation-syntax"></a>

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

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

```
 VpcEndpointId: String
```

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

 `VpcEndpointId`   <a name="sam-api-domainaccessassociation-vpcendpointid"></a>
與 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
<a name="sam-property-api-route53configuration"></a>

設定 API 的 Route53 記錄集。

## 語法
<a name="sam-property-api-route53configuration-syntax"></a>

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

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

```
  [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
<a name="sam-property-api-route53configuration-properties"></a>

 `DistributionDomainName`   <a name="sam-api-route53configuration-distributiondomainname"></a>
設定 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`   <a name="sam-api-route53configuration-evaluatetargethealth"></a>
當 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`   <a name="sam-api-route53configuration-hostedzoneid"></a>
託管區域的 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`   <a name="sam-api-route53configuration-hostedzonename"></a>
您要在其中建立記錄的託管區域名稱。  
請指定 `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`   <a name="sam-api-route53configuration-ipv6"></a>
設定此屬性時， 會 AWS SAM 建立`AWS::Route53::RecordSet`資源，並將提供的 HostedZone `AAAA`的 [Type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset.html#cfn-route53-recordset-type) 設定為 。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

`Region`  <a name="sam-api-route53configuration-region"></a>
*僅限延遲型資源記錄集：*您建立資源的 Amazon EC2 區域，這是此資源記錄集指向的資源。資源通常是 AWS 資源，例如 EC2 執行個體或 ELB 負載平衡器，並且根據記錄類型由 IP 地址或 DNS 網域名稱參考。  
當 Amazon Route 53 收到網域名稱和類型的 DNS 查詢，而您已建立其延遲資源記錄集時，Route 53 會選取最低延遲介於最終使用者與相關聯 Amazon 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`  <a name="sam-api-route53configuration-setidentifier"></a>
*沒有簡單路由政策的資源記錄集：*在具有相同名稱和類型組合的多個資源記錄集中用以區隔的識別碼，例如，多個加權資源記錄集名為 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`  <a name="sam-api-route53configuration-vpcendpointdomainname"></a>
與 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`  <a name="sam-api-route53configuration-vpcendpointhostedzoneid"></a>
與 API Gateway VPC 服務相關聯之 VPC 介面端點的託管區域 ID。只有私有網域才需要此屬性。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::Route53::RecordSet` `AliasTarget` 欄位的 `[HostedZoneId](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-route53-recordset-aliastarget.html)` 屬性。

## 範例
<a name="sam-property-api-route53configuration--examples"></a>

### 基本範例
<a name="sam-property-api-route53configuration--examples--route-53-configuration-example"></a>

在此範例中，我們為 API 設定自訂網域和 Route 53 記錄集。

#### YAML
<a name="sam-property-api-route53configuration--examples--route-53-configuration-example--yaml"></a>

```
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
<a name="sam-property-api-endpointconfiguration"></a>

REST API 的端點類型。

## 語法
<a name="sam-property-api-endpointconfiguration-syntax"></a>

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

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

```
  [IpAddressType](#sam-api-endpointconfiguration-ipaddresstype): String
  [Type](#sam-api-endpointconfiguration-type): String
  [VPCEndpointIds](#sam-api-endpointconfiguration-vpcendpointids): List
```

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

 `IpAddressType`   <a name="sam-api-endpointconfiguration-ipaddresstype"></a>
可叫用 API (RestApi) 的 IP 地址類型。  
*有效值*：`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`   <a name="sam-api-endpointconfiguration-type"></a>
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`   <a name="sam-api-endpointconfiguration-vpcendpointids"></a>
要建立 Route53 別名之 REST API 的 VPC 端點 IDs 清單。  
*類型：*清單  
*必要*：否  
*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)` 屬性。

## 範例
<a name="sam-property-api-endpointconfiguration--examples"></a>

### EndpointConfiguration
<a name="sam-property-api-endpointconfiguration--examples--endpointconfiguration"></a>

端點組態範例

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

```
EndpointConfiguration:
  Type: PRIVATE
  VPCEndpointIds:
    - vpce-123a123a
    - vpce-321a321a
```