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

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

Takahiro Iwasa

2024-07-07

4 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 統合、または AWS サービス統合を使用します。

記事一覧に戻る