Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# AWS::Serverless::WebSocketApi
<a name="sam-resource-websocketapi"></a>

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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html) 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](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
<a name="sam-resource-websocketapi-syntax"></a>

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

### YAML
<a name="sam-resource-websocketapi-syntax.yaml"></a>

```
Type: AWS::Serverless::WebSocketApi
Properties:
  [ApiKeySelectionExpression](#sam-websocketapi-apikeyselectionexpression): {{String}}
  [AccessLogSettings](#sam-websocketapi-accesslogsettings): {{[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)}}
  [Auth](#sam-websocketapi-auth): {{WebSocketApiAuth}}
  [DefaultRouteSettings](#sam-websocketapi-defaultroutesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}}
  [Description](#sam-websocketapi-description): {{String}}
  [DisableExecuteApiEndpoint](#sam-websocketapi-disableexecuteapiendpoint): {{Boolean}}
  [DisableSchemaValidation](#sam-websocketapi-disableschemavalidation): {{Boolean}}
  [Domain](#sam-websocketapi-domain): {{WebSocketApiDomainConfiguration}}
  [IpAddressType](#sam-websocketapi-ipaddresstype): {{String}}
  [Name](#sam-websocketapi-name): {{String}}
  [PropagateTags](#sam-websocketapi-propagatetags): {{Boolean}}
  [Routes](#sam-websocketapi-routes): {{RouteConfiguration}}
  [RouteSelectionExpression](#sam-websocketapi-routeselectionexpression): {{String}}
  [RouteSettings](#sam-websocketapi-routesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}}
  [StageName](#sam-websocketapi-stagename): {{String}}
  [StageVariables](#sam-websocketapi-stagevariables): {{[Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)}}
  [Tags](#sam-websocketapi-tags): {{Map}}
```

## Sifat-sifat
<a name="sam-resource-websocketapi-properties"></a>

 `ApiKeySelectionExpression`   <a name="sam-websocketapi-apikeyselectionexpression"></a>
Ekspresi pemilihan kunci API. Untuk informasi selengkapnya, lihat [Ekspresi Pemilihan Kunci API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions) di *Panduan Pengembang API Gateway*.  
*Tipe*: String  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[ApiKeySelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `AccessLogSettings`   <a name="sam-websocketapi-accesslogsettings"></a>
Pengaturan untuk log akses dalam tahap.  
*Jenis*: [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` properti `AWS::ApiGatewayV2::Stage` sumber daya.

 `Auth`   <a name="sam-websocketapi-auth"></a>
Mengonfigurasi otorisasi untuk mengontrol akses ke API Anda WebSocket . Otorisasi diterapkan pada `$connect` rute.  
Untuk informasi selengkapnya, lihat [Mengontrol akses WebSocket APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html) di *Panduan Pengembang API Gateway*.  
*Jenis*: [WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.

 `DefaultRouteSettings`   <a name="sam-websocketapi-defaultroutesettings"></a>
Pengaturan rute default untuk WebSocket API ini. Pengaturan ini berlaku untuk semua rute kecuali dibatalkan oleh properti `RouteSettings` untuk rute tertentu.  
*Jenis*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-defaultroutesettings)` properti `AWS::ApiGatewayV2::Stage` sumber daya.

 `Description`   <a name="sam-websocketapi-description"></a>
Deskripsi WebSocket API.  
*Tipe*: String  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-description)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `DisableExecuteApiEndpoint`   <a name="sam-websocketapi-disableexecuteapiendpoint"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `DisableSchemaValidation`   <a name="sam-websocketapi-disableschemavalidation"></a>
Hindari memvalidasi model saat membuat deployment.  
*Tipe*: Boolean  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[DisableSchemaValidation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `Domain`   <a name="sam-websocketapi-domain"></a>
Mengonfigurasi domain kustom untuk WebSocket API ini.  
WebSocket APIs tidak mendukung otentikasi TLS timbal balik (MTLS). Jika Anda menentukan `MutualTlsAuthentication` atau`OwnershipVerificationCertificateArn`, AWS SAM akan mengembalikan kesalahan.
*Jenis*: [WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.

 `IpAddressType`   <a name="sam-websocketapi-ipaddresstype"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-ipaddresstype)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `Name`   <a name="sam-websocketapi-name"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-name)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `PropagateTags`   <a name="sam-websocketapi-propagatetags"></a>
Jika`true`, 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`   <a name="sam-websocketapi-routes"></a>
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](sam-property-websocketapi-routeconfiguration.md)  
*Wajib*: Ya  
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.

 `RouteSelectionExpression`   <a name="sam-websocketapi-routeselectionexpression"></a>
Ekspresi pemilihan rute untuk WebSocket API. Untuk informasi selengkapnya, lihat [Ekspresi Pemilihan Rute](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-route-selection-expressions) 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-routeselectionexpression)` properti `AWS::ApiGatewayV2::Api` sumber daya.

 `RouteSettings`   <a name="sam-websocketapi-routesettings"></a>
Pengaturan rute untuk WebSocket API ini. Pengaturan ini mengesampingkan `DefaultRouteSettings` rute tertentu.  
*Jenis*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` properti `AWS::ApiGatewayV2::Stage` sumber daya.

 `StageName`   <a name="sam-websocketapi-stagename"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` properti `AWS::ApiGatewayV2::Stage` sumber daya.

 `StageVariables`   <a name="sam-websocketapi-stagevariables"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini diteruskan langsung ke `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` properti `AWS::ApiGatewayV2::Stage` sumber daya.

 `Tags`   <a name="sam-websocketapi-tags"></a>
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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) di *Panduan CloudFormation Pengguna*.  
*Tipe*: Peta  
*Wajib*: Tidak  
*CloudFormation kompatibilitas*: Properti ini unik AWS SAM dan tidak memiliki CloudFormation padanan.

## Contoh
<a name="sam-resource-websocketapi-examples"></a>

### WebSocket API Sederhana
<a name="sam-resource-websocketapi-examples-simple"></a>

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
<a name="sam-resource-websocketapi-examples-auth"></a>

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