翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

Amazon API Gateway WebSocket API を作成します。これにより、双方向のインタラクティブ通信アプリケーションを作成できます。WebSocket APIsを使用すると、サーバーはクライアントにメッセージをリクエストすることなくメッセージを送信できます。詳細については、[APIsWebSocket ](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 ゲートウェイデベロッパーガイド*」の「[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 リソースを CloudFormation リソース AWS SAM に変換します。詳細については、「[の生成済み 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}}
```

## プロパティ
<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 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` プロパティによって上書きされる場合を除き、すべてのルートに適用されます。  
*Type*: [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`、IPv4 および IPv6 `dualstack`です。  
*タイプ*: 文字列  
*必須:* いいえ  
*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`、 が AWS SAM 生成する `AWS::ApiGatewayV2::Stage`および `AWS::ApiGatewayV2::DomainName`リソースに `Tags`プロパティ AWS SAM を追加します。  
型: ブール  
*必須:* いいえ  
*CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のプロパティはありません。

 `Routes`   <a name="sam-websocketapi-routes"></a>
この WebSocket API のルート設定。ルートは、メッセージが Lambda 関数にルーティングされる方法を定義します。各ルートは、ルートキーと Lambda 関数 ARN で構成されます。  
WebSocket APIs`$connect`、、`$disconnect`および の 3 つの事前定義されたルートをサポートします`$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`の を上書きします。  
*Type*: [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 ステージの名前です。名前を指定しない場合、ステージ名`default`として AWS SAM を使用します。  
*タイプ*: 文字列  
*必須:* いいえ  
*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>

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

次の例では、3 つのルートを持つ 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
```