本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

建立 Amazon API Gateway WebSocket API，可讓您建立雙向互動式通訊應用程式。WebSocket APIs 可讓伺服器傳送訊息給用戶端，而不需要用戶端加以請求。如需詳細資訊，請參閱[APIs》中的使用 WebSocket ](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html) API。 **

我們建議您使用 CloudFormation 勾點或 IAM 政策來驗證 API Gateway 資源是否已連接授權方，以控制對它們的存取。

如需使用 CloudFormation 勾點的詳細資訊，請參閱 *CloudFormation CLI 使用者指南*中的[註冊勾點](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html)和 [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub 儲存庫。

如需使用 IAM 政策的詳細資訊，請參閱[《 API Gateway 開發人員指南》中的要求 API 路由具有授權](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization)。 **

**注意**  
當您部署到 時 AWS CloudFormation， 會將您的 AWS SAM 資源 AWS SAM 轉換為 CloudFormation 資源。如需詳細資訊，請參閱[為 產生 CloudFormation 資源 AWS SAM](sam-specification-generated-resources.md)。

## 語法
<a name="sam-resource-websocketapi-syntax"></a>

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

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

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

 `ApiKeySelectionExpression`   <a name="sam-websocketapi-apikeyselectionexpression"></a>
API 金鑰選擇表達式。如需詳細資訊，請參閱《 [API Gateway 開發人員指南》中的 API 金鑰選擇表達式](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions)。 **  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[ApiKeySelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` 屬性。

 `AccessLogSettings`   <a name="sam-websocketapi-accesslogsettings"></a>
階段中存取記錄的設定。  
*類型*：[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Stage` 資源的 `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` 屬性。

 `Auth`   <a name="sam-websocketapi-auth"></a>
設定控制 WebSocket API 存取的授權。授權會套用至`$connect`路由。  
如需詳細資訊，請參閱[《 API Gateway 開發人員指南》中的控制對 WebSocket API 的存取 APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html)。 **  
*類型*：[WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `DefaultRouteSettings`   <a name="sam-websocketapi-defaultroutesettings"></a>
此 WebSocket API 的預設路由設定。除非由特定路由的 `RouteSettings` 屬性覆寫，否則這些設定適用於所有路由。  
*類型*：[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Stage` 資源的 `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-defaultroutesettings)` 屬性。

 `Description`   <a name="sam-websocketapi-description"></a>
WebSocket API 的說明。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-description)` 屬性。

 `DisableExecuteApiEndpoint`   <a name="sam-websocketapi-disableexecuteapiendpoint"></a>
指定用戶端是否可以使用預設 `execute-api` 端點叫用您的 API。如要要求用戶端使用自訂網域名稱來叫用 API，請停用預設端點。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` 屬性。

 `DisableSchemaValidation`   <a name="sam-websocketapi-disableschemavalidation"></a>
避免在建立部署時驗證模型。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[DisableSchemaValidation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` 屬性。

 `Domain`   <a name="sam-websocketapi-domain"></a>
設定此 WebSocket API 的自訂網域。  
WebSocket APIs不支援交互 TLS 身分驗證 (MTLS)。如果您指定 `MutualTlsAuthentication`或 `OwnershipVerificationCertificateArn`， AWS SAM 將傳回錯誤。
*類型*：[WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md)  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `IpAddressType`   <a name="sam-websocketapi-ipaddresstype"></a>
API 的 IP 地址類型。有效值僅適用於 `ipv4` IPv4，`dualstack`適用於 IPv4 和 IPv6。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[IpAddressType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-ipaddresstype)` 屬性。

 `Name`   <a name="sam-websocketapi-name"></a>
WebSocket API 的名稱。如果您未指定名稱， 會為您 AWS SAM 產生名稱。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-name)` 屬性。

 `PropagateTags`   <a name="sam-websocketapi-propagatetags"></a>
如果為 `true`，則 會將 `Tags` 屬性 AWS SAM 新增至 AWS SAM 產生的 `AWS::ApiGatewayV2::DomainName` `AWS::ApiGatewayV2::Stage`和資源。  
*類型*：布林值  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `Routes`   <a name="sam-websocketapi-routes"></a>
此 WebSocket API 的路由組態。路由定義訊息如何路由到 Lambda 函數。每個路由都包含路由金鑰和 Lambda 函數 ARN。  
WebSocket APIs 支援三個預先定義的路由：`$connect`、 `$disconnect`和 `$default`。您也可以定義自訂路由。  
*類型*：[RouteConfiguration](sam-property-websocketapi-routeconfiguration.md)  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

 `RouteSelectionExpression`   <a name="sam-websocketapi-routeselectionexpression"></a>
WebSocket API 的路由選擇表達式。如需詳細資訊，請參閱《 *API Gateway 開發人員指南*》中的[路由選擇表達式](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-route-selection-expressions)。  
常見值為 `$request.body.action`，它會根據訊息內文中的 `action` 欄位來路由訊息。  
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Api` 資源的 `[RouteSelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-routeselectionexpression)` 屬性。

 `RouteSettings`   <a name="sam-websocketapi-routesettings"></a>
此 WebSocket API 的路由設定。這些設定會覆寫特定路由`DefaultRouteSettings`的 。  
*類型*：[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Stage` 資源的 `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` 屬性。

 `StageName`   <a name="sam-websocketapi-stagename"></a>
API 階段的名稱。如果您未指定名稱， AWS SAM 會使用 `default`做為階段名稱。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Stage` 資源的 `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` 屬性。

 `StageVariables`   <a name="sam-websocketapi-stagevariables"></a>
定義階段變數的映射。變數名稱可以有英數字元和底線字元，且值必須符合 `[A-Za-z0-9-._~:/?#&=,]+`。  
*類型*：[Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGatewayV2::Stage` 資源的 `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` 屬性。

 `Tags`   <a name="sam-websocketapi-tags"></a>
映射 （字串到字串），指定要新增至此 WebSocket API 的標籤。如需標籤有效金鑰和值的詳細資訊，請參閱*CloudFormation 《 使用者指南*》中的[資源標籤](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)。  
*類型*：映射  
*必要*：否  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等的。

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

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

下列範例會建立具有三個路由的 WebSocket API。

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

### 具有 Lambda 授權方的 WebSocket API
<a name="sam-resource-websocketapi-examples-auth"></a>

下列範例會使用 Lambda 授權方建立 WebSocket API。

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