API Gateway WebSocket で Mock 統合を設定する方法

岩佐孝浩

2024年7月7日

4 min read

API Gateway WebSocket Mock Integration

AWS ユーザーは、 API Gateway と Mock 統合を利用して WebSocket サーバーを迅速に構築できます。

Integrations for WebSocket API in API Gateway - Amazon API Gateway

docs.aws.amazon.com

Integrations for WebSocket API in API Gateway - Amazon API Gateway

Learn how to add integrations to a WebSocket API.

AWS リソース作成

以下の内容で CloudFormation テンプレートを作成してください。

重要なポイントは以下のとおりです。

68行目の $input.path('$.messageId') で、 messageId をパスしています。マッピングテンプレートについては、公式ドキュメントをご参照ください。
77行目と84行目の統合レスポンスキーは、 statusCode です。 AWS 公式ドキュメントに、“For HTTP and MOCK integrations, it is $integration.response.statuscode”. と記載されています。
85行目から87行目の message ルートでレスポンステンプレートを指定することで、 messageId の値にしたがってレスポンスが変化します。

AWSTemplateFormatVersion: 2010-09-09
Description: API Gateway WebSocket with Mock Integration
Resources:
  ApiGatewayV2Api:
    Type: AWS::ApiGatewayV2::Api
    Properties:
      Name: api-gateway-websocket-with-mock-integration
      ProtocolType: WEBSOCKET
      RouteSelectionExpression: $request.body.action

  ApiGatewayV2Stage:
    Type: AWS::ApiGatewayV2::Stage
    Properties:
      StageName: production
      ApiId: !Ref ApiGatewayV2Api
      AutoDeploy: true

  ApiGatewayV2RouteOnConnect:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      RouteKey: $connect
      RouteResponseSelectionExpression: $default
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnConnect}

  ApiGatewayV2RouteOnMessage:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      RouteKey: message
      RouteResponseSelectionExpression: $default
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnMessage}

  ApiGatewayV2RouteResponseOnConnect:
    Type: AWS::ApiGatewayV2::RouteResponse
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      RouteResponseKey: $default
      RouteId: !Ref ApiGatewayV2RouteOnConnect

  ApiGatewayV2RouteResponseOnMessage:
    Type: AWS::ApiGatewayV2::RouteResponse
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      RouteResponseKey: $default
      RouteId: !Ref ApiGatewayV2RouteOnMessage

  ApiGatewayV2IntegrationOnConnect:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      ConnectionType: INTERNET
      IntegrationType: MOCK
      PassthroughBehavior: WHEN_NO_MATCH
      RequestTemplates:
        '$default': '{"statusCode": 200}'
      TimeoutInMillis: 29000
      PayloadFormatVersion: '1.0'

  ApiGatewayV2IntegrationOnMessage:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      ConnectionType: INTERNET
      IntegrationType: MOCK
      PassthroughBehavior: WHEN_NO_MATCH
      RequestTemplates:
        '$default': '{"statusCode": 200, "messageId": $input.path(''$.messageId'')}'
      TimeoutInMillis: 29000
      PayloadFormatVersion: '1.0'

  ApiGatewayV2IntegrationResponseOnConnect:
    Type: AWS::ApiGatewayV2::IntegrationResponse
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      IntegrationId: !Ref ApiGatewayV2IntegrationOnConnect
      IntegrationResponseKey: /200/

  ApiGatewayV2IntegrationResponseOnMessage:
    Type: AWS::ApiGatewayV2::IntegrationResponse
    Properties:
      ApiId: !Ref ApiGatewayV2Api
      IntegrationId: !Ref ApiGatewayV2IntegrationOnMessage
      IntegrationResponseKey: /200/
      ResponseTemplates:
        '1': '{"message": "Hello World"}'
        '2': '{"message": "Hi!"}'
      TemplateSelectionExpression: ${request.body.messageId}

Outputs:
  ApiGatewayV2ApiEndpoint:
    Value: !GetAtt ApiGatewayV2Api.ApiEndpoint

以下のコマンドで CloudFormation スタックをデプロイしてください。

aws cloudformation deploy \
--template-file template.yaml \
--stack-name api-gateway-websocket-with-mock-integration

テスト用の値を確認するために、以下のコマンドを実行してください。

$ aws cloudformation describe-stacks \
--stack-name api-gateway-websocket-with-mock-integration \
| jq ".Stacks[0].Outputs"

[
  {
    "OutputKey": "ApiGatewayV2ApiEndpoint",
    "OutputValue": "wss://<id>.execute-api.<region>.amazonaws.com"
  }
]

テスト

WebSocket クライアントとして wscat をインストールしてください。

npm i wscat

以下のコマンドを実行して、 API Gateway WebSocket エンドポイントに接続してください。接続時は $connect ルートが利用されます。

$ wscat -c wss://<id>.execute-api.<region>.amazonaws.com/production/
Connected (press CTRL+C to quit)

以下のコマンドを実行して、テストメッセージを送信してください。 messageId に基づいて、レスポンスが変化します。

> {"action": "message", "messageId": 1}
< {"message": "Hello World"}
> {"action": "message", "messageId": 2}
< {"message": "Hi!"}

クリーンアップ

以下のコマンドを使用して、プロビジョニングされた AWS リソースを削除してください。

aws cloudformation delete-stack --stack-name api-gateway-websocket-with-mock-integration

まとめ

API Gateway WebSocket エンドポイントに接続するアプリケーションの開発中は、 Mock 統合を利用すると、サーバーの実装を待つことなくクライアントを実装できます。

この投稿が、お役に立てば幸いです。