# Amazon IVS Chat の開始方法
Amazon Interactive Video Service (IVS) チャットは、ライブ動画ストリームに付随するマネージド型のライブチャット機能です。(IVS Chat はビデオストリームなしでも使用できます。) チャットルームを作成し、ユーザー間でチャットセッションを有効にできます。
Amazon IVS Chat では、ライブ動画に付随するカスタマイズされたチャット体験を構築することに注力できます。インフラストラクチャの管理や、チャットワークフローのコンポーネントの開発および設定は不要です。Amazon IVS Chat は、スケーラブルかつ安全で、信頼性が高く、コスト効率に優れています。
Amazon IVS Chat は、ライブ動画ストリームの参加者間の開始と終了時のメッセージングを容易にするために最適です。
このドキュメントの残りの部分では、Amazon IVS Chat を使用して最初のチャットアプリケーションを構築する手順を説明します。
**例:** 以下のデモアプリが利用可能です (3 つのサンプルクライアントアプリとトークン作成用のバックエンドサーバーアプリ)。
+ [Amazon IVS Chat ウェブ用デモ](https://github.com/aws-samples/amazon-ivs-chat-web-demo)
+ [Amazon IVS Chat Android 用デモ](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)
+ [Amazon IVS Chat iOS 用デモ](https://github.com/aws-samples/amazon-ivs-chat-for-ios-demo)
+ [Amazon IVS Chat デモバックエンド](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless)
**重要:** 24 か月間新しい接続や更新がないチャットルームは自動的に削除されます。
**Topics**
+ [ステップ 1: 初期設定を行う](getting-started-chat-create-account.md)
+ [ステップ 2: チャットルームを作成する](getting-started-chat-create-room.md)
+ [ステップ 3: チャットトークンを作成する](getting-started-chat-auth.md)
+ [ステップ 4: 最初のメッセージを送受信する](getting-started-chat-send-and-receive.md)
+ [ステップ 5: Service-Quota 制限の確認 (オプション)](getting-started-chat-check-service-quota.md)
# ステップ 1: 初期設定を行う
先に進む前に、次のことを行う必要があります。
1. AWS アカウント作成します。
1. ルートユーザーと管理ユーザーを設定します。
1. AWS IAM (Identity and Access Management) のアクセス許可を設定します。次のポリシーを使用してください。
前述の具体的なステップについては、「*Amazon IVS ユーザーガイド*」の「[Amazon IVS 低レイテンシーストリーミングの開始](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html)」を参照してください。**重要:**「ステップ 3: IAM アクセス許可の設定」では、次の IVS チャットポリシーを使用します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ivschat:CreateChatToken",
"ivschat:CreateLoggingConfiguration",
"ivschat:CreateRoom",
"ivschat:DeleteLoggingConfiguration",
"ivschat:DeleteMessage",
"ivschat:DeleteRoom",
"ivschat:DisconnectUser",
"ivschat:GetLoggingConfiguration",
"ivschat:GetRoom",
"ivschat:ListLoggingConfigurations",
"ivschat:ListRooms",
"ivschat:ListTagsForResource",
"ivschat:SendEvent",
"ivschat:TagResource",
"ivschat:UntagResource",
"ivschat:UpdateLoggingConfiguration",
"ivschat:UpdateRoom"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"servicequotas:ListServiceQuotas",
"servicequotas:ListServices",
"servicequotas:ListAWSDefaultServiceQuotas",
"servicequotas:ListRequestedServiceQuotaChangeHistoryByQuota",
"servicequotas:ListTagsForResource",
"cloudwatch:GetMetricData",
"cloudwatch:DescribeAlarms"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:GetLogDelivery",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:ListLogDeliveries",
"logs:PutResourcePolicy",
"logs:DescribeResourcePolicies",
"logs:DescribeLogGroups",
"s3:PutBucketPolicy",
"s3:GetBucketPolicy",
"iam:CreateServiceLinkedRole",
"firehose:TagDeliveryStream"
],
"Resource": "*"
}
]
}
```
------
# ステップ 2: チャットルームを作成する
Amazon IVS Chat ルームには、それに関連付けられた設定情報 (メッセージの最大長など) があります。
このセクションの手順では、コンソールまたは AWS CLI を使用してチャットルームをセットアップし (メッセージを確認したり、メッセージをログ記録したりするためのオプション設定を含む)、チャットルームを作成する方法を示します。
# IVS Chat ルームを作成するためのコンソールの手順
これらのステップは、初期ルームの設定から最終ルームの作成まで、いくつかのフェーズに分かれています。
オプションで、メッセージがレビューされるようにルームを設定できます。例えば、メッセージの内容やメタデータを更新したり、メッセージを拒否して送信されないようにしたり、元のメッセージを通過させたりすることができます。これについては、[ルームメッセージのレビュー設定 (オプション)](#create-room-console-review-messages) で説明しています。
オプションで、メッセージがログに記録されるようにルームを設定することもできます。例えば、チャットルームに送信するメッセージがある場合は、Amazon S3 バケット、Amazon CloudWatch、または Amazon Kinesis Data Firehose にそのメッセージをログとして記録できます。これについては、[メッセージのログ設定 (オプション)](#create-room-console-log-messages) で説明しています。
## 初期ルーム設定
1. [Amazon IVS Chat コンソール](https://console.aws.amazon.com/ivs/chat)を開きます。
([AWS マネジメントコンソール](https://console.aws.amazon.com/)から Amazon IVS コンソールにアクセスすることもできます。)
1. ナビゲーションバーから、[**Select a Region (リージョンの選択)**] ドロップダウンをクリックして、リージョンを選択します。新しいルームがこのリージョンに作成されます。
1. **[Get started]** (使用開始) ボックス (右上) で、**[Amazon IVS Chat Room]** (Amazon IVS Chat ルーム) を選択します。**[Create room]** (ルームの作成) ウィンドウが表示されます。
![\[チャットルームを作成する。\]](http://docs.aws.amazon.com/ja_jp/ivs/latest/ChatUserGuide/images/Chat_Create_Room.png)
1. **[Setup]** (セットアップ) を選択し、オプションで **[Room name]** (ルーム名) を指定します。ルーム名は一意ではありませんが、ルーム ARN (Amazon リソースネーム) 以外のルームを区別するのに役立ちます。
1. **[Setup > Room configuration]** (設定 > ルーム設定) で、**[Default configuration]** (デフォルト設定) を受け入れるか、**[Custom configuration]** (カスタム設定) を選択して、**[Maximum message length]** (最大メッセージ長) および/または **[Maximum message rate]** (最大メッセージレート) を設定することができます。
1. メッセージをレビューする場合は、以下の「[ルームメッセージのレビュー設定 (オプション)](#create-room-console-review-messages)」に進みます。それ以外の場合は、その手順をスキップして (つまり、**[Message Review Handler > Disabled]** (メッセージレビューハンドラ > 無効) を受け入れ)、直接 [[Final Room Creation]](#create-room-console-final) (最終ルームの作成) に進みます。
## ルームメッセージのレビュー設定 (オプション)
1. **[Message Review Handler]** (メッセージレビューハンドラ) で、**[Handle with AWS Lambda]** (AWS Lambda で処理する) を選択します。**[Message Review Handler]** (メッセージレビューハンドラ) セクションが展開され、追加のオプションが表示されます。
1. ハンドラが有効な応答を返さない場合、エラーが発生した場合、またはタイムアウト期間を超えた場合に、メッセージを**許可**または**拒否する**ように**フォールバック結果**を設定します。
1. 既存の **[Lambda function]** (Lambda 関数) を指定するか、**[Create Lambda function]** (Lambda 関数の作成) を使用して新しい関数を作成します。
Lambda 関数は、チャットルームと同じ AWS アカウントおよび同じ AWS リージョンに存在する必要があります。Amazon Chat SDK サービスに Lambda リソースを呼び出すアクセス許可を与える必要があります。リソースベースのポリシーは、選択した Lambda 関数に対して自動的に作成されます。アクセス許可の詳細については、「[Resource-Based Policy for Amazon IVS Chat](security-iam.md#security-chat-policy-examples)」を参照してください。
## メッセージのログ設定 (オプション)
1. **[Message logging]** (メッセージログ) で、**[Automatically log chat messages]** (チャットメッセージを自動的に記録する) を選択します。**[Message logging]** (メッセージログ) セクションが展開され、追加のオプションが表示されます。既存のログ記録設定をこのルームに追加するか、**[Create logging configuration]** (ログ記録設定の作成) を選択して、新しいログ記録設定を作成できます。
1. 既存のログ記録設定を選択すると、ドロップダウンメニューが開き、作成済みのログ記録設定がすべて表示されます。リストから 1 つ選択すると、自動的にチャットメッセージがこの送信先に記録されます。
1. **[Create logging configuration]** (ログ記録設定の作成) を選択すると、新しくモーダルウィンドウが表示され、ログ記録設定の作成とカスタマイズができます。
1. オプションで **[Logging configuration name]** (ログ記録設定名) を指定します。ログ記録設定名は、ルーム名のように一意ではありませんが、ログ記録設定 ARN 以外のログ記録設定を区別するのに役立ちます。
1. **[Destination (送信先)]** で、**[CloudWatch log group (CloudWatch ロググループ)]**、**[Kinesis firehose delivery stream (Kinesis Firehose 配信ストリーム)]**、または **[Amazon S3 バケット]** を選択して、ログの送信先を選択します。
1. 送信先に応じて、既存の**CloudWatch ロググループ**、**Kinesis Firehose 配信ストリーム**、または **Amazon S3 バケット**を使用するか、これらを新規に作成するかを選択します。
1. レビュー後、**[Create]** (作成) をクリックして、一意の ARN で新しいログ記録設定を作成します。これにより新しいログ記録設定が、自動的にチャットルームにアタッチされます。
## 最終ルームの作成
1. レビュー後、**[Create chat room]** (チャットルームの作成) をクリックして、一意の ARN で新しいチャットルームを作成します。
# IVS Chat ルームを作成するための CLI の手順
このドキュメントでは、AWS CLI を使用して Amazon IVS Chat ルームを作成するためのステップについて説明します。
## チャットルームを作成する
AWS CLI を使用してチャットルームを作成することは詳細オプションであり、最初に CLI をダウンロードしてマシンに設定する必要があります。詳細については、「[AWS Command Line Interface のユーザーガイド](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」を参照してください。
1. チャット `create-room` コマンドを実行し、オプション名を渡します。
```
aws ivschat create-room --name test-room
```
1. これにより、新しいチャットルームが返されます。
```
{
"arn": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6",
"id": "string",
"createTime": "2021-06-07T14:26:05-07:00",
"maximumMessageLength": 200,
"maximumMessageRatePerSecond": 10,
"name": "test-room",
"tags": {},
"updateTime": "2021-06-07T14:26:05-07:00"
}
```
1. `arn` フィールドに注意してください。クライアントトークンを作成してチャットルームに接続するには、これが必要です。
## ログ記録設定のセットアップ (オプション)
AWS CLI を使用してチャットルームを作成し、ログ記録設定をセットアップすることは詳細オプションであり、最初に CLI をダウンロードしてマシンに設定する必要があります。詳細については、「[AWS Command Line Interface のユーザーガイド](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」を参照してください。
1. チャットの `create-logging-configuration` コマンドを実行し、オプションとしてログ設定の名前と、Amazon S3 バケットを指定する送信先設定の名前を渡します。この Amazon S3 バケットは、ログ記録設定の作成前に存在している必要があります。(Amazon S3 バケットの作成について詳しくは、[Amazon S3 ドキュメント](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)を参照してください。)
```
aws ivschat create-logging-configuration \
--destination-configuration s3={bucketName=demo-logging-bucket} \
--name "test-logging-config"
```
1. これで新しいログ記録設定が返ってきます。
```
{
"Arn": "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ",
"createTime": "2022-09-14T17:48:00.653000+00:00",
"destinationConfiguration": {
"s3": {"bucketName": "demo-logging-bucket"}
},
"id": "ABcdef34ghIJ",
"name": "test-logging-config",
"state": "ACTIVE",
"tags": {},
"updateTime": "2022-09-14T17:48:01.104000+00:00"
}
```
1. `arn` フィールドに注意してください。チャットルームにログ記録設定をアタッチするには、このフィールドが必要です。
1. 新しくチャットルームを作成する場合は、`create-room` コマンドを実行して、ログ記録設定 `arn` を渡します。
```
aws ivschat create-room --name test-room \
--logging-configuration-identifiers \
"arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ"
```
1. 既存のチャットルームを更新する場合は、`update-room` コマンドを実行して、ログ記録設定 `arn` を渡します。
```
aws ivschat update-room --identifier \
"arn:aws:ivschat:us-west-2:12345689012:room/g1H2I3j4k5L6" \
--logging-configuration-identifiers \
"arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ"
```
# ステップ 3: チャットトークンを作成する
チャット参加者がルームに接続してメッセージの送受信を開始するには、チャットトークンを作成する必要があります。チャットトークンは、チャットクライアントの認証と認可に使用されます。
この図は、IVS Chat トークンを作成するためのワークフローを示しています。
![\[新しく作成したチャットルームのクライアントを認証し、認可します。\]](http://docs.aws.amazon.com/ja_jp/ivs/latest/ChatUserGuide/images/Chat_Getting_Started_Auth.png)
上記のように、クライアントアプリケーションはサーバー側のアプリケーションにトークンを要求し、サーバー側のアプリケーションは AWS SDK または [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) 署名付きリクエストを使用して CreateChatToken を呼び出します。AWS 認証情報が API の呼び出しに使用されるため、トークンはクライアント側のアプリケーションではなく、安全なサーバー側のアプリケーションで生成する必要があります。
トークン生成のデモンストレーションを行うバックエンドサーバーアプリケーションは、[Amazon IVS Chat デモバックエンド](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless)で入手可能です。
*セッション期間*とは、確立されたセッションが自動的に終了されるまでのアクティブな状態を維持できる期間を指します。つまり、セッション期間は、新しいトークンを生成して新しい接続を確立する必要が生じる前に、クライアントがチャットルームに接続したままにできる期間です。オプションでは、トークンの作成中に、セッション期間を指定できます。
エンドユーザーの接続を確立するために、各トークンは一度だけ使用できます。接続が終了した場合、接続を再確立する前に、新しいトークンを作成する必要があります。トークン自体は、応答に含まれるトークンの有効期限のタイムスタンプまで有効です。
エンドユーザーがチャットルームに接続する場合、クライアントはサーバーアプリケーションにトークンを要求する必要があります。サーバーアプリケーションはトークンを作成し、それをクライアントに返します。トークンはオンデマンドでエンドユーザー向けに作成する必要があります。
チャット認証トークンを作成するには、以下の手順に従います。チャットトークンを作成する際は、リクエストフィールドを使用してチャットエンドユーザーとエンドユーザーのメッセージング機能に関するデータを渡します。詳細については、「*IVS Chat API Reference*」の「[CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html)」を参照してください。
## AWS SDK での手順
AWS SDK を使用してチャットトークンを作成するには、最初にアプリケーションに SDK をダウンロードして設定する必要があります。以下は、JavaScript による AWS SDK の手順です。
**重要:** このコードは、サーバー側で実行し、その出力をクライアントに渡す必要があります。
**前提条件**: 以下のコードサンプルを使用するには、AWS JavaScript SDK をアプリケーションにロードする必要があります。詳細については、[Getting started with the AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html) を参照してください。
```
async function createChatToken(params) {
const ivs = new AWS.Ivschat();
const result = await ivs.createChatToken(params).promise();
console.log("New token created", result.token);
}
/*
Create a token with provided inputs. Values for user ID and display name are
from your application and refer to the user connected to this chat session.
*/
const params = {
"attributes": {
"displayName": "DemoUser",
}",
"capabilities": ["SEND_MESSAGE"],
"roomIdentifier": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6",
"userId": 11231234
};
createChatToken(params);
```
## CLI の手順
AWS CLI を使用してチャットトークンを作成することは詳細オプションであり、最初に CLI をダウンロードしてマシンに設定する必要があります。詳細については、「[AWS Command Line Interface のユーザーガイド](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)」を参照してください。注: AWS CLI を使用したトークンの生成はテスト目的の場合は問題ありませんが、本番環境で使用する場合は、AWS SDK を使用してサーバー側でトークンを生成することをお勧めします (上記の手順を参照)。
1. クライアントのルーム識別子およびユーザ ID とともに `create-chat-token` のコマンドを実行します。以下のいずれかの機能を含めます: `"SEND_MESSAGE"`、`"DELETE_MESSAGE"`、`"DISCONNECT_USER"`。(オプションで、このチャットセッションに関するセッション期間 (分単位) やカスタム属性 (メタデータ) を含めます。これらのフィールドは以下には表示されません。)
```
aws ivschat create-chat-token --room-identifier "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6" --user-id "11231234" --capabilities "SEND_MESSAGE"
```
1. これはクライアントトークンを返します。
```
{
"token": "abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234.abcd12345EFGHI67890_jklmno123PQRS567890uvwxyz1234abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234abcde",
"sessionExpirationTime": "2022-03-16T04:44:09+00:00",
"tokenExpirationTime": "2022-03-16T03:45:09+00:00"
}
```
1. このトークンを保存します。チャットルームに接続し、メッセージを送受信するには、これが必要です。セッションが終了する前に、別のチャットトークンを生成する必要があります (`sessionExpirationTime` で示されています)。
# ステップ 4: 最初のメッセージを送受信する
チャットトークンを使用してチャットルームに接続し、最初のメッセージを送信します。サンプルの JavaScript コードを以下に示します。IVS クライアント SDK も利用可能です。「[チャット SDK: Android ガイド](chat-sdk-android.md)」、「[ チャット SDK: iOS ガイド](chat-sdk-ios.md)」、「[チャット SDK: JavaScript ガイド](chat-sdk-js.md)」をご覧ください。
**リージョンサービス:** 以下のサンプルコードは、お客様の「サポート対象リージョン」を示しています。Amazon IVS Chat では、リクエストの実行に使用できるリージョンのエンドポイントを提供しています。Amazon IVS Chat メッセージング API の場合、リージョンエンドポイントの一般的な構文は次のとおりです。
+ wss://edge.ivschat..amazonaws.com
例えば、米国西部 (オレゴン) リージョンのエンドポイントは wss://edge.ivschat.us-west-2.amazonaws.com です。サポートされているリージョンのリストについては、「*AWS 全般のリファレンス*」の [Amazon IVS ページ](https://docs.aws.amazon.com/general/latest/gr/ivs.html)にある Amazon IVS Chat 情報を参照してください。
```
/*
1. To connect to a chat room, you need to create a Secure-WebSocket connection
using the client token you created in the previous steps. Use one of the provided
endpoints in the Chat Messaging API, depending on your AWS region.
*/
const chatClientToken = "GENERATED_CHAT_CLIENT_TOKEN_HERE";
const socket = "wss://edge.ivschat.us-west-2.amazonaws.com"; // Replace “us-west-2” with supported region of choice.
const connection = new WebSocket(socket, chatClientToken);
/*
2. You can send your first message by listening to user input
in the UI and sending messages to the WebSocket connection.
*/
const payload = {
"Action": "SEND_MESSAGE",
"RequestId": "OPTIONAL_ID_YOU_CAN_SPECIFY_TO_TRACK_THE_REQUEST",
"Content": "text message",
"Attributes": {
"CustomMetadata": "test metadata"
}
}
connection.send(JSON.stringify(payload));
/*
3. To listen to incoming chat messages from this WebSocket connection
and display them in your UI, you must add some event listeners.
*/
connection.onmessage = (event) => {
const data = JSON.parse(event.data);
displayMessages({
display_name: data.Sender.Attributes.DisplayName,
message: data.Content,
timestamp: data.SendTime
});
}
function displayMessages(message) {
// Modify this function to display messages in your chat UI however you like.
console.log(message);
}
/*
4. Delete a chat message by sending the DELETE_MESSAGE action to the WebSocket
connection. The connected user must have the "DELETE_MESSAGE" permission to
perform this action.
*/
function deleteMessage(messageId) {
const deletePayload = {
"Action": "DELETE_MESSAGE",
"Reason": "Deleted by moderator",
"Id": "${messageId}"
}
connection.send(deletePayload);
}
```
おめでとうございます、これで準備万端です！これで、メッセージを送受信できるシンプルなチャットアプリケーションができました。
# ステップ 5: Service-Quota 制限の確認 (オプション)
チャットルームは Amazon IVS ライブストリームに合わせて拡張され、すべての視聴者がチャットの会話に参加できるようになります。ただし、すべての Amazon IVS アカウントには、同時チャット参加者数およびメッセージ配信速度に制限があります。
*制限が適切であることを確認し、必要に応じて引き上げをリクエストします (特に大規模なストリーミングイベントを計画している場合)*。詳細については、「[Service Quotas (Low-Latency Streaming)](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/service-quotas.html)」、「[Service Quotas (Real-Time Streaming)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/service-quotas.html)」、および「[Service Quotas (Chat)](service-quotas.md)」を参照してください。