Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS::Serverless::Api
Membuat koleksi sumber daya Amazon API Gateway dan metode yang dapat dipanggil melalui titik akhir HTTPS.
[AWS::Serverless::Api](#sam-resource-api)Sumber daya tidak perlu ditambahkan secara eksplisit ke template Definisi Aplikasi AWS Tanpa Server. Sumber daya tupe ini secara implisit dibuat dari penyatuan peristiwa Api yang ditentukan pada sumber daya [AWS::Serverless::Function](sam-resource-function.md) yang ditentukan dalam templat yang tidak mengacu pada sumber daya [AWS::Serverless::Api](#sam-resource-api).
[AWS::Serverless::Api](#sam-resource-api)Resource harus digunakan untuk mendefinisikan dan mendokumentasikan penggunaan API OpenApi, yang memberikan lebih banyak kemampuan untuk mengonfigurasi sumber daya Amazon API Gateway yang mendasarinya.
Kami menyarankan Anda menggunakan CloudFormation kait atau kebijakan IAM untuk memverifikasi bahwa sumber daya API Gateway memiliki otorisasi yang melekat padanya untuk mengontrol akses ke sumber daya tersebut.
Untuk informasi selengkapnya tentang penggunaan CloudFormation kait, lihat [Mendaftarkan kait](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) di *panduan pengguna CloudFormation CLI* dan repositori. [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub
Untuk informasi selengkapnya tentang penggunaan kebijakan IAM, lihat [Mengharuskan rute API memiliki otorisasi dalam Panduan](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) *Pengembang API Gateway*.
**catatan**
Ketika Anda menyebarkan ke AWS CloudFormation, AWS SAM mengubah AWS SAM sumber daya Anda menjadi CloudFormation sumber daya. Untuk informasi selengkapnya, lihat [CloudFormation Sumber daya yang dihasilkan untuk AWS SAM](sam-specification-generated-resources.md).
## Sintaksis
Untuk mendeklarasikan entitas ini dalam template AWS Serverless Application Model (AWS SAM) Anda, gunakan sintaks berikut.
### YAML
```
Type: AWS::Serverless::Api
Properties:
[AccessLogSetting](#sam-api-accesslogsetting): [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
AlwaysDeploy: Boolean
[ApiKeySourceType](#sam-api-apikeysourcetype): String
[Auth](#sam-api-auth): ApiAuth
[BinaryMediaTypes](#sam-api-binarymediatypes): List
[CacheClusterEnabled](#sam-api-cacheclusterenabled): Boolean
[CacheClusterSize](#sam-api-cacheclustersize): String
[CanarySetting](#sam-api-canarysetting): [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
[Cors](#sam-api-cors): String | CorsConfiguration
[DefinitionBody](#sam-api-definitionbody): JSON
[DefinitionUri](#sam-api-definitionuri): String | ApiDefinition
[Description](#sam-api-description): String
[DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): Boolean
[Domain](#sam-api-domain): DomainConfiguration
[EndpointConfiguration](#sam-api-endpointconfiguration): EndpointConfiguration
[FailOnWarnings](#sam-api-failonwarnings): Boolean
[GatewayResponses](#sam-api-gatewayresponses): Map
MergeDefinitions: Boolean
[MethodSettings](#sam-api-methodsettings): MethodSettings
[MinimumCompressionSize](#sam-api-minimumcompressionsize): Integer
[Mode](#sam-api-mode): String
[Models](#sam-api-models): Map
[Name](#sam-api-name): String
[OpenApiVersion](#sam-api-openapiversion): String
PropagateTags: Boolean
[Policy](#sam-api-policy): JSON
[StageName](#sam-api-stagename): String
[Tags](#sam-api-tags): Map
[TracingEnabled](#sam-api-tracingenabled): Boolean
[Variables](#sam-api-variables): Map
```
## Sifat-sifat
`AccessLogSetting`
Mengonfigurasi Pengaturan Log Ac untuk tahap.
*Jenis*: [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)` properti `AWS::ApiGateway::Stage` sumber daya.
`AlwaysDeploy`
Selalu menerapkan API, bahkan ketika tidak ada perubahan pada API yang terdeteksi.
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`ApiKeySourceType`
Sumber kunci API untuk permintaan pengukuran sesuai dengan rencana penggunaan. Nilai yang valid adalah `HEADER` dan `AUTHORIZER`.
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-apikeysourcetype)` properti `AWS::ApiGateway::RestApi` sumber daya.
`Auth`
Konfigurasikan otorisasi untuk mengendalikan akses ke API Gateway Anda.
Untuk informasi selengkapnya tentang mengonfigurasi akses menggunakan AWS SAM lihat[Kontrol akses API dengan AWS SAM template Anda](serverless-controlling-access-to-apis.md). Untuk contoh yang menunjukkan cara mengganti otorisasi global, lihat. [Ganti otorisasi global untuk REST API Amazon API Gateway](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override)
*Jenis*: [ApiAuth](sam-property-api-apiauth.md)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`BinaryMediaTypes`
Daftar tipe MIME yang dapat dikembalikan API Anda. Gunakan ini untuk mengaktifkan dukungan biner untukAPIs.
*Tipe*: Daftar
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)` properti `AWS::ApiGateway::RestApi` sumber daya. Daftar BinaryMediaTypes ditambahkan ke CloudFormation sumber daya dan dokumen OpenAPI.
`CacheClusterEnabled`
Menunjukkan apakah caching diaktifkan untuk panggung. Untuk cache respons, Anda juga harus mengatur `CachingEnabled` ke `true` bawah`MethodSettings`.
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` properti `AWS::ApiGateway::Stage` sumber daya.
`CacheClusterSize`
Ukuran klaster cache dari tahap tersebut.
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclustersize)` properti `AWS::ApiGateway::Stage` sumber daya.
`CanarySetting`
Konfigurasikan pengaturan canary ke tahap deployment reguler.
*Jenis*: [CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)` properti `AWS::ApiGateway::Stage` sumber daya.
`Cors`
Kelola berbagi sumber daya lintas asal (CORS) untuk semua API Gateway Anda. APIs Tentukan domain untuk diizinkan sebagai string atau tentukan kamus dengan konfigurasi Cors tambahan.
CORS AWS SAM perlu memodifikasi definisi OpenAPI Anda. Buat definisi OpenAPI sebaris di untuk mengaktifkan `DefinitionBody` CORS.
Untuk informasi lebih lanjut tentang CORS, lihat [Aktifkan CORS untuk sumber daya API REST API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html) di *Panduan Developer API Gateway*.
*Jenis*: String \$1 [CorsConfiguration](sam-property-api-corsconfiguration.md)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`DefinitionBody`
Spesifikasi OpenAPI yang menggambarkan API Anda. Jika `DefinitionUri` dan `DefinitionBody` tidak ditentukan, SAM akan membuat `DefinitionBody` untuk Anda berdasarkan konfigurasi templat Anda.
Untuk mereferensikan OpenAPI file lokal yang mendefinisikan API Anda, gunakan `AWS::Include` transformasi. Untuk mempelajari selengkapnya, lihat [Cara AWS SAM mengunggah file lokal](deploy-upload-local-files.md).
*Tipe*: JSON
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` properti `AWS::ApiGateway::RestApi` sumber daya. Jika properti tertentu disediakan, konten dapat dimasukkan atau dimodifikasi ke dalam DefinitionBody sebelum diteruskan ke CloudFormation. Properti termasuk`Auth`, `BinaryMediaTypes``Cors`,`GatewayResponses`,`Models`,, dan `EventSource` tipe Api untuk yang sesuai`AWS::Serverless::Function`.
`DefinitionUri`
Amazon S3 Uri, jalur file lokal, atau objek lokasi dokumen OpenAPI menentukan API. Objek Amazon S3 yang dirujuk properti ini harus menjadi file OpenAPI yang valid. Jika `DefinitionUri` dan `DefinitionBody` tidak ditentukan, SAM akan membuat `DefinitionBody` untuk Anda berdasarkan konfigurasi templat Anda.
Jika lintasan file lokal disediakan, templat harus melalui alur kerja yang mencakup perintah `sam deploy` atau `sam package`, agar ketentuan diubah dengan benar.
Fungsi intrinsik tidak didukung dalam OpenApi file eksternal yang direferensikan oleh. `DefinitionUri` Gunakan sebagai gantinya `DefinitionBody` properti dengan [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) untuk mengimpor OpenApi definisi ke dalam template.
*Jenis*: String \$1 [ApiDefinition](sam-property-api-apidefinition.md)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-bodys3location)` properti `AWS::ApiGateway::RestApi` sumber daya. Properti Amazon S3 nest diberi nama berbeda.
`Description`
Deskripsi sumber daya Api.
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-description)` properti `AWS::ApiGateway::RestApi` sumber daya.
`DisableExecuteApiEndpoint`
Menentukan apakah klien dapat memanggil API dengan menggunakan titik akhir `execute-api` default. Secara default, klien dapat memanggil API Anda dengan default`https://{api_id}.execute-api.{region}.amazonaws.com`. Untuk mengharuskan klien menggunakan nama domain khusus untuk menjalankan API Anda, tentukan`True`.
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)` properti `AWS::ApiGateway::RestApi` sumber daya. Itu diteruskan langsung ke `disableExecuteApiEndpoint` properti `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` ekstensi, yang akan ditambahkan ke ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body)` properti `AWS::ApiGateway::RestApi` sumber daya.
`Domain`
Mengonfigurasi domain khusus untuk API dari API Gateway ini.
*Jenis*: [DomainConfiguration](sam-property-api-domainconfiguration.md)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`EndpointConfiguration`
Tipe titik akhir dari REST API.
*Jenis*: [EndpointConfiguration](sam-property-api-endpointconfiguration.md)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)` properti `AWS::ApiGateway::RestApi` sumber daya. Properti konfigurasi nest diberi nama berbeda.
`FailOnWarnings`
Menentukan apakah akan memutar kembali penciptaan API (`true`) atau not (`false`) ketika peringatan ditemui. Nilai default-nya adalah `false`.
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-failonwarnings)` properti `AWS::ApiGateway::RestApi` sumber daya.
`GatewayResponses`
Mengonfigurasi Respons Gateway untuk API. Respons Gateway adalah respons yang dikembalikan oleh API Gateway, secara langsung atau melalui penggunaan Lambda Authorizers. Untuk informasi selengkapnya, lihat dokumentasi untuk [ OpenApi ekstensi Api Gateway untuk Tanggapan Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html).
*Tipe*: Peta
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`MergeDefinitions`
AWS SAM menghasilkan OpenAPI spesifikasi dari sumber peristiwa API Anda. Tentukan `true` untuk AWS SAM menggabungkan ini ke dalam OpenAPI spesifikasi sebaris yang ditentukan dalam sumber daya Anda`AWS::Serverless::Api`. Tentukan `false` untuk tidak bergabung.
`MergeDefinitions`membutuhkan `DefinitionBody` properti `AWS::Serverless::Api` untuk didefinisikan. `MergeDefinitions`tidak kompatibel dengan `DefinitionUri` properti untuk`AWS::Serverless::Api`.
*Nilai default*: `false`
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`MethodSettings`
Mengonfigurasi semua pengaturan untuk tahap API termasuk Logging, Metrik, CacheTTL, Throttling.
*Jenis*: Daftar [ MethodSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html)
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-methodsettings)` properti `AWS::ApiGateway::Stage` sumber daya.
`MinimumCompressionSize`
Izinkan kompresi isi respons berdasarkan header Accept-Encoding klien. Kompresi terpicu ketika ukuran tubuh respons lebih besar dari atau sama dengan ambang batas Anda yang telah dikonfigurasi. Ambang batas ukuran isi maksimum adalah 10 MB (10.485.760 Bita). - Tipe kompresi berikut didukung: gzip, mengempis, dan identitas.
*Tipe*: Integer
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-minimumcompressionsize)` properti `AWS::ApiGateway::RestApi` sumber daya.
`Mode`
Properti ini hanya berlaku bila Anda menggunakan OpenAPI untuk menentukan API REST Anda. `Mode` menentukan bagaimana API Gateway menangani pembaruan sumber daya. Untuk informasi selengkapnya, lihat Properti [mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode) dari jenis [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)sumber daya.
*Nilai yang valid*: `overwrite` atau `merge`
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode)` properti `AWS::ApiGateway::RestApi` sumber daya.
`Models`
Skema yang akan digunakan oleh metode API Anda. Skema ini dapat dijelaskan menggunakan JSON atau YAML. Lihat bagian Contoh di bagian bawah halaman ini misalnya model.
*Tipe*: Peta
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`Name`
Nama untuk RestApi sumber daya API Gateway
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-name)` properti `AWS::ApiGateway::RestApi` sumber daya.
`OpenApiVersion`
Versi OpenApi untuk digunakan. Ini bisa `2.0` untuk spesifikasi Swagger, atau salah satu versi OpenApi 3.0, seperti. `3.0.1` Untuk informasi selengkapnya tentang OpenAPI, lihat [Spesifikasi OpenAPI](https://swagger.io/specification/).
AWS SAM menciptakan tahap yang disebut secara `Stage` default. Menyetel properti ini ke nilai yang valid akan mencegah pembuatan panggung`Stage`.
*Tipe*: String
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`PropagateTags`
Tunjukkan apakah akan meneruskan tag dari `Tags` properti ke sumber daya yang Anda [AWS::Serverless::Api](sam-specification-generated-resources-api.md) hasilkan atau tidak. Tentukan `True` untuk menyebarkan tag di sumber daya yang Anda hasilkan.
*Tipe*: Boolean
*Wajib*: Tidak
*Default*: `False`
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.
`Policy`
Dokumen kebijakan yang berisi izin untuk API. Untuk menetapkan ARN untuk kebijakan, gunakan fungsi intrinsik `!Join` dengan `""` sebagai pembatas dan nilai-nilai `"execute-api:/"` dan `"*"`.
*Tipe*: JSON
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke properti [Kebijakan](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) `AWS::ApiGateway::RestApi` sumber daya.
`StageName`
Nama tahap, yang digunakan API Gateway sebagai segmen jalur pertama dalam Uniform Resource Identifier (URI) panggil.
Untuk referensi sumber daya tahap, gunakan `.Stage`. Untuk informasi lebih lanjut tentang referensi sumber daya yang dibuat ketika sumber daya [AWS::Serverless::Api](#sam-resource-api) ditentukan, lihat [CloudFormation sumber daya yang dihasilkan saat AWS::Serverless::Api ditentukan](sam-specification-generated-resources-api.md). Untuk informasi umum tentang CloudFormation sumber daya yang dihasilkan, lihat[CloudFormation Sumber daya yang dihasilkan untuk AWS SAM](sam-specification-generated-resources.md).
*Tipe*: String
*Wajib*: Ya
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-stagename)` properti `AWS::ApiGateway::Stage` sumber daya. Hal ini diperlukan dalam SAM, tetapi tidak diperlukan di API Gateway
*Catatan tambahan*: API implisit memiliki nama tahap “Prod”.
`Tags`
Sebuah peta (string ke string) yang menentukan tanda yang akan ditambahkan ke tahap API Gateway ini. Untuk detail tentang kunci dan nilai tag yang valid, lihat [Tag sumber daya](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) di *Panduan AWS CloudFormation Pengguna*.
*Tipe*: Peta
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini mirip dengan `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tags)` properti `AWS::ApiGateway::Stage` sumber daya. Properti Tags di SAM terdiri dari pasangan Key:Value; di CloudFormation dalamnya terdiri dari daftar objek Tag.
`TracingEnabled`
Menunjukkan apakah penelusuran aktif dengan X-Ray diaktifkan untuk tahap tersebut. Untuk informasi selengkapnya tentang X-Ray, lihat [Menelusuri permintaan pengguna ke REST APIs menggunakan X-Ray](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html) di *Panduan Pengembang API Gateway*.
*Tipe*: Boolean
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-tracingenabled)` properti `AWS::ApiGateway::Stage` sumber daya.
`Variables`
Sebuah peta (string ke string) yang menentukan variabel tahap, dengan nama variabel adalah kunci dan nilai variabel adalah nilai. Nama variabel terbatas pada karakter alfanumerik. Nilai harus sesuai dengan ekspresi reguler berikut: `[A-Za-z0-9._~:/?#&=,-]+`.
*Tipe*: Peta
*Wajib*: Tidak
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables)` properti `AWS::ApiGateway::Stage` sumber daya.
## Nilai Pengembalian
### Ref
Ketika ID logis dari sumber daya ini disediakan untuk fungsi intrinsik `Ref`, ID logis mengembalikan ID dari API Gateway utama.
Untuk informasi lebih lanjut tentang menggunakan fungsi `Ref`, lihat [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) di *Panduan Pengguna AWS CloudFormation *.
### Fn:: GetAtt
`Fn::GetAtt` mengembalikan nilai untuk atribut yang ditentukan dari jenis ini. Berikut ini adalah atribut yang tersedia dan nilai-nilai kembali sampel.
Untuk informasi lebih lanjut tentang `Fn::GetAtt`, lihat [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) di *Panduan Pengguna AWS CloudFormation *
`RootResourceId`
ID sumber daya root untuk sumber daya `RestApi`, seperti `a0bc123d4e`.
## Contoh
### SimpleApiExample
File AWS SAM template Hello World yang berisi Fungsi Lambda dengan titik akhir API. Ini adalah file AWS SAM template lengkap untuk aplikasi tanpa server yang berfungsi.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### ApiCorsExample
Cuplikan AWS SAM template dengan API yang ditentukan dalam file Swagger eksternal bersama dengan integrasi Lambda dan konfigurasi CORS. Ini hanya sebagian dari file AWS SAM template yang menunjukkan [AWS::Serverless::Api](#sam-resource-api) definisi.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
# Allows www.example.com to call these APIs
# SAM will automatically add AllowMethods with a list of methods for this API
Cors: "'www.example.com'"
DefinitionBody: # Pull in an OpenApi definition from S3
'Fn::Transform':
Name: 'AWS::Include'
# Replace "bucket" with your bucket name
Parameters:
Location: s3://bucket/swagger.yaml
```
### ApiCognitoAuthExample
Cuplikan AWS SAM template dengan API yang menggunakan Amazon Cognito untuk mengotorisasi permintaan terhadap API. Ini hanya sebagian dari file AWS SAM template yang menunjukkan [AWS::Serverless::Api](#sam-resource-api) definisi.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Cors: "'*'"
Auth:
DefaultAuthorizer: MyCognitoAuthorizer
Authorizers:
MyCognitoAuthorizer:
UserPoolArn:
Fn::GetAtt: [MyCognitoUserPool, Arn]
```
### ApiModelsExample
Cuplikan AWS SAM template dengan API yang menyertakan skema Model. Ini hanya sebagian dari file AWS SAM template, menunjukkan [AWS::Serverless::Api](#sam-resource-api) definisi dengan dua skema model.
#### YAML
```
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
Models:
User:
type: object
required:
- username
- employee_id
properties:
username:
type: string
employee_id:
type: integer
department:
type: string
Item:
type: object
properties:
count:
type: integer
category:
type: string
price:
type: integer
```
### Contoh caching
File AWS SAM template Hello World yang berisi Fungsi Lambda dengan titik akhir API. API telah mengaktifkan caching untuk satu sumber daya dan metode. Untuk informasi selengkapnya tentang caching, lihat [Mengaktifkan caching API untuk meningkatkan daya tanggap](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html) dalam Panduan Pengembang *API* Gateway.
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
ApiGatewayApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
CacheClusterEnabled: true
CacheClusterSize: '0.5'
MethodSettings:
- ResourcePath: /
HttpMethod: GET
CachingEnabled: true
CacheTtlInSeconds: 300
Tags:
CacheMethods: All
ApiFunction: # Adds a GET method at the root resource via an Api event
Type: AWS::Serverless::Function
Properties:
Events:
ApiEvent:
Type: Api
Properties:
Path: /
Method: get
RestApiId:
Ref: ApiGatewayApi
Runtime: python3.10
Handler: index.handler
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
```
### Domain khusus dengan contoh API pribadi
File AWS SAM template Hello World yang berisi fungsi Lambda dengan titik akhir API yang dipetakan ke domain pribadi. Template membuat asosiasi akses domain antara titik akhir VPC dan domain pribadi. Untuk informasi selengkapnya, lihat [Nama domain khusus untuk pribadi APIs di API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html).
#### YAML
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API
Parameters:
DomainName:
Type: String
Default: mydomain.example.com
CertificateArn:
Type: String
HostedZoneId:
Type: String
VpcEndpointId:
Type: String
VpcEndpointDomainName:
Type: String
VpcEndpointHostedZoneId:
Type: String
Resources:
MyFunction:
Type: AWS::Serverless::Function
Properties:
InlineCode: |
def handler(event, context):
return {'body': 'Hello World!', 'statusCode': 200}
Handler: index.handler
Runtime: python3.13
Events:
Fetch:
Type: Api
Properties:
RestApiId:
Ref: MyApi
Method: Get
Path: /get
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: Prod
EndpointConfiguration:
Type: PRIVATE
VPCEndpointIds:
- !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
Domain:
DomainName: !Ref DomainName
CertificateArn: !Ref CertificateArn
EndpointConfiguration: PRIVATE
BasePath:
- /
Route53:
HostedZoneId: !Ref HostedZoneId
VpcEndpointDomainName: !Ref VpcEndpointDomainName
VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
AccessAssociation:
VpcEndpointId: !Ref VpcEndpointId
Policy:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
- Effect: Deny
Principal: '*'
Action: execute-api:Invoke
Resource: execute-api:/*
Condition:
StringNotEquals:
aws:SourceVpce: !Ref VpcEndpointId
```