翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
WebSockets を使用したメッセージの受信
Amazon Chime JS SDK
の使用を開始するには、リストされている順序で以下のトピックに従ってください WebSockets。
IAM ポリシーの定義
開始するには、 WebSocket 接続を確立するアクセス許可を付与する IAM ポリシーを定義します。次のポリシー例では、接続を確立するAppInstanceUser
アクセス許可を に付与します WebSocket。
"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 接続で使用されるエンドポイントを取得する方法について説明します。
GetMessagingSessionEndpoint API を使用して WebSocket エンドポイントを取得します。
GetMessagingSessionEndpoint API によって返される URL を使用して、署名バージョン 4 の署名付き WebSocket URL を作成します。その際にヘルプが必要な場合は、接続の確立 の指示に従ってください。
注記
WebSocket URLsの形式は次のとおりです。
id
.region
.ws-messaging.chime.aws
接続の確立
エンドポイントを取得したら、Connect API を使用して Amazon Chime SDK バックエンドサーバー WebSocket への接続を確立し、 のメッセージを受信しますAppInstanceUser
。リクエストに署名するには、 AWS 署名バージョン 4 を使用する必要があります。リクエストの署名の詳細については、「署名バージョン 4 によるリクエストの署名 AWS」を参照してください。
注記
エンドポイントを取得するには、 GetMessagingSessionEndpoint API を呼び出します。選択した WebSocket クライアントライブラリを使用してエンドポイントに接続できます。
リクエストの構文
GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=
AKIARALLEXAMPLE%2F20201214
%2Fregion
%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/」を参照してください。
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 接続を確立するときに、クエリパラメータprefetch-on=connect
で を指定してCHANNEL_DETAILS
イベントを配信できます。プリフェッチ機能は接続 API に付属しており、この機能によりユーザーは API を余分に呼び出さなくても充実したチャットビューを表示できます。ユーザーは次の操作を実行できます。
直近のチャネルメッセージのプレビューとそのタイムスタンプを表示する。
チャネルのメンバーを表示する。
チャネルの未読マーカーを表示する。
ユーザーがプリフェッチパラメータを指定して接続すると、接続が確立されたことを示すセッション確立イベントがユーザーに届きます。その後、ユーザーは最大 50 件の CHANNEL_DETAILS
イベントを受信します。ユーザーのチャネル数が 50 個未満の場合、接続 API は CHANNEL_DETAILS
イベントを介してすべてのチャネルをプリフェッチします。ユーザーのチャネルが 50 個を超える場合、API は未読メッセージと最新の LastMessageTimestamp
値を含む上位 50 個のチャネルをプリフェッチします。CHANNEL_DETAILS
イベントはランダムな順序で到着し、ユーザーは 50 個のチャネルすべてのイベントを受信します。
また、プリフェッチは ChannelMessages
と ChannelMemberships
に対して以下を返します。
ChannelMessages - ChannelMessageSummary オブジェクトのリスト。降順
CreatedTimestamp
で並べられます。ユーザーに表示されている最新 20 件のメッセージのみが含まれます。現在のユーザーには表示されないターゲットを絞ったメッセージがチャネルにある場合、返されるメッセージは 20 件未満になる可能性があります。ChannelMessagesHasMore
ブール値は true に設定され、メッセージが他にもあることを示します。 AWS アカウントレベルで調整可能なソフト制限。ChannelMemberships – ChannelMembershipSummary オブジェクトのリスト。最大 30 人のチャネルメンバーが含まれます。ソフト制限、 AWS アカウントレベルで調整可能。
次の例では、prefetch-on=connect
の使用方法を示します。
GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=
AKIARALLEXAMPLE
%2F20201214
%2Fregion
%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: ChannelSummary ChannelMessages: List of ChannelMessageSummary ChannelMemberships: List of ChannelMembershipSummary ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) }
イベントの処理
AppInstanceUser
が接続を確立した後にメッセージを受信するには、メッセージをチャネルに追加する必要があります。そのためには、 CreateChannelMembership API を使用します。
注記
AppInstanceUser
は、自分が属しているすべてのチャネルのメッセージを常に受信します。AppInstance
ユーザーが接続を切断すると、メッセージングは停止します。
CreateChannelMembership API を使用して明示的に追加しない限り、 AppInstanceAdmin
と はチャネルでメッセージを受信ChannelModerator
しません。
以下のトピックでは、イベントを処理する方法について説明します。
メッセージの構造について
受信するすべての 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 | ペイロード形式 |
---|---|
|
該当なし。 このメッセージは、ユーザーが に接続した後に 1 回送信されます WebSocket。これは、ユーザーがメッセージを受信した後に到着するチャネル上の |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-type
以下の表に x-amz-chime-message-type
メッセージタイプを示します。
メッセージの種類 | 説明 |
---|---|
|
Websocket が STANDARD チャネルメッセージを受信すると送信されます。 |
|
が「コントロールチャネル」メッセージ WebSocket を受信すると送信されます。 |
|
Amazon Chime SDK メッセージングによって送信されるその他すべての Websocket メッセージ。 |
x-amz-chime-event-reason
これは特定のユースケースでサポートされるオプションのヘッダーです。ヘッダーには、特定のイベントを受信した理由に関する情報が表示されます。
イベント理由 | 説明 |
---|---|
subchannel_DELETED |
Elastic チャネルモデレーターが受信した |
切断への対応
WebSocket は、ネットワーク接続の変化や認証情報の有効期限が切れると切断されることがあります。を開くと WebSocket、Amazon Chime SDK はメッセージングクライアントに通常の ping を送信して、まだ接続されていることを確認します。接続が閉じると、クライアントは WebSocket クローズコードを受け取ります。クローズコードによっては、クライアントが再接続できる場合とできない場合があります。次の表は、クライアントが再接続に使用できるクローズコードを示しています。
1000~4000 のクローズコードについては、次のメッセージの場合にのみ再接続してください。
クローズコード |
再接続可能 |
理由 |
---|---|---|
1001 |
はい |
正常なクローズ |
1006 |
はい |
異常なクローズ |
1011 |
はい |
内部サーバーエラー |
1012 |
はい |
サービスの再起動 |
1013 |
はい |
後でもう一度試してみてください |
1014 |
はい |
サーバーは、ゲートウェイまたはプロキシとして機能しており、上流サーバーから無効な応答を受信しました。これは 502 の HTTP ステータスコードに似ています。 |
4XXX コードの場合は、常に再接続できます。ただし、次のメッセージを除きます。
クローズコード |
再接続可能 |
理由 |
---|---|---|
4002 |
いいえ |
クライアント自身によるクローズ |
4003 |
いいえ |
Forbidden |
4401 |
いいえ |
権限がありません |
アプリケーションが再接続にクローズコードを使用する場合、アプリケーションには、次の動作が求められます。
-
GetMessagingSessionEndpoint API を再度呼び出して、新しいベース URL を取得します。
IAM 認証情報の有効期限が切れている場合は更新する。
-
経由で接続します WebSocket。
amazon-chime-sdk-js ライブラリを使用する場合、 needsRefresh () プロパティと refresh() メソッドを実装すると、これが処理されます。実際の例については、https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101