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

# 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}}
  [EndpointAccessMode](#sam-api-endpointaccessmode): {{String}}
  [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}}
  [SecurityPolicy](#sam-api-securitypolicy): {{String}}
  [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)。 **  
*類型*：字串 \| [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。屬性包括對應 `EventSource`的 Api `BinaryMediaTypes` `Cors` `GatewayResponses`類型 `Auth`、`Models`、、 和 `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 定義匯入範本。  
*類型*：字串 \| [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)` 屬性。巢狀組態屬性的名稱不同。

 `EndpointAccessMode`   <a name="sam-api-endpointaccessmode"></a>
REST API 端點的存取模式。使用增強型安全政策時為必要 （字首為 )`SecurityPolicy_`。  
*有效值*：`STRICT` 或 `BASIC`  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 `[EndpointAccessMode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointaccessmode)` 屬性。

 `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 的閘道回應。閘道回應是由 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)屬性。

 `SecurityPolicy`   <a name="sam-api-securitypolicy"></a>
REST API 的 TLS 版本加上密碼套件。使用增強型安全政策 （字首為 `SecurityPolicy>`) 時，您還必須設定 `EndpointAccessMode`。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::RestApi` 資源的 `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-securitypolicy)` 屬性。

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