API Gateway WebSocket：モック統合の実装

バックエンドのLambdaを一切使わず、モック統合のみでAPI Gateway WebSocket APIを構築し、あらかじめ用意されたレスポンスを返します。

Takahiro Iwasa

2024-07-07

5 min read

API Gatewayのモック統合を使えば、背後にバックエンドを一切置かずに、あらかじめ用意されたWebSocketレスポンスを返すことができます。これは、実際のビジネスロジックが完成する前にルーティングやレスポンスの形を検証するのに便利です。

Integrations for WebSocket APIs in API Gateway

構築

68行目の$input.path('$.messageId')によってmessageIdが引き渡されます。
- API Gateway mapping template and access logging variable reference
77行目と84行目にある統合レスポンスのキーはstatusCodeである必要があります。
- Data transformations for WebSocket APIs in API Gateway
85〜87行目にあるmessageルートのレスポンステンプレートは、messageIdの値に応じてレスポンスを変更します。

1
AWSTemplateFormatVersion: 2010-09-09
2
Description: API Gateway WebSocket with Mock Integration
3
Resources:
4
  ApiGatewayV2Api:
5
    Type: AWS::ApiGatewayV2::Api
6
    Properties:
7
      Name: api-gateway-websocket-with-mock-integration
8
      ProtocolType: WEBSOCKET
9
      RouteSelectionExpression: $request.body.action
10

11
  ApiGatewayV2Stage:
12
    Type: AWS::ApiGatewayV2::Stage
13
    Properties:
14
      StageName: production
15
      ApiId: !Ref ApiGatewayV2Api
16
      AutoDeploy: true
17

18
  ApiGatewayV2RouteOnConnect:
19
    Type: AWS::ApiGatewayV2::Route
20
    Properties:
21
      ApiId: !Ref ApiGatewayV2Api
22
      RouteKey: $connect
23
      RouteResponseSelectionExpression: $default
24
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnConnect}
25

26
  ApiGatewayV2RouteOnMessage:
27
    Type: AWS::ApiGatewayV2::Route
28
    Properties:
29
      ApiId: !Ref ApiGatewayV2Api
30
      RouteKey: message
31
      RouteResponseSelectionExpression: $default
32
      Target: !Sub integrations/${ApiGatewayV2IntegrationOnMessage}
33

34
  ApiGatewayV2RouteResponseOnConnect:
35
    Type: AWS::ApiGatewayV2::RouteResponse
36
    Properties:
37
      ApiId: !Ref ApiGatewayV2Api
38
      RouteResponseKey: $default
39
      RouteId: !Ref ApiGatewayV2RouteOnConnect
40

41
  ApiGatewayV2RouteResponseOnMessage:
42
    Type: AWS::ApiGatewayV2::RouteResponse
43
    Properties:
44
      ApiId: !Ref ApiGatewayV2Api
45
      RouteResponseKey: $default
46
      RouteId: !Ref ApiGatewayV2RouteOnMessage
47

48
  ApiGatewayV2IntegrationOnConnect:
49
    Type: AWS::ApiGatewayV2::Integration
50
    Properties:
51
      ApiId: !Ref ApiGatewayV2Api
52
      ConnectionType: INTERNET
53
      IntegrationType: MOCK
54
      PassthroughBehavior: WHEN_NO_MATCH
55
      RequestTemplates:
56
        '$default': '{"statusCode": 200}'
57
      TimeoutInMillis: 29000
58
      PayloadFormatVersion: '1.0'
59

60
  ApiGatewayV2IntegrationOnMessage:
61
    Type: AWS::ApiGatewayV2::Integration
62
    Properties:
63
      ApiId: !Ref ApiGatewayV2Api
64
      ConnectionType: INTERNET
65
      IntegrationType: MOCK
66
      PassthroughBehavior: WHEN_NO_MATCH
67
      RequestTemplates:
68
        '$default': '{"statusCode": 200, "messageId": $input.path(''$.messageId'')}'
69
      TimeoutInMillis: 29000
70
      PayloadFormatVersion: '1.0'
71

72
  ApiGatewayV2IntegrationResponseOnConnect:
73
    Type: AWS::ApiGatewayV2::IntegrationResponse
74
    Properties:
75
      ApiId: !Ref ApiGatewayV2Api
76
      IntegrationId: !Ref ApiGatewayV2IntegrationOnConnect
77
      IntegrationResponseKey: /200/
78

79
  ApiGatewayV2IntegrationResponseOnMessage:
80
    Type: AWS::ApiGatewayV2::IntegrationResponse
81
    Properties:
82
      ApiId: !Ref ApiGatewayV2Api
83
      IntegrationId: !Ref ApiGatewayV2IntegrationOnMessage
84
      IntegrationResponseKey: /200/
85
      ResponseTemplates:
86
        '1': '{"message": "Hello World"}'
87
        '2': '{"message": "Hi!"}'
88
      TemplateSelectionExpression: ${request.body.messageId}
89

90
Outputs:
91
  ApiGatewayV2ApiEndpoint:
92
    Value: !GetAtt ApiGatewayV2Api.ApiEndpoint

次のコマンドでCloudFormationスタックをデプロイします。

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

デプロイされたAPI Gatewayのエンドポイントを取得するには、次のコマンドを使用します。

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

出力例:

1
[
2
  {
3
    "OutputKey": "ApiGatewayV2ApiEndpoint",
4
    "OutputValue": "wss://<id>.execute-api.<region>.amazonaws.com"
5
  }
6
]

テスト

WebSocketクライアントとしてwscatをインストールします。

npm i wscat

次のコマンドを実行してWebSocketエンドポイントに接続します。新規接続には$connectルートが使用されます。

wscat -c wss://<id>.execute-api.<region>.amazonaws.com/production/

テストメッセージを送信し、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 APIを構築したところ、バックエンドのLambdaを一切デプロイすることなく、受信したmessageIdに応じて異なるあらかじめ用意されたレスポンスが返ってきました。ここでモック統合が機能するのは、「バックエンド」がmessageIdをキーにした単なる静的なレスポンステンプレートに過ぎないからです。これは、実際のバックエンドが存在する前にWebSocket APIのルーティングとレスポンス形状をプロトタイピングするのに適しています。$connectルートとmessageルートが期待通りに動作するかを検証するためだけに、Lambda関数や永続的な接続処理を書く必要はありません。とはいえ、TemplateSelectionExpressionがサポートするのはここで示したような静的な値ベースの分岐だけです。実際の計算や永続化、他のサービスの呼び出しが必要になる場合は、VTLテンプレートだけではそれを表現できないため、モック統合をLambda統合やHTTP統合に置き換える必要があります。

記事一覧に戻る