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

# アプリケーションとウェブクライアント間のデータチャネル通信
<a name="data-channels"></a>

 データチャネルを使用すると、Amazon GameLift Streams アプリケーションとウェブクライアント (エンドユーザーのウェブブラウザで実行されている JavaScript コード) の間で任意のメッセージを安全に通信できます。これにより、エンドユーザーはストリームを表示しているウェブブラウザを介して、Amazon GameLift Streams がストリーミングしているアプリケーションとやり取りできます。

Amazon GameLift Streams のデータチャネルのユースケースの例を次に示します。
+ ユーザーはローカルブラウザでアプリケーションで URLs を開くことができます。
+ ユーザーはクリップボード内のコンテンツをアプリケーションに前後に渡すことができます。
+ ユーザーはローカルマシンからアプリケーションにコンテンツをアップロードできます。
+ 開発者は、アプリケーションにコマンドを送信する UI をブラウザに実装できます。
+ ユーザーはスキーマを渡して、視覚化レイヤーの表示を制御できます。

## 特徴
<a name="data-channels-features"></a>

**メッセージのサイズ制限**  
Amazon GameLift Streams Web SDK は、メッセージあたり 64 KB (65536 バイト) の最大サイズ制限を課します。これにより、メッセージサイズ制限がほとんどのブラウザと互換性があり、通信がストリームの合計帯域幅に与える影響が低くなります。

**メトリクス**  
 データチャネル使用状況のメトリクスは、ストリームセッションが終了すると AWS アカウントに送信されます。詳細については、「Amazon GameLift ストリームのモニタリング」セクション[データチャネル](monitoring-cloudwatch.md#monitoring-data-channels)の「」を参照してください。 * GameLift * 

## データチャネルの使用
<a name="data-channels-using"></a>

Amazon GameLift Streams Web SDK は、アプリケーションにバイト配列としてメッセージを送信する `sendApplicationMessage`関数を提供します。メッセージは、定義したコールバック関数によって処理`clientConnection.applicationMessage`されます。

アプリケーションがデータチャネルポートに接続する前にクライアントがメッセージを送信すると、メッセージはキューに入れられます。次に、アプリケーションが接続すると、メッセージを受信します。ただし、クライアントがデータチャネルポートに接続する前にアプリケーションがメッセージを送信すると、メッセージは失われます。アプリケーションは、メッセージを送信する前にクライアントの接続状態を確認する必要があります。

## クライアント側
<a name="data-channels-using-client"></a>

ウェブクライアントアプリケーションに次のコードを記述します。

1.  アプリケーションから受信メッセージを受信するコールバック関数を定義します。

   ```
   function streamApplicationMessageCallback(message) {
       console.log('Received ' + message.length + ' bytes of message from 
       Application');
   }
   ```

1.  `clientConnection.applicationMessage` をコールバック関数に設定します。

   ```
   clientConnection: {
       connectionState: streamConnectionStateCallback,
       channelError: streamChannelErrorCallback,
       serverDisconnect: streamServerDisconnectCallback,
       applicationMessage: streamApplicationMessageCallback,
   }
   ```

1.  `GameLiftStreams.sendApplicationMessage` 関数を呼び出して、アプリケーションにメッセージを送信します。これは、ストリームセッションがアクティブで入力がアタッチされている限り、いつでも呼び出すことができます。

例として、Amazon GameLift Streams Web SDK サンプルクライアントを参照してください。このクライアントは、クライアント側でシンプルなデータチャネルを設定する方法を示しています。

## アプリケーション側
<a name="data-channels-using-application"></a>

アプリケーションに次のロジックを記述します。

### ステップ 1. データチャネルポートに接続する
<a name="data-channels-using-application-1"></a>

アプリケーションが起動したら、 `40712`のポートに接続します`localhost`。アプリケーションは、実行期間中、この接続を維持する必要があります。アプリケーションが接続を閉じると、再度開くことはできません。

### ステップ 2. イベントをリッスンする
<a name="data-channels-using-application-2"></a>

イベントは固定サイズのヘッダーで始まり、その後に可変長の関連データが続きます。アプリケーションがイベントを受け取ったら、イベントを解析して情報を取得します。

**Event format**
+ **ヘッダー**: 形式の 4 バイトヘッダー `abcc`
  +  `a` : クライアント ID バイト。これは、複数の接続 (切断と再接続による) の場合に、特定のクライアント接続を識別します。
  +  `b` : イベントタイプのバイト。 - `0` 接続されたクライアント、 - `1` 接続されていないクライアント、 `2` - クライアントからメッセージが送信されます。その他のイベントタイプは、今後の Amazon GameLift Streams サービスの更新で受信される可能性があるため、無視する必要があります。
  +  `cc` : 関連付けられたイベントデータの長さ。これは、ビッグエンディアンの順序で 2 バイトとして表されます (最初のバイトが最も重要です）。イベントタイプが 2 の場合、イベントデータはクライアントからのメッセージの内容を表します。
+ **データ**: 残りのバイトには、クライアントメッセージなどのイベントデータが含まれます。データの長さは、 ヘッダー`cc`の で示されます。

**イベントをリッスンするには**

1. 4 つのヘッダーバイトを読み取って、クライアント ID、イベントタイプ、イベントデータの長さを取得します。

1. ヘッダーで説明されている長さに従って、クライアント ID とイベントタイプに関係なく、可変長イベントデータを読み取ります。イベントデータがバッファに残されないように、データを無条件に読み取ることが重要です。バッファには、次のイベントヘッダーと混同される可能性があります。イベントタイプに基づいてデータの長さを推測しないでください。

1. アプリケーションで認識された場合は、イベントタイプに基づいて適切なアクションを実行します。このアクションには、着信接続または切断のログ記録、クライアントメッセージの解析、アプリケーションロジックのトリガーなどがあります。

### ステップ 3. クライアントにメッセージを送信する
<a name="data-channels-using-application-3"></a>

アプリケーションは、受信イベントで使用されるのと同じ 4 バイトのヘッダー形式でメッセージを送信する必要があります。

**クライアントにメッセージを送信するには**

1. 次のプロパティを使用して ヘッダーを書き込みます。

   1. `a` : クライアント ID バイト。メッセージがクライアントメッセージに応答している場合は、古いクライアント接続から新しく再接続されたクライアントに応答を配信するなどの競合状態を避けるため、受信クライアントメッセージと同じクライアント ID を再利用する必要があります。アプリケーションが未承諾メッセージをクライアントに送信している場合は、最新の「クライアント接続」イベント (イベントタイプ 0) と一致するようにクライアント ID を設定する必要があります。

   1. `b` : 送信メッセージのイベントタイプは常に 2 である必要があります。クライアントは、他のイベントタイプのメッセージを無視します。

   1. `cc` : メッセージの長さ、バイト単位。

1. メッセージバイトを書き込みます。

クライアントが切断しない限り、メッセージは指定されたクライアントに配信されます。切断されたクライアントが再接続すると、クライアント接続イベントを介して新しいクライアント ID が割り当てられます。古いクライアント ID の未配信メッセージはすべて破棄されます。

**Example**  
次の擬似コードは、アプリケーション側でメッセージを伝えるロジックを示しています。Winsock を使用した完全な例については、Windows Sockets 2 ドキュメントの[「Winsock クライアントコードの完了](https://learn.microsoft.com/en-us/windows/win32/winsock/complete-client-code)」を参照してください。  

```
connection = connect_to_tcp_socket("localhost:40712")
loop:
    while has_pending_bytes(connection):
        client_id = read_unsigned_byte(connection)
        event_type = read_unsigned_byte(connection)
        event_length = 256 * read_unsigned_byte(connection)
        event_length = event_length + read_unsigned_byte(connection)
        event_data = read_raw_bytes(connection, event_length)
        if message_type == 0:
            app_process_client_connected(client_id)
        else if message_type == 1:
            app_process_client_disconnected(client_id)
        else if message_type == 2:
            app_process_client_message(client_id, event_data)
        else:
            log("ignoring unrecognized event type")
    while app_has_outgoing_messages():
        target_client_id, message_bytes = app_next_outgoing_message()
        message_length = length(message_bytes)
        write_unsigned_byte(connection, target_client_id)
        write_unsigned_byte(connection, 2)
        write_unsigned_byte(connection, message_length / 256)
        write_unsigned_byte(connection, message_length mod 256)
        write_raw_bytes(connection, message_bytes)
```