翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # WebSockets を使用して Amazon Chime SDK メッセージングでメッセージを受信する [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) を使用し WebSocket を使用してメッセージを受信することも、任意の WebSocket クライアントライブラリを使用することもできます。 WebSocket の使用を開始するには、以下のトピックを記載されている順序で実行してください。 **Topics** + [IAM ポリシーの定義](#define-iam-policy) + [エンドポイントの取得](#retrieve-endpoint) + [接続の確立](#connect-api) + [プリフェッチを使用してチャネルの詳細を配信する](#prefetch) + [イベントの処理](#process-events) ## IAM ポリシーの定義 まず、WebSocket 接続を確立するアクセス許可を付与する IAM ポリシーを定義します。以下のサンプルポリシーは、WebSocket 接続を確立する `AppInstanceUser` アクセス許可を付与します。 ``` "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action: [ "chime:Connect" ], "Resource": [ "arn:aws:chime:{{region}}:{{{aws_account_id}}}:app-instance/{{{app_instance_id}}}/user/{{{app_instance_user_id}}}" ] }, { "Effect": "Allow", "Action: [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] } ] } ``` ## エンドポイントの取得 以下の手順では、WebSocket 接続で使用されるエンドポイントを取得する方法について説明します。 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API を使用して WebSocket エンドポイントを取得します。 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API によって返された URL を使用して、署名バージョン 4 の署名付き WebSocket URL を構築します。その際にヘルプが必要な場合は、[接続の確立](#connect-api) の指示に従ってください。 **注記** WebSocket URL の形式は以下のとおりです: `{{id}}.{{region}}.ws-messaging.chime.aws` ## 接続の確立 エンドポイントを取得したら、接続 API を使用して Amazon Chime SDK バックエンドサーバーへの WebSocket 接続を確立し、`AppInstanceUser` からのメッセージを受信します。リクエストに署名するには、 AWS 署名バージョン 4 を使用する必要があります。リクエストへの署名に関する情報については、「[署名バージョン 4 を使用した AWS リクエストへの署名](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html)」を参照してください。 **注記** エンドポイントを取得するには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API を呼び出します。任意の WebSocket クライアントライブラリを使用してエンドポイントに接続できます。 **リクエストの構文** ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE%2F20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{{sessionId}}} &userArn={{{appInstanceUserArn}}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` **URI リクエストパラメータ** URI リクエストクエリパラメータはすべて URL でエンコードされている必要があります。 **X-Amz-Algorithm** AWS 署名のバージョンと、署名の計算に使用したアルゴリズムを識別します。Amazon Chime SDK は AWS 署名バージョン 4 認証のみをサポートしているため、この値は `AWS4-HMAC-SHA256` です。 **X-Amz-Credential** アクセスキー ID に加えて、このパラメータは署名が有効な AWS リージョンとサービス、つまりスコープも提供します。この値は、署名の計算で使用するスコープと一致する必要があります。このパラメータ値の一般的な形式は次のとおりです。 `<{{yourAccessKeyId}}>/<{{date}}>/<{{awsRegion}}>/<{{awsService}} >/aws4_request` 例えば、次のようになります。 `AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request` **X-Amz-Date** 日付と時刻の形式は ISO 8601 規格に準拠している必要があるため、`yyyyMMddTHHmmssZ` という形式にする必要があります。例えば、**2020 年 8 月 1 日 15:32:41.982-700** を協定世界時 (UTC) に変換し、`20200801T083241Z` として送信する必要があります。 **X-Amz-Signed-Headers** 署名の計算に使用したヘッダーを一覧表示します。署名計算には次のヘッダーが必要です。 + HTTP ホストヘッダー。 + リクエストに追加する予定のすべての x-amz-\* ヘッダー。 **注記** セキュリティを強化するため、リクエストに含める予定のすべてのリクエストヘッダーに署名します。 **X-Amz-Signatures** リクエストを認証するための署名を指定します。この署名は、Amazon Chime SDK が計算する署名と一致する必要があります。一致しない場合、Amazon Chime SDK はリクエストを拒否します。例えば、`733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`。 **X-Amz-Security-Token** Security Token Service から取得した認証情報を使用する場合のオプションの認証情報パラメータ。このサービスの詳細については、「[https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)」を参照してください。 **SessionId** 確立中の WebSocket 接続の一意の ID を示します。 **UserArn** 接続を確立しようとしている `AppInstanceUser` の ID を示します。値は、`AppInstanceUser` の ARN でなければなりません。例: `arn:aws:chime:{{us%2Deast%2D1}}:{{123456789012}}:app%2Dinstance/{{694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e}}/user/{{johndoe}}` ## プリフェッチを使用してチャネルの詳細を配信する WebSocket 接続を確立する際に、`CHANNEL_DETAILS` イベントを配信するようにクエリパラメータで `prefetch-on=connect` を指定できます。プリフェッチ機能は接続 API に付属しており、この機能によりユーザーは API を余分に呼び出さなくても充実したチャットビューを表示できます。ユーザーは次の操作を実行できます。 + 直近のチャネルメッセージのプレビューとそのタイムスタンプを表示する。 + チャネルのメンバーを表示する。 + チャネルの未読マーカーを表示する。 ユーザーがプリフェッチパラメータを指定して接続すると、接続が確立されたことを示すセッション確立イベントがユーザーに届きます。その後、ユーザーは最大 50 件の `CHANNEL_DETAILS` イベントを受信します。ユーザーのチャネル数が 50 個未満の場合、接続 API は `CHANNEL_DETAILS` イベントを介してすべてのチャネルをプリフェッチします。ユーザーのチャネルが 50 個を超える場合、API は未読メッセージと最新の `LastMessageTimestamp` 値を含む上位 50 個のチャネルをプリフェッチします。`CHANNEL_DETAILS` イベントはランダムな順序で到着し、ユーザーは 50 個のチャネルすべてのイベントを受信します。 また、プリフェッチは `ChannelMessages` と `ChannelMemberships` に対して以下を返します。 + **ChannelMessages** – [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) オブジェクトのリスト。降順で `CreatedTimestamp` によって順序付けられます。ユーザーに表示されている最新 20 件のメッセージのみが含まれます。現在のユーザーには表示されないターゲットを絞ったメッセージがチャネルにある場合、返されるメッセージは 20 件未満になる可能性があります。`ChannelMessagesHasMore` ブール値は true に設定され、メッセージが他にもあることを示します。ソフト制限、 AWS アカウントレベルで調整可能。 + **ChannelMemberships** – [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html) オブジェクトのリスト 最大 30 人のチャネルメンバーが含まれます。ソフト制限、 AWS アカウントレベルで調整可能。 次の例では、`prefetch-on=connect` の使用方法を示します。 ``` GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential={{AKIARALLEXAMPLE}}%2F{{20201214}}%2F{{region}}%2Fchime%2Faws4_request &X-Amz-Date={{20201214T171359Z}} &X-Amz-Expires={{10}} &X-Amz-SignedHeaders=host &sessionId={{sessionId}} &prefetch-on=connect &userArn={{appInstanceUserArn}} &X-Amz-Signature={{db75397d79583EXAMPLE}} ``` この例は、1 つのチャネルのレスポンスを示しています。50 個のチャネルすべてについてのレスポンスが届きます。 ``` { "Headers": { "x-amz-chime-event-type": "CHANNEL_DETAILS", "x-amz-chime-message-type": "SYSTEM" }, "Payload": JSON.stringify"({ Channel: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html) ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ) ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) } ``` ## イベントの処理 `AppInstanceUser` が接続を確立した後にメッセージを受信するには、メッセージをチャネルに追加する必要があります。そのためには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API を使用します。 **注記** `AppInstanceUser` は、自分が属しているすべてのチャネルのメッセージを常に受信します。`AppInstance` ユーザーが接続を切断すると、メッセージングは停止します。 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API を使用してメッセージを明示的に追加しない限り、`AppInstanceAdmin` および `ChannelModerator` はチャネルでメッセージを受信しません。 以下のトピックでは、イベントを処理する方法について説明します。 **Topics** + [メッセージの構造について](#message-structures) + [切断への対応](#handle-disconnects) ### メッセージの構造について 受信するすべての WebSocket メッセージは、以下の形式に従います。 ``` { "Headers": {"{{key}}": "{{value}}"}, "Payload": "{\"{{key}}\": \"{{value}}\"}" } ``` **ヘッダー** Amazon Chime SDK メッセージングでは、以下のヘッダーキーを使用します。 + `x-amz-chime-event-type` + `x-amz-chime-message-type` + `x-amz-chime-event-reason` 次のセクションでは、ヘッダーで有効な値およびペイロードを示して説明します。 **ペイロード** Websocket メッセージは JSON 文字列を返します。JSON 文字列の構造は `x-amz-event-type` ヘッダーによって異なります。以下の表に、有効な `x-amz-chime-event-type` 値とペイロードを示します。
EventTypeペイロード形式
`SESSION_ESTABLISHED`該当なし。このメッセージは、ユーザーが WebSocket に接続した後に 1 回送信されます。これは、ユーザーが `SESSION_ESTABLISHED` メッセージを受信した後に到着したチャネル上のメッセージまたはイベントは、WebSocket が開いたままである限り、ユーザーに配信されることが保証されていることを示しています。
`CREATE_CHANNEL_MESSAGE` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessage.html)
`REDACT_CHANNEL_MESSAGE`
`UPDATE_CHANNEL_MESSAGE`
`DELETE_CHANNEL_MESSAGE`
`PENDING_CREATE_CHANNEL_MESSAGE`
`PENDING_UPDATE_CHANNEL_MESSAGE`
`FAILED_CREATE_CHANNEL_MESSAGE`
`FAILED_UPDATE_CHANNEL_MESSAGE`
`DENIED_CREATE_CHANNEL_MESSAGE`
`DENIED_UPDATE_CHANNEL_MESSAGE`
`CHANNEL_DETAILS`[See the AWS documentation website for more details](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/websockets.html)
`UPDATE_CHANNEL` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Channel.html)
`DELETE_CHANNEL`
`BATCH_CREATE_CHANNEL_MEMBERSHIP` [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchChannelMemberships.html)
`CREATE_CHANNEL_MEMBERSHIP`[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembership.html)
`DELETE_CHANNEL_MEMBERSHIP`
`UPDATE_CHANNEL_MEMBERSHIP`
**x-amz-chime-message-type** 以下の表に `x-amz-chime-message-type` メッセージタイプを示します。 | メッセージタイプ | 説明 | | --- | --- | | `STANDARD` | Websocket が STANDARD チャネルメッセージを受信すると送信されます。 | | `CONTROL` | WebSocket が CONTROL チャネルメッセージを受信したときに送信されます。 | | `SYSTEM` | Amazon Chime SDK メッセージングによって送信されるその他すべての Websocket メッセージ。 | **x-amz-chime-event-reason** これは特定のユースケースでサポートされるオプションのヘッダーです。ヘッダーには、特定のイベントを受信した理由に関する情報が表示されます。 | イベント理由 | 説明 | | --- | --- | | subchannel\_DELETED | Elastic チャネルモデレーターが受信した `DELETE_CHANNEL_MEMBERSHIP` イベント。メンバーシップバランシングにより属していたサブチャネルが削除された後、モデレーターにのみ表示されます。 | ### 切断への対応 WebSocket は、ネットワーク接続の変化や認証情報の有効期限が切れると切断されることがあります。ユーザーが WebSocket を開くと、Amazon Chime SDK からメッセージングクライアントに定期的に ping が送信され、接続状態の維持が確認されます。接続が終了すると、クライアントは WebSocket クローズコードを受信します。クローズコードによっては、クライアントが再接続できる場合とできない場合があります。次の表は、クライアントが再接続に使用できるクローズコードを示しています。 1000～4000 のクローズコードについては、次のメッセージの場合にのみ再接続してください。 | クローズコード | 再接続可能 | Reason | | --- | --- | --- | | 1001 | はい | 正常なクローズ | | 1006 | はい | 異常なクローズ | | 1011 | はい | 内部サーバーエラー | | 1012 | はい | サービスの再起動 | | 1013 | はい | 後でもう一度試してみてください | | 1014 | はい | サーバーは、ゲートウェイまたはプロキシとして機能しており、上流サーバーから無効な応答を受信しました。これは 502 の HTTP ステータスコードに似ています。 | 4XXX コードの場合は、常に再接続できます。ただし、次のメッセージを除きます。 | クローズコード | 再接続可能 | Reason | | --- | --- | --- | | 4002 | いいえ | クライアント自身によるクローズ | | 4003 | いいえ | Forbidden | | 4401 | いいえ | 権限がありません | アプリケーションが再接続にクローズコードを使用する場合、アプリケーションには、次の動作が求められます。 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API を再度呼び出して、新しいベース URL を取得します。 1. IAM 認証情報の有効期限が切れている場合は更新する。 1. WebSocket を介して接続する。 amazon-chime-sdk-js ライブラリを使用して [needsRefresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) プロパティと [refresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) メソッドを実装すると、上記の操作を行えます。有効なコード例については、次を参照してください: [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx\#L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101)