AWS::Serverless::WebSocketApi

Membuat API Amazon WebSocket API Gateway, yang memungkinkan Anda membuat aplikasi komunikasi interaktif dua arah. WebSocket APIs memungkinkan server untuk mengirim pesan ke klien tanpa klien harus meminta mereka. Untuk informasi selengkapnya, lihat Bekerja dengan WebSocket APIs di Panduan Pengembang API Gateway.

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 di panduan pengguna 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 CloudFormation sumber daya. Untuk informasi selengkapnya, lihat CloudFormation Sumber daya yang dihasilkan untuk AWS SAM.

Sintaksis

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

YAML

Type: AWS::Serverless::WebSocketApi
Properties:
  ApiKeySelectionExpression: String
  AccessLogSettings: AccessLogSettings
  Auth: WebSocketApiAuth
  DefaultRouteSettings: RouteSettings
  Description: String
  DisableExecuteApiEndpoint: Boolean
  DisableSchemaValidation: Boolean
  Domain: WebSocketApiDomainConfiguration
  IpAddressType: String
  Name: String
  PropagateTags: Boolean
  Routes: RouteConfiguration
  RouteSelectionExpression: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Sifat-sifat

ApiKeySelectionExpression

Ekspresi pemilihan kunci API. Untuk informasi selengkapnya, lihat Ekspresi Pemilihan Kunci API di Panduan Pengembang API Gateway.

Tipe: String

Wajib: Tidak

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

AccessLogSettings

Pengaturan untuk log akses dalam tahap.

Jenis: AccessLogSettings

Wajib: Tidak

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

Auth

Mengonfigurasi otorisasi untuk mengontrol akses ke API Anda WebSocket . Otorisasi diterapkan pada $connect rute.

Untuk informasi selengkapnya, lihat Mengontrol akses WebSocket APIs di Panduan Pengembang API Gateway.

Jenis: WebSocketApiAuth

Wajib: Tidak

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

DefaultRouteSettings

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

Jenis: RouteSettings

Wajib: Tidak

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

Description

Deskripsi WebSocket API.

Tipe: String

Wajib: Tidak

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

DisableExecuteApiEndpoint

Menentukan apakah klien dapat memanggil API dengan menggunakan titik akhir execute-api default. Untuk meminta agar klien menggunakan nama domain kustom untuk memanggil API Anda, nonaktifkan titik akhir default.

Tipe: Boolean

Wajib: Tidak

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

DisableSchemaValidation

Hindari memvalidasi model saat membuat deployment.

Tipe: Boolean

Wajib: Tidak

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

Domain

Mengonfigurasi domain kustom untuk WebSocket API ini.

catatan

WebSocket APIs tidak mendukung otentikasi TLS timbal balik (MTLS). Jika Anda menentukan MutualTlsAuthentication atauOwnershipVerificationCertificateArn, AWS SAM akan mengembalikan kesalahan.

Jenis: WebSocketApiDomainConfiguration

Wajib: Tidak

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

IpAddressType

Jenis alamat IP untuk API. Nilai yang valid IPv4 hanya ipv4 untuk dan dualstack untuk IPv4 dan IPv6.

Tipe: String

Wajib: Tidak

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

Name

Sebuah nama untuk WebSocket API. Jika Anda tidak menentukan nama, AWS SAM buat nama untuk Anda.

Tipe: String

Wajib: Tidak

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

PropagateTags

Jikatrue, AWS SAM tambahkan Tags properti ke AWS::ApiGatewayV2::Stage dan AWS::ApiGatewayV2::DomainName sumber daya yang AWS SAM menghasilkan.

Tipe: Boolean

Wajib: Tidak

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

Routes

Konfigurasi rute untuk WebSocket API ini. Rute menentukan bagaimana pesan dirutekan ke fungsi Lambda. Setiap rute terdiri dari kunci rute dan fungsi Lambda ARN.

WebSocket APIs mendukung tiga rute yang telah ditentukan:$connect,$disconnect, dan$default. Anda juga dapat menentukan rute khusus.

Jenis: RouteConfiguration

Wajib: Ya

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

RouteSelectionExpression

Ekspresi pemilihan rute untuk WebSocket API. Untuk informasi selengkapnya, lihat Ekspresi Pemilihan Rute di Panduan Pengembang API Gateway.

Nilai umum adalah$request.body.action, yang merutekan pesan berdasarkan action bidang di badan pesan.

Tipe: String

Wajib: Ya

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

RouteSettings

Pengaturan rute untuk WebSocket API ini. Pengaturan ini mengesampingkan DefaultRouteSettings rute tertentu.

Jenis: RouteSettings

Wajib: Tidak

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

StageName

Nama tahap API. Jika Anda tidak menentukan nama, AWS SAM gunakan default sebagai nama panggung.

Tipe: String

Wajib: Tidak

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

StageVariables

Sebuah peta yang mendefinisikan variabel tahapan. Nama variabel dapat memiliki karakter alfanumerik dan garis bawah, dan nilainya harus cocok. [A-Za-z0-9-._~:/?#&=,]+

Tipe: Json

Wajib: Tidak

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

Tags

Peta (string ke string) yang menentukan tag yang akan ditambahkan ke WebSocket API ini. Untuk detail tentang kunci dan nilai tag yang valid, lihat Tag sumber daya di Panduan CloudFormation Pengguna.

Tipe: Peta

Wajib: Tidak

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

Contoh

WebSocket API Sederhana

Contoh berikut membuat WebSocket API dengan tiga rute.

Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        $disconnect:
          FunctionArn: !GetAtt DisconnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  DisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.disconnect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

WebSocket API dengan Lambda Authorizer

Contoh berikut membuat WebSocket API dengan otorisasi Lambda.

Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Auth:
        AuthType: CUSTOM
        AuthArn: !GetAtt AuthorizerFunction.Arn
        IdentitySource:
          - route.request.header.Authorization
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  AuthorizerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.authorize
      Runtime: nodejs20.x
      CodeUri: ./src

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src