翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

HTTPS エンドポイント経由で呼び出すことができる Amazon API Gateway リソースとメソッドのコレクションを作成します。

[AWS::Serverless::Api](#sam-resource-api) リソースを AWS サーバーレスアプリケーション定義テンプレートに明示的に追加する必要はありません。このタイプのリソースは、[AWS::Serverless::Function](sam-resource-function.md) リソースを参照しないテンプレートで定義された [AWS::Serverless::Api](#sam-resource-api) リソースに定義される 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 ゲートウェイデベロッパーガイド*」の「[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 リソースを CloudFormation リソース AWS SAM に変換します。詳細については、「[の生成済み 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}}
```

## プロパティ
<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 タイプのリストです。これは、API のバイナリサポートを有効化するために使用します。  
*タイプ*: リスト  
*必須:* いいえ  
*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>
ステージでキャッシュが有効化されているかどうかを示します。レスポンスをキャッシュするには、`MethodSettings` で `CachingEnabled` を `true` に設定することも必要です。  
型: ブール  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは、 `AWS::ApiGateway::Stage`リソースの `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)`プロパティに直接渡されます。

 `CacheClusterSize`   <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 API のクロスオリジンリソース共有 (CORS) を管理します。許可するドメインを文字列として指定するか、追加の CORS 設定でディクショナリを指定します。  
CORS では AWS SAM 、OpenAPI 定義を変更する必要があります。CORS を有効にするには、`DefinitionBody` の中でインライン OpenAPI 定義を作成します。
CORS の詳細については、*Amazon 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)を参照してください。  
*Type*: 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`、`Cors`、`GatewayResponses`、`Models`、および、対応する `AWS::Serverless::Function` 向けの `EventSource` タイプの API が含まれます。

 `DefinitionUri`   <a name="sam-api-definitionuri"></a>
Amazon S3 URI、ローカルファイルパス、または API を定義する OpenAPI ドキュメントのロケーションオブジェクトです。このプロパティが参照する Amazon S3 オブジェクトは、有効な OpenAPI ファイルである必要があります。`DefinitionUri` と `DefinitionBody` のどちらも指定されていない場合、SAM はテンプレート設定に基づいて `DefinitionBody` を生成します。  
ローカルファイルパスを指定する場合は、定義が適切に変換されるようにするために、テンプレートが `sam deploy` または `sam package` コマンドを含むワークフローを実行する必要があります。  
組み込み関数は、`DefinitionUri` で参照される外部 OpenApi ファイルではサポートされていません。その代わりに、[Include Transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) で `DefinitionBody` プロパティを使用して、OpenApi 定義をテンプレートにインポートします。  
*タイプ*: 文字列 \| [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 を呼び出すことができるかどうかを指定します。デフォルトでは、クライアントはデフォルトの `https://{api_id}.execute-api.{region}.amazonaws.com` を使用して API を呼び出すことができます。クライアントがカスタムドメイン名を使用して API を呼び出すように要求するには、`True` を指定します。  
型: ブール  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは、 `AWS::ApiGateway::RestApi`リソースの `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)`プロパティに似ています。これは `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` 拡張機能の `disableExecuteApiEndpoint` プロパティに直接渡され、`AWS::ApiGateway::RestApi` リソースの ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` プロパティに追加されます。

 `Domain`   <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 のゲートウェイレスポンスを設定します。ゲートウェイレスポンスは、直接、または Lambda オーソライザーを使用して返される API Gateway からのレスポンスです。詳細については、[ゲートウェイレスポンス用の 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::Serverless::Api` リソースで定義されているインラインOpenAPI仕様にこれを AWS SAM マージ`true`するには、 を指定します。マージしない場合は `false` を指定します。  
`MergeDefinitions` では、`AWS::Serverless::Api` の `DefinitionBody` プロパティを定義する必要があります。`MergeDefinitions` は `AWS::Serverless::Api` の `DefinitionUri` プロパティと互換性がありません。  
*デフォルト値*: `false`  
型: ブール  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。

 `MethodSettings`   <a name="sam-api-methodsettings"></a>
ロギング、メトリクス、CacheTTL、スロットリングなどの API ステージのすべての設定を行います。  
*タイプ*: [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) リソースタイプの[Mode](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 のバージョンです。これは、Swagger 仕様の `2.0`、または `3.0.1` のような OpenApi 3.0 バージョンの 1 つにすることができます。OpenAPI の詳細については、「[OpenAPI Specification](https://swagger.io/specification/)」を参照してください。  
 AWS SAM は`Stage`デフォルトで というステージを作成します。このプロパティに有効な値を設定すると、ステージ `Stage` が作成されなくなります。
*タイプ*: 文字列  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のプロパティはありません。

`PropagateTags`  <a name="sam-api-propagatetags"></a>
[AWS::Serverless::Api](sam-specification-generated-resources-api.md) が生成したリソースに `Tags` プロパティからのタグを渡すかどうかを指定します。`True` を指定して、生成されたリソースにタグを伝播します。  
型: ブール  
*必須:* いいえ  
*デフォルト*: `False`  
*CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。

`Policy`  <a name="sam-api-policy"></a>
API の許可が含まれるポリシードキュメント。ポリシーの ARN を設定するには、区切り記号および `"execute-api:/"` と `"*"` の値として、`""` と `!Join` 組み込み関数を使用します。  
*Type*: JSON  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは、 `AWS::ApiGateway::RestApi`リソースの [ Policy](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 が invoke Uniform Resource Identifier (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 の Tags プロパティは、キーバリューペアで構成されています。CloudFormation では、タグオブジェクトのリストで構成されています。

 `TracingEnabled`   <a name="sam-api-tracingenabled"></a>
このステージに X-Ray を使用したアクティブトレーシングが有効化されているかどうかを示します。X-Ray の詳細については、*API 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>

### 参照番号
<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>

API エンドポイントを持つ Lambda 関数を含む Hello World AWS SAM テンプレートファイル。これは、動作中のサーバーレスアプリケーションの完全な 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>

Lambda 統合と CORS 設定とともに、外部 Swagger ファイルで定義された API を持つ AWS SAM テンプレートスニペット。これは、[AWS::Serverless::Api](#sam-resource-api)定義を示す AWS SAM テンプレートファイルの一部にすぎません。

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

Amazon Cognito を使用して API に対するリクエストを承認する API を含む AWS SAM テンプレートスニペット。これは、[AWS::Serverless::Api](#sam-resource-api)定義を示す AWS SAM テンプレートファイルの一部にすぎません。

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

Models スキーマを含む API を含む AWS SAM テンプレートスニペット。これは AWS SAM テンプレートファイルの一部にすぎず、2 つのモデルスキーマを持つ[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>

API エンドポイントを持つ Lambda 関数を含む Hello World AWS SAM テンプレートファイル。API では、1 つのリソースとメソッドに対してキャッシュが有効になっています。キャッシュの詳細については、「*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>

プライベートドメインにマッピングされた API エンドポイントを持つ Lambda 関数を含む Hello World AWS SAM テンプレートファイル。テンプレートはVPC エンドポイントとプライベートドメインの間にドメイン名アクセスの関連付けを作成します。詳細については、「[API Gateway でのプライベート API のカスタムドメイン名](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
```