翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

WebSockets を使用して Amazon Chime SDK メッセージングでメッセージを受信する

Amazon Chime JS SDK を使用し WebSocket を使用してメッセージを受信することも、任意の WebSocket クライアントライブラリを使用することもできます。

WebSocket の使用を開始するには、以下のトピックを記載されている順序で実行してください。

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 接続で使用されるエンドポイントを取得する方法について説明します。

接続の確立

エンドポイントを取得したら、接続 API を使用して Amazon Chime SDK バックエンドサーバーへの WebSocket 接続を確立し、AppInstanceUser からのメッセージを受信します。リクエストに署名するには、 AWS 署名バージョン 4 を使用する必要があります。リクエストへの署名に関する情報については、「署名バージョン 4 を使用した AWS リクエストへの署名」を参照してください。

リクエストの構文

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

署名の計算に使用したヘッダーを一覧表示します。署名計算には次のヘッダーが必要です。

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 接続を確立する際に、CHANNEL_DETAILS イベントを配信するようにクエリパラメータで prefetch-on=connect を指定できます。プリフェッチ機能は接続 API に付属しており、この機能によりユーザーは API を余分に呼び出さなくても充実したチャットビューを表示できます。ユーザーは次の操作を実行できます。

ユーザーがプリフェッチパラメータを指定して接続すると、接続が確立されたことを示すセッション確立イベントがユーザーに届きます。その後、ユーザーは最大 50 件の CHANNEL_DETAILS イベントを受信します。ユーザーのチャネル数が 50 個未満の場合、接続 API は CHANNEL_DETAILS イベントを介してすべてのチャネルをプリフェッチします。ユーザーのチャネルが 50 個を超える場合、API は未読メッセージと最新の LastMessageTimestamp 値を含む上位 50 個のチャネルをプリフェッチします。CHANNEL_DETAILS イベントはランダムな順序で到着し、ユーザーは 50 個のチャネルすべてのイベントを受信します。

また、プリフェッチは ChannelMessages と ChannelMemberships に対して以下を返します。

次の例では、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 を使用します。

CreateChannelMembership API を使用してメッセージを明示的に追加しない限り、AppInstanceAdmin および ChannelModerator はチャネルでメッセージを受信しません。

以下のトピックでは、イベントを処理する方法について説明します。

メッセージの構造について

受信するすべての WebSocket メッセージは、以下の形式に従います。

{
   "Headers": {"key": "value"},
   "Payload": "{\"key\": \"value\"}"
}

ヘッダー

Amazon Chime SDK メッセージングでは、以下のヘッダーキーを使用します。

次のセクションでは、ヘッダーで有効な値およびペイロードを示して説明します。

ペイロード

Websocket メッセージは JSON 文字列を返します。JSON 文字列の構造は x-amz-event-type ヘッダーによって異なります。以下の表に、有効な x-amz-chime-event-type 値とペイロードを示します。

x-amz-chime-message-type

以下の表に x-amz-chime-message-type メッセージタイプを示します。

x-amz-chime-event-reason

これは特定のユースケースでサポートされるオプションのヘッダーです。ヘッダーには、特定のイベントを受信した理由に関する情報が表示されます。

切断への対応

WebSocket は、ネットワーク接続の変化や認証情報の有効期限が切れると切断されることがあります。ユーザーが WebSocket を開くと、Amazon Chime SDK からメッセージングクライアントに定期的に ping が送信され、接続状態の維持が確認されます。接続が終了すると、クライアントは WebSocket クローズコードを受信します。クローズコードによっては、クライアントが再接続できる場合とできない場合があります。次の表は、クライアントが再接続に使用できるクローズコードを示しています。

1000～4000 のクローズコードについては、次のメッセージの場合にのみ再接続してください。

4XXX コードの場合は、常に再接続できます。ただし、次のメッセージを除きます。

アプリケーションが再接続にクローズコードを使用する場合、アプリケーションには、次の動作が求められます。

amazon-chime-sdk-js ライブラリを使用して needsRefresh() プロパティと refresh() メソッドを実装すると、上記の操作を行えます。有効なコード例については、次を参照してください: https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101