AWS AppSync GraphQLをPostmanからSubscribeする

大阪オフィスの小倉です。

AWS AppSync GraphQLを使った開発をしていたときに、PostmanからGraphQLのSubscriptionに接続する方法を調べたという小ネタです。
Postmanクライアントは、執筆時点のMacOS(Apple Chip)用最新バージョン(11.47.1)を使用しています。

Query、Mutationの場合

QueryとMutationの場合は、「GraphQL」を選択してRequestを作成すればOKです。
事前にSchemaタブの「Using GraphQL Introspection」からAPI定義を取得すれば簡単にリクエストを記述できます。

Subscriptionの場合

本題です。

今回は以下のスキーマ定義をAWS CDKでデプロイしておき、onMessageSentというSubscriptionに接続します。
sendMessageというMutationが実行されれば、onMessageSentにデータが流れてくる想定です。

今回は認証方法にAPI Keyを利用する方法で接続します。

type Message @aws_iam @aws_api_key{
  id: ID!
  content: String!
}

type Mutation {
  sendMessage(content: String!): Message
  @aws_iam @aws_api_key
}

type Subscription {
  onMessageSent: Message
    @aws_subscribe(mutations: ["sendMessage"])
    @aws_iam @aws_api_key
}

type Query {
  dummy: String
  @aws_iam @aws_api_key
}

Postmanの画面でRequestを作成します。
Subscriptionの場合は、「GraphQL」ではなく「WebSocket」のRequestを選択します。

まずHeadersに sec-websocket-protocol : graphql-wsを追加します。

次に、以下の形式にあわせてリクエストURLを作成します。

wss://xxxx.appsync-realtime-api.ap-northeast-1.amazonaws.com/graphql?header=<Base64エンコード文字列>&payload=e30=

1. wss://......amazonaws.com/graphql の部分はAppSyncのリアルタイムエンドポイントを指定します。
2. header=に指定する値は、以下のJSONをBase64エンコードした結果の文字列をセットします。

{
    "host":"xxxx.appsync-api.ap-northeast-1.amazonaws.com", # AppSyncのGraphQLエンドポイントのホスト名。エンドポイントの値から`https://`を削除したもの
    "x-api-key":"<API KEY>" # APIキーの値
}

作成したHeadersとURLをセットし、「Connect」を押すと接続されます。
接続後、{"type":"ka"}というkeep-aliveメッセージが定期的に届いています。

最後に以下のイメージになるようにMessageにセットする値を作成します。

{
  "id": "<適当な値>",
  "payload": {
  "data": "{\"query\":\"subscription MySubscription {\\n  onMessageSent {\\n    content\\n    id\\n  }\\n}\",\"variables\":null}",
      "extensions": {
        "authorization": {
          "x-api-key": "<API KEY>",
          "host": "xxxx.appsync-api.ap-northeast-1.amazonaws.com"
         }
      }
  },
  "type": "start"
}

1. idの値は他の接続と重複しなければ、適当な値で良さそうです
2. payload.data の部分に、Subscriptionのクエリをエスケープしながらセットします。payload.data.extensionsにはAPIキーの値とGraphQLエンドポイントのホスト名をセットします。

作成したMessageの値をセットし、「Send」を押すと、Subscribeが開始されます。

Subscriptionに対応するMutationを発生させると、Subscriptionからデータを受信していることがわかります。

まとめ

PostmanからGraphQL Subscriptionに接続してみました。
Subscriptionクエリを自分でエスケープするのが若干手間ですね。。。マネジメントコンソールで事足りるのであれば、コンソールからSubscribeするほうがお手軽かもしれません。

今回はAPI KEY認証の方法のみ試しましたが、参考URLのドキュメントに従えばOIDC等他の認証方法の場合でも、同様に接続できるのではないでしょうか。

どなたかの参考になれば幸いです。

参考

• Building a real-time WebSocket client in AWS AppSync
• AWS appsync subscription fails to connect