AWS::Serverless::Api - AWS Serverless Application Model
SintaksPropertiNilai PengembalianContoh

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::ApiSumber 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 yang ditentukan dalam templat yang tidak mengacu pada sumber daya AWS::Serverless::Api.

AWS::Serverless::ApiResource harus digunakan untuk mendefinisikan dan mendokumentasikan penggunaan API OpenApi, yang memberikan lebih banyak kemampuan untuk mengonfigurasi resource Amazon API Gateway yang mendasarinya.

Kami menyarankan Anda menggunakan AWS 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 AWS CloudFormation kait, lihat Mendaftarkan kait di panduan pengguna AWS CloudFormation CLI dan repositori. apigw-enforce-authorizer GitHub

Untuk informasi selengkapnya tentang penggunaan kebijakan IAM, lihat Mengharuskan rute API memiliki otorisasi dalam Panduan Pengembang API Gateway.

catatan

Ketika Anda menyebarkan ke AWS CloudFormation, AWS SAM mengubah AWS SAM sumber daya Anda menjadi AWS CloudFormation sumber daya. Untuk informasi selengkapnya, lihat AWS CloudFormation Sumber daya yang dihasilkan untuk AWS SAM.

Sintaks

Untuk mendeklarasikan entitas ini dalam template AWS Serverless Application Model (AWS SAM) Anda, gunakan sintaks berikut.

Properti

AccessLogSetting

Mengonfigurasi Pengaturan Log Ac untuk tahap.

Jenis: AccessLogSetting

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke AccessLogSetting properti AWS::ApiGateway::Stage sumber daya.

AlwaysDeploy

Selalu menerapkan API, bahkan ketika tidak ada perubahan pada API yang terdeteksi.

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

ApiKeySourceType

Sumber kunci API untuk permintaan pengukuran sesuai dengan rencana penggunaan. Nilai yang valid adalah HEADER dan AUTHORIZER.

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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 lihatKontrol API akses dengan AWS SAM template Anda.

Jenis: ApiAuth

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

BinaryMediaTypes

Daftar tipe MIME yang dapat dikembalikan API Anda. Gunakan ini untuk mengaktifkan dukungan biner untuk API. Gunakan ~1 bukan / dalam tipe mime.

Tipe: Daftar

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan BinaryMediaTypes properti AWS::ApiGateway::RestApi sumber daya. Daftar BinaryMediaTypes ditambahkan ke AWS CloudFormation sumber daya dan dokumen OpenAPI.

CacheClusterEnabled

Menunjukkan apakah caching diaktifkan untuk panggung. Untuk cache respons, Anda juga harus mengatur CachingEnabled ke true bawahMethodSettings.

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke CacheClusterEnabled properti AWS::ApiGateway::Stage sumber daya.

CacheClusterSize

Ukuran klaster cache dari tahap tersebut.

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke CacheClusterSize properti AWS::ApiGateway::Stage sumber daya.

CanarySetting

Konfigurasikan pengaturan canary ke tahap deployment reguler.

Jenis: CanarySetting

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke CanarySetting properti AWS::ApiGateway::Stage sumber daya.

Cors

Kelola Cross-origin resource sharing (CORS) untuk semua API Gateway Anda. Tentukan domain untuk diizinkan sebagai string atau tentukan kamus dengan konfigurasi Cors tambahan.

catatan

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 di Panduan Developer API Gateway.

Jenis: String | CorsConfiguration

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS 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.

Tipe: JSON

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan Body properti AWS::ApiGateway::RestApi sumber daya. Jika properti tertentu disediakan, konten dapat dimasukkan atau dimodifikasi ke dalam DefinitionBody sebelum diteruskan ke CloudFormation. Properti termasukAuth, BinaryMediaTypesCors,GatewayResponses,Models,, dan EventSource tipe Api untuk yang sesuaiAWS::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 DefinitionBody properti dengan Include Transform untuk mengimpor OpenApi definisi ke dalam template.

Jenis: String | ApiDefinition

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan BodyS3Location properti AWS::ApiGateway::RestApi sumber daya. Properti Amazon S3 nest diberi nama berbeda.

Description

Deskripsi sumber daya Api.

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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 defaulthttps://{api_id}.execute-api.{region}.amazonaws.com. Untuk mengharuskan klien menggunakan nama domain khusus untuk menjalankan API Anda, tentukanTrue.

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan DisableExecuteApiEndpoint properti AWS::ApiGateway::RestApi sumber daya. Itu diteruskan langsung ke disableExecuteApiEndpoint properti x-amazon-apigateway-endpoint-configuration ekstensi, yang akan ditambahkan ke Body properti AWS::ApiGateway::RestApi sumber daya.

Domain

Mengonfigurasi domain khusus untuk API dari API Gateway ini.

Jenis: DomainConfiguration

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

EndpointConfiguration

Tipe titik akhir dari REST API.

Jenis: EndpointConfiguration

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan 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

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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.

Tipe: Peta

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS 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 AndaAWS::Serverless::Api. Tentukan false untuk tidak bergabung.

MergeDefinitionsmembutuhkan DefinitionBody properti AWS::Serverless::Api untuk didefinisikan. MergeDefinitionstidak kompatibel dengan DefinitionUri properti untukAWS::Serverless::Api.

Nilai default: false

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

MethodSettings

Mengonfigurasi semua pengaturan untuk tahap API termasuk Logging, Metrik, CacheTTL, Throttling.

Jenis: Daftar MethodSetting

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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 dari jenis AWS::ApiGateway::RestApisumber daya.

Nilai yang valid: overwrite atau merge

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

Name

Nama untuk RestApi sumber daya API Gateway

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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.

catatan

AWS SAM menciptakan tahap yang disebut secara Stage default. Menyetel properti ini ke nilai yang valid akan mencegah pembuatan panggungStage.

Tipe: String

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

PropagateTags

Tunjukkan apakah akan meneruskan tag dari Tags properti ke sumber daya yang Anda AWS::Serverless::Api hasilkan atau tidak. Tentukan True untuk menyebarkan tag di sumber daya yang Anda hasilkan.

Tipe: Boolean

Wajib: Tidak

Default: False

AWS CloudFormation kompatibilitas: Properti ini unik AWS SAM dan tidak memiliki AWS CloudFormation padanan.

StageName

Nama tahap, yang digunakan API Gateway sebagai segmen jalur pertama dalam Uniform Resource Identifier (URI) panggil.

Untuk referensi sumber daya tahap, gunakan <api-logical-id>.Stage. Untuk informasi lebih lanjut tentang referensi sumber daya yang dibuat ketika sumber daya AWS::Serverless::Api ditentukan, lihat AWS CloudFormation sumber daya yang dihasilkan saat AWS::Serverless::Api ditentukan. Untuk informasi umum tentang AWS CloudFormation sumber daya yang dihasilkan, lihatAWS CloudFormation Sumber daya yang dihasilkan untuk AWS SAM.

Tipe: String

Wajib: Ya

AWS CloudFormation kompatibilitas: Properti ini mirip dengan 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 di Panduan AWS CloudFormation Pengguna.

Tipe: Peta

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan 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 Melacak permintaan pengguna untuk REST API menggunakan X-Ray di Panduan Developer API Gateway.

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke 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 Ref 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 Fn::GetAtt 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 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 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 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 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}