Sintaks Properti Nilai Pengembalian Contoh

AWS::Serverless::HttpApi

Membuat API HTTP Amazon API Gateway, yang mengaktifkan Anda untuk membuat API RESTful dengan latensi yang lebih rendah dan biaya yang lebih rendah dari REST API. Untuk informasi selengkapnya, lihat Bekerja dengan API HTTP di Panduan Developer API Gateway.

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.

Sintaks

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

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Properti

AccessLogSettings

Pengaturan untuk log akses dalam tahap.

Jenis: AccessLogSettings

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke AccessLogSettings properti AWS::ApiGatewayV2::Stage sumber daya.

Auth

Mengonfigurasikan otorisasi untuk mengendalikan akses ke API HTTP API Gateway Anda.

Untuk informasi selengkapnya, lihat Mengendalikan akses ke API HTTP dengan otorisasi JWT di Panduan Developer API Gateway.

Jenis: HttpApiAuth

Wajib: Tidak

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

CorsConfiguration

Mengelola cross-origin resource sharing (CORS) untuk semua API HTTP API Gateway Anda. Tentukan domain untuk diizinkan sebagai string, atau menentukan objek HttpApiCorsConfiguration. Perhatikan bahwa CORS AWS SAM perlu memodifikasi definisi OpenAPI Anda, jadi CORS hanya berfungsi jika properti ditentukanDefinitionBody.

Untuk informasi selengkapnya, lihat Mengonfigurasi CORS untuk API HTTP di Panduan Developer API Gateway.

catatan

Jika CorsConfiguration disetel baik dalam definisi OpenAPI maupun di tingkat properti, maka AWS SAM gabungkan kedua sumber konfigurasi dengan properti yang diutamakan. Jika properti ini disetel ketrue, maka semua asal diizinkan.

Jenis: String | HttpApiCorsConfiguration

Wajib: Tidak

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

DefaultRouteSettings

Pengaturan rute default untuk API HTTP ini. Pengaturan ini berlaku untuk semua rute kecuali dibatalkan oleh properti RouteSettings untuk rute tertentu.

Jenis: RouteSettings

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke RouteSettings properti AWS::ApiGatewayV2::Stage sumber daya.

DefinitionBody

Ketentuan OpenAPI yang menjelaskan API HTTP Anda. Jika Anda tidak menentukan a DefinitionUri atau a DefinitionBody AWS SAM , DefinitionBody buat untuk Anda berdasarkan konfigurasi template Anda.

Tipe: JSON

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini mirip dengan Body properti AWS::ApiGatewayV2::Api sumber daya. Jika properti tertentu disediakan, AWS SAM dapat memasukkan konten ke dalam atau memodifikasi DefinitionBody sebelum diteruskan ke AWS CloudFormation. Properti termasuk Auth dan EventSource tipe HttpApi untuk AWS::Serverless::Function sumber daya yang sesuai.

DefinitionUri

URI Amazon Simple Storage Service (Amazon S3), jalur file lokal, atau objek lokasi ketentuan OpenAPI yang menentukan API HTTP. Objek Amazon S3 yang merujuk properti ini harus menjadi file ketentuan OpenAPI yang valid. Jika Anda tidak menentukan DefinitionUri atau DefinitionBody ditentukan, buat AWS SAM DefinitionBody untuk Anda berdasarkan konfigurasi template Anda.

Jika Anda menyediakan jalur file lokal, templat harus melalui alur kerja yang mencakup perintah sam deploy atau sam package untuk ketentuan agar berubah dengan benar.

Fungsi intrinsik tidak didukung dalam file OpenApi definisi eksternal yang Anda referensikan. DefinitionUri Untuk mengimpor OpenApi definisi ke dalam template, gunakan DefinitionBody properti dengan transformasi Sertakan.

Jenis: String | HttpApiDefinition

Wajib: Tidak

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

Description

Deskripsi sumber daya HTTP API.

Saat Anda menentukanDescription, AWS SAM akan memodifikasi OpenApi definisi sumber daya HTTP API dengan menyetel description bidang. Skenario berikut akan menghasilkan kesalahan:

DefinitionBodyProperti ditentukan dengan description bidang yang disetel dalam definisi Open API — Ini menghasilkan konflik description bidang yang tidak AWS SAM akan diselesaikan.
DefinitionUriProperti ditentukan — tidak AWS SAM akan mengubah definisi Open API yang diambil dari Amazon S3.

Tipe: String

Wajib: Tidak

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

DisableExecuteApiEndpoint

Menentukan apakah klien dapat memanggil API HTTP Anda dengan menggunakan https://{api_id}.execute-api.{region}.amazonaws.com titik akhir execute-api default. Secara default, klien dapat memanggil API Anda dengan titik akhir default. Untuk meminta agar klien hanya menggunakan nama domain kustom untuk memanggil API Anda, nonaktifkan titik akhir default.

Untuk menggunakan properti ini, Anda harus menentukan DefinitionBody properti alih-alih DefinitionUri properti atau menentukan x-amazon-apigateway-endpoint-configuration dengan disableExecuteApiEndpoint definisi OpenAPI Anda.

Tipe: Boolean

Wajib: Tidak

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

Domain

Mengonfigurasi domain kustom untuk API HTTP API Gateway ini.

Jenis: HttpApiDomainConfiguration

Wajib: Tidak

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

FailOnWarnings

Menentukan apakah akan memutar kembali pembuatan API HTTP (true) atau tidak (false) saat peringatan ditemui. Nilai default-nya adalah false.

Tipe: Boolean

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke FailOnWarnings properti AWS::ApiGatewayV2::Api sumber daya.

Name

Nama sumber daya HTTP API.

Saat Anda menentukanName, AWS SAM akan memodifikasi definisi OpenAPI sumber daya HTTP API dengan menyetel bidang. title Skenario berikut akan menghasilkan kesalahan:

DefinitionBodyProperti ditentukan dengan title bidang yang disetel dalam definisi Open API — Ini menghasilkan konflik title bidang yang tidak AWS SAM akan diselesaikan.
DefinitionUriProperti ditentukan — tidak AWS SAM akan mengubah definisi Open API yang diambil dari Amazon S3.

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::HttpApi 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.

RouteSettings

Pengaturan rute, per rute, untuk API HTTP ini. Untuk informasi selengkapnya, lihat Bekerja dengan rute untuk API HTTP di Panduan Developer API Gateway.

Jenis: RouteSettings

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke RouteSettings properti AWS::ApiGatewayV2::Stage sumber daya.

StageName

Nama tahap API. Jika tidak ada nama yang ditentukan, AWS SAM gunakan $default stage dari API Gateway.

Tipe: String

Wajib: Tidak

Default: $default

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke StageName properti AWS::ApiGatewayV2::Stage sumber daya.

StageVariables

Sebuah peta yang menentukan variabel panggung. Nama variabel dapat memiliki karakter alfanumerik dan garis bawah. Nilai-nilai harus sesuai dengan [A-Za-z0-9-._~:/? #&=,] +.

Tipe: Json

Wajib: Tidak

AWS CloudFormation kompatibilitas: Properti ini diteruskan langsung ke StageVariables properti AWS::ApiGatewayV2::Stage sumber daya.

Tags

Sebuah peta (string ke string) yang menentukan tanda untuk ditambahkan ke tahap API Gateway ini. Kunci dapat berupa 1 hingga 128 karakter Unicode dan tidak dapat menyertakan awalanaws:. Anda dapat menggunakan salah satu karakter berikut: set huruf Unicode, angka, spasi putih, _, ., /, =, +, dan -. Nilai dapat berupa 1 hingga 256 karakter Unicode panjangnya.

Tipe: Peta

Wajib: Tidak

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

Catatan tambahan: Tags Properti AWS SAM harus mengubah definisi OpenAPI Anda, sehingga tag ditambahkan hanya jika DefinitionBody properti ditentukan—tidak ada tag yang ditambahkan jika properti ditentukan. DefinitionUri AWS SAM secara otomatis menambahkan httpapi:createdBy:SAM tag. Tanda juga ditambahkan ke sumber daya AWS::ApiGatewayV2::Stage dan sumber daya AWS::ApiGatewayV2::DomainName (jika DomainName ditentukan).

Nilai Pengembalian

Ref

Bila Anda melewati ID logis dari sumber daya ini ke fungsi Ref intrinsik, Ref mengembalikan ID API dari sumber daya AWS::ApiGatewayV2::Api utama, misalnya, a1bcdef2gh.

Untuk informasi lebih lanjut tentang penggunaan fungsi Ref, lihat Ref di Panduan Pengguna AWS CloudFormation .

Contoh

Sederhana HttpApi

Contoh berikut menunjukkan minimum yang diperlukan untuk mengatur titik akhir HTTP API yang didukung oleh fungsi Lambda. Contoh ini menggunakan HTTP API default yang AWS SAM membuat.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

HttpApi dengan Auth

Contoh berikut menunjukkan cara mengatur otorisasi di titik akhir HTTP API.

YAML


Properties:
  FailOnWarnings: true
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

HttpApidengan definisi OpenAPI

Contoh berikut menunjukkan cara menambahkan ketentuan OpenAPI ke templat.

Perhatikan bahwa AWS SAM mengisi integrasi Lambda yang hilang HttpApi untuk peristiwa yang mereferensikan API HTTP ini. AWS SAM juga menambahkan jalur yang hilang yang menjadi referensi HttpApi acara.

YAML


Properties:
  FailOnWarnings: true
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

HttpApi dengan pengaturan konfigurasi

Contoh berikut menunjukkan cara menambahkan API HTTP dan konfigurasi persiapan ke templat.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: true

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Waktu Aktif

HttpApiAuth