次の方法で共有

クイック スタート:チャットをアプリに追加する

  • [アーティクル]

Communication Services Chat SDK を使用してリアルタイム チャットをアプリケーションに追加することによって、Azure Communication Services の使用を開始します。 このクイックスタートでは、Chat SDK を使用して、ユーザーが相互に会話できるようにするチャット スレッドを作成します。 チャットの概念の詳細については、 チャットの概念に関するドキュメントを参照してください。

前提条件

  • アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。

  • アクティブな Communication Services リソースと接続文字列。 Communication Services のリソースを作成する。

  • Azure CLI をインストールします。

  • Communication Services のリソース エンドポイントをメモします。 このエンドポイントは、Azure portal から取得できます。 また、接続文字列でエンドポイント URL を見つけることもできます。 この URL は、endpoint= の後にある、https:// で始まる URL です。

  • ユーザー アクセス トークン。 スコープを必ず chat に設定し、トークン文字列と ser_id 文字列をメモしてください。 Azure CLI を使用して、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

設定

拡張機能の追加

az extension コマンドを使用して、Azure CLI の Azure Communication Services 拡張機能を追加します。

az extension add --name communication

Azure CLI へのサインイン

Azure CLI にサインインする必要があります。 ターミナルから az login コマンドを実行し、資格情報を入力してサインインできます。

(省略可能) エンドポイントまたはアクセス トークンを渡さずに Azure CLI の ID 操作を使用する

環境変数にエンドポイントを格納する

エンドポイントを渡す --endpoint を使用せずに、Azure CLI チャット操作を使用するために AZURE_COMMUNICATION_ENDPOINT 環境変数を構成できます。 環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourEndpoint> は、実際のエンドポイントに置き換えます。

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

環境変数にアクセス トークンを格納する

アクセス トークンを渡す --access-token を使用せずに、Azure CLI チャット操作を使用するために AZURE_COMMUNICATION_ACCESS_TOKEN 環境変数を構成できます。 環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <yourAccessToken> は、実際のアクセス トークンに置き換えてください。

コンソール ウィンドウを開き、次のコマンドを入力します。

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

操作

チャット スレッドを開始する

チャット スレッドを作成するには、thread create コマンドを使用します。

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

前述したようにエンドポイントとアクセス トークンを環境変数に格納した場合、それらをコマンドに渡す必要はありません。

az communication chat thread create --topic "<chatTopic>"
  • スレッドにトピックを提供するには、<chatTopic> を使用します。 チャット スレッドが作成された後、thread update-topic コマンドを使用してトピックを更新できます。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドのトピックを更新する

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • <chatTopic> は、設定する新しいチャット トピックに置き換えます。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

すべてのチャット スレッドを一覧表示する

thread list コマンドは、ユーザーのチャット スレッドの一覧を返します。

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • チャット メッセージを取得する最も早い時点を指定するには、オプションの <startTime> を使用します。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドにメッセージを送信する

作成したチャット スレッド (threadId で指定) にメッセージを送信するには、message send コマンドを使用します。

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • チャット メッセージの内容は、<content> を使用して設定します。
  • メッセージのコンテンツの種類を指定するには、<messageType> を使用します。 設定可能な値は text および html です。 値を指定しない場合、既定値は text になります。
  • 送信者の表示名を指定するには、オプションの <displayName> を使用します。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッド内のチャット メッセージを一覧表示する

message list コマンドは、チャット スレッド内のチャット メッセージの一覧を返します。

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • チャット メッセージを取得する最も早い時点を指定するには、オプションの <startTime> を使用します。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドからチャット メッセージを受信する

message list コマンドを使用して、チャット メッセージを取得できます。

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • <messageId> は、取得するメッセージの ID に置き換えます。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

開封確認メッセージを送信する

ユーザーに代わって開封確認イベントをスレッドに送信するには、message receipt send コマンドを使用します。

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • <messageId> は、現在のユーザーが読み取った最新のメッセージの ID に置き換えます。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドに参加者としてユーザーを追加する

チャット スレッドを作成した後、そこにユーザーを追加したり削除したりすることができます。 追加したユーザーには、チャット スレッドにメッセージを送信したり、他の参加者を追加または削除したりできるアクセス権が与えられます。 participant add コマンドを呼び出す前に、そのユーザーの新しいアクセス トークンと ID を取得していることを確認してください。

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • <userId> を対象のユーザー ID に置き換えてください。
  • 送信者の表示名を指定するには、オプションの <displayName> を使用します。
  • チャット メッセージを取得する最も早い時点を指定するには、オプションの <startTime> を使用します。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドのスレッド参加者の一覧を取得する

参加者の追加と同様、スレッドから参加者の一覧を取得することもできます。

スレッドの参加者を取得するには、participant list コマンドを使用します。

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • 応答内の指定した位置まで参加者をスキップするには、オプションの <skip> を使用します。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

チャット スレッドから参加者を削除する

'participant remove' コマンドを使用して、チャット スレッドからチャット参加者を削除できます。

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • <chatThreadId> は、実際のチャット スレッド ID に置き換えます。
  • <userId> は、チャット スレッドから削除する userId に置き換えます。
  • <endpoint> を Azure Communication Services エンドポイントに置き換えます。
  • <token> は、前に identity token issue コマンドを実行して取得したアクセス トークンに置き換えます。

前提条件

開始する前に、必ず次のことを行ってください。

  • アクティブなサブスクリプションがある Azure アカウントを作成します。 詳細については、アカウントの無料作成に関するページを参照してください。

  • Node.js のアクティブ LTS バージョンおよびメンテナンス LTS バージョンをインストールします。

  • Azure Communication Services リソースを作成します。 詳細については、Azure Communication Services リソースの作成に関するページを参照してください。 このクイック スタートでは、リソース エンドポイントと接続文字列を記録する必要があります。

  • 3 人の Azure Communication Services ユーザー作成し、ユーザー アクセス トークンを発行します。 スコープを必ず chat に設定し、トークン文字列と ser_id 文字列をメモしてください。 完全なデモでは、最初の 2 名の参加者でスレッドを作成し、3 人目の参加者をスレッドに追加します。 Azure CLI を使用して、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

設定

新しい Web アプリケーションを作成する

まず、ターミナルまたはコマンド ウィンドウを開き、自分のアプリ用に新しいディレクトリを作成して、そこに移動します。

mkdir chat-quickstart && cd chat-quickstart

既定の設定で npm init -y を実行して、package.json ファイルを作成します。

npm init -y

パッケージのインストール

npm install コマンドを使用して、次に示した JavaScript 用の Communication Services SDK をインストールします。

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

--save オプションを使用すると、package.json ファイル内の依存関係としてライブラリが表示されます。

アプリのフレームワークを設定する

このクイックスタートでは、パーセルを使用してアプリケーション資産をバンドルします。 次のコマンドを実行してインストールし、package.json の開発依存関係として一覧表示します。

npm install parcel --save-dev

自分のプロジェクトのルート ディレクトリに、index.html ファイルを作成します。 このファイルをテンプレートとして使い、JavaScript 用 Azure Communication Chat SDK を使用してチャット機能を追加します。

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./client.js" type="module"></script>
  </body>
</html>

このクイックスタートのアプリケーション ロジックを格納するために、client.js という名前のファイルを自分のプロジェクトのルート ディレクトリに作成します。

チャット クライアントを作成する

Web アプリにチャット クライアントを作成するには、Communications Service エンドポイントと、前提条件の手順で生成されたアクセス トークンを使用します。

ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 このクイック スタートでは、チャット アプリケーションのトークンを管理するサービスレベルの作成については説明しません。 チャット アーキテクチャの詳細については、チャットの概念、アクセス トークンの詳細については、ユーザー アクセス トークンに関するページを参照してください。

client.js 内では、下のコードのエンドポイントとアクセス トークンを使用し、JavaScript 用 Azure Communication Chat SDK を使用してチャット機能を追加します。


import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');
  • endpointUrl は、Communication Services リソースのエンドポイントに置き換えます。まだご覧になっていない場合は、Azure Communication Services リソースの作成に関するページを参照してください。
  • userAccessToken は、発行したトークンに置き換えます。

コードの実行

次のコマンドを実行して、アプリケーションを実行します。

npx parcel index.html

ブラウザーを開き、http://localhost:1234/. に移動します ブラウザー内の開発者ツール コンソールには、次のように表示されます。

Azure Communication Chat client created!

オブジェクト モデル

JavaScript 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前 説明
ChatClient このクラスは、チャット機能に必要となります。 自分のサブスクリプション情報を使用してインスタンスを生成し、それを使用してスレッドを作成、取得、削除し、チャット イベントにサブスクライブします。
ChatThreadClient このクラスはチャット スレッド機能に必要です。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信/受信/更新/削除、ユーザーの追加/削除/取得、入力通知の送信、開封確認を行います。

チャット スレッドを開始する

チャット スレッドは、createThread メソッドを使用して作成します。

スレッド要求は、createThreadRequest を使用して記述します。

  • このチャットにトピックを指定するには、topic を使用します。 チャット スレッドの作成後に、UpdateThread 関数を使用してトピックを更新することができます。
  • チャット スレッドに追加する参加者をリストアップするには、participants を使用します。

解決されると、createChatThread メソッドから CreateChatThreadResult が返されます。 このモデルには chatThread プロパティが含まれており、そこから、新しく作成されたスレッドの id にアクセスすることができます。 その後、id を使用して ChatThreadClient のインスタンスを取得できます。 さらに、ChatThreadClient を使用すると、メッセージの送信や参加者の一覧表示など、スレッド内で操作を実行できます。

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

ブラウザー タブを最新の情報に更新すると、コンソールに以下が表示されます。

Thread created: <thread_id>

チャット スレッド クライアントを取得する

`createClient` メソッドは、既に存在するスレッドの `ChatThreadClient` を返します。 これは、作成したスレッドに対し、参加者の追加、メッセージの送信などの操作を実行する場合に使用できます。threadId は、既存のチャット スレッドの一意の ID です。

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

client.js の <CREATE CHAT THREAD CLIENT> コメントをこのコードで置き換え、ブラウザー タブを最新の情報に更新してコンソールを確認すると、以下が表示されます。

Chat Thread client for threadId: <threadId>

すべてのチャット スレッドを一覧表示する

listChatThreads メソッドは、ChatThreadItem 型の PagedAsyncIterableIterator を返します。 これを使用すると、すべてのチャット スレッドを一覧表示できます。 [ChatThreadItem] の反復子は、スレッドの一覧表示から返される応答です

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

チャット スレッドにメッセージを送信する

threadId で識別されるスレッドにメッセージを送信するには、sendMessage メソッドを使用します。

メッセージ要求は、sendMessageRequest を使用して記述します。

  • チャット メッセージの内容は、content を使用して設定します。

操作の省略可能なパラメーターを記述するには、sendMessageOptions を使用します。

  • 送信者の表示名を指定するには、senderDisplayName を使用します。
  • 'text' や 'html' などのメッセージの種類を指定するには、type を使用します
  • 必要に応じて、metadata を使用して、メッセージと共に送信するその他のデータを含めます。 このフィールドは、開発者がチャット メッセージ機能を拡張し、ユース ケースに応じたカスタム情報を追加するためのメカニズムを提供します。 たとえば、メッセージ内でファイル リンクを共有する場合、'hasAttachment:true' をメタデータに追加することで、受信者のアプリケーションがそれを解析して適切に表示できます。

SendChatMessageResult は、メッセージの送信から返された応答です。ここには ID (メッセージの一意の ID) が含まれています。

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

client.js の <SEND MESSAGE TO A CHAT THREAD> コメントをこのコードで置き換え、ブラウザー タブを最新の情報に更新してコンソールを確認します。

Message sent!, message id:<number>

チャット スレッドからチャット メッセージを受信する

リアルタイム シグナリングを使用すると、新しい受信メッセージをサブスクライブしてリッスンし、それに応じてメモリ内の現在のメッセージを更新することができます。 Azure Communication Services は、サブスクライブ可能な一連のイベントをサポートしています。

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

client.js の <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> コメントをこのコードで置き換えます。 ブラウザー タブを最新の情報に更新すると、コンソールに "Notification chatMessageReceived" というメッセージが表示されます。

チャット メッセージは、特定の間隔で listMessages メソッドをポーリングすることによって取得することもできます。


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

client.js の <LIST MESSAGES IN A CHAT THREAD> コメントをこのコードで置き換えます。 タブを最新の情報に更新すると、このチャット スレッドで送信されたメッセージの一覧がコンソールに表示されます。

listMessages は、chatMessage.type で識別できるさまざまな種類のメッセージを返します。

詳細については、「メッセージの種類」を参照してください。

チャット スレッドに参加者としてユーザーを追加する

チャット スレッドの作成後、ユーザーを追加したり削除したりすることができます。 追加したユーザーには、チャット スレッドにメッセージを送信したり、他の参加者を追加、削除したりできるアクセス権が与えられます。

addParticipants メソッドを呼び出す前に、そのユーザーの新しいアクセス トークンと ID を取得していることを確認してください。 チャット クライアントを初期化するためには、ユーザーにアクセス トークンが必要となります。

addParticipantsRequest は要求オブジェクトを表します。その中では、チャット スレッドに追加する参加者が participants を使用してリストアップされます。

  • id (必須) は、チャット スレッドに追加するコミュニケーション識別子です。
  • displayName (省略可) は、スレッド参加者の表示名です。
  • shareHistoryTime (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。 チャット スレッドの始めから履歴を共有する場合は、スレッドの作成日時と同じかそれ以前の任意の日付にこのプロパティを設定してください。 参加者が追加された時点よりも前の履歴は共有しない場合は、現在の日付に設定します。 履歴を部分的に共有するには、目的の日付に設定します。

const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

NEW_PARTICIPANT_USER_ID は、新しいユーザー ID に置き換えます。このコードは、client.js の <ADD NEW PARTICIPANT TO THREAD> コメントの代わりに追加してください。

チャット スレッド内のユーザーをリストアップする

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

client.js の <LIST PARTICIPANTS IN A THREAD> コメントをこのコードで置き換え、ブラウザー タブを最新の情報に更新してコンソールを確認すると、スレッド内のユーザーについての情報が表示されます。

チャット スレッドからユーザーを削除する

参加者の追加と同様、チャット スレッドから参加者を削除することもできます。 削除するには、追加した参加者の ID を追跡する必要があります。

removeParticipant メソッドを使用します。participant は、スレッドから削除するコミュニケーション ユーザーです。


await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

PARTICIPANT_ID は、前の手順で使用したユーザー ID (<NEW_PARTICIPANT_USER_ID>) に置き換えてください。 client.js の <REMOVE PARTICIPANT FROM THREAD> コメントをこのコードで置き換えます。

リアル タイム通知の接続状態をサブスクライブする

イベント realTimeNotificationConnected のサブスクリプション、および realTimeNotificationDisconnected を使用すると、呼び出しサーバーへの接続がアクティブになっている状態がわかります。

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

開始する前に、必ず次のことを行ってください。

設定

新しい Python アプリケーションを作成する

ターミナルまたはコマンド ウィンドウを開き、自分のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir chat-quickstart && cd chat-quickstart

テキスト エディターを使用して、プロジェクトのルート ディレクトリに start-chat.py というファイルを作成します。 基本的な例外処理を含め、プログラムの構造を追加します。 以降のセクションで、このクイックスタートのすべてのソース コードをこのファイルに追加していきます。

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

SDK をインストールする

次のコマンドを使用して SDK をインストールします。


pip install azure-communication-chat

オブジェクト モデル

Python 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前 説明
ChatClient このクラスはチャットの機能に必要です。 サブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除します。
ChatThreadClient このクラスはチャット スレッド機能に必要です。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信、受信、更新、および削除を行います。 また、これを使用して、ユーザーの追加、削除、取得、および入力通知と開封確認メッセージの送信を行うこともできます。

チャット クライアントを作成する

チャット クライアントを作成するには、Communication Services エンドポイントと、前提条件の手順の一部として生成したアクセス トークンを使用します。

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

このクイックスタートでは、チャット アプリケーションのトークンを管理するためのサービス レベルの作成については説明しませんが、そうすることをお勧めします。 詳細については、「チャットに関する概念」の「チャットのアーキテクチャ」セクションを参照してください。

チャット スレッドを開始する

チャット スレッドは、create_chat_thread メソッドを使用して作成します。

  • スレッドにトピックを提供するには、topic を使用します。 チャット スレッドが作成された後は、update_thread 関数を使用してトピックを更新できます。
  • チャット スレッドに追加する ChatParticipant をリストアップするには、thread_participants を使用します。 ChatParticipant は、CommunicationUserIdentifier 型を user として受け取ります。

CreateChatThreadResult は、スレッドの作成から返される結果です。 これを使用して、作成されたチャット スレッドの id をフェッチできます。 その後、この id は、get_chat_thread_client メソッドを使用して ChatThreadClient オブジェクトをフェッチするために使用できます。 ChatThreadClient は、このチャット スレッドに対して他のチャット操作を実行するために使用できます。

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

チャット スレッド クライアントを取得する

get_chat_thread_client メソッドは、既に存在するスレッドのスレッド クライアントを返します。 これを使用して、作成されたスレッドに対して操作を実行できます。 たとえば、参加者を追加したり、メッセージを送信したりできます。 thread_id は、既存のチャット スレッドの一意の ID です。

ChatThreadClient は、このチャット スレッドに対して他のチャット操作を実行するために使用できます。

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

すべてのチャット スレッドを一覧表示する

list_chat_threads メソッドは、ChatThreadItem 型の反復子を返します。

  • チャット スレッドを取得する最も早い時点を指定するには、start_time を使用します。
  • ページごとに返されるチャット スレッドの最大数を指定するには、results_per_page を使用します。

[ChatThreadItem] の反復子は、スレッドの一覧表示から返される応答です。

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

チャット スレッドにメッセージを送信する

作成したチャット スレッド (thread_id で識別されます) にメッセージを送信するには、send_message メソッドを使用します。

  • チャット メッセージの内容は、content を使用して設定します。
  • メッセージのコンテンツの種類を指定するには、chat_message_type を使用します。 設定可能な値は text および html です。 値を指定しない場合、既定値は text になります。
  • 送信者の表示名を指定するには、sender_display_name を使用します。
  • メッセージと共に送信する追加データを含めるには、必要に応じて metadata を使用します。 このフィールドは、開発者がチャット メッセージ機能を拡張し、ユース ケースに応じたカスタム情報を追加するためのメカニズムを提供します。 たとえば、メッセージ内でファイル リンクを共有する場合、'hasAttachment:true' をメタデータに追加することで、受信者のアプリケーションがそれを解析して適切に表示できます。

SendChatMessageResult は、メッセージの送信から返される応答です。 これには、ID (そのメッセージの一意の ID) が含まれています。

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

チャット スレッドからチャット メッセージを受信する

チャット メッセージは、特定の間隔で list_messages メソッドをポーリングすることによって取得できます。

  • ページごとに返されるメッセージの最大数を指定するには、results_per_page を使用します。
  • メッセージを取得する最も早い時点を指定するには、start_time を使用します。

[ChatMessage] の反復子は、メッセージの一覧表示から返される応答です。

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages は、メッセージに対して update_message や delete_message を使用して行われた編集や削除を含む、メッセージの最新バージョンを返します。 削除されたメッセージについては、そのメッセージがいつ削除されたかを示す datetime 値が ChatMessage.deleted_on から返されます。 編集されたメッセージについては、そのメッセージがいつ編集されたかを示す datetime 値が ChatMessage.edited_on から返されます。 メッセージの最初の作成日時には、ChatMessage.created_on を使用してアクセスできます。これをメッセージの並べ替えに使用することができます。

list_messages は、ChatMessage.type で識別できるさまざまな種類のメッセージを返します。

詳細については、「メッセージの種類」を参照してください。

開封確認メッセージを送信する

ユーザーに代わって開封確認イベントをスレッドに送信するには、send_read_receipt メソッドを使用します。

  • 現在のユーザーに読まれた最新のメッセージの ID を指定するには、message_id を使用します。
content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

チャット スレッドに参加者としてユーザーを追加する

チャット スレッドを作成した後、そこにユーザーを追加したり削除したりすることができます。 追加したユーザーには、チャット スレッドにメッセージを送信したり、他の参加者を追加または削除したりできるアクセス権が与えられます。 add_participants メソッドを呼び出す前に必ず、そのユーザーの新しいアクセス トークンと ID を取得しておいてください。 このアクセス トークンは、ユーザーがチャット クライアントを初期化するために必要になります。

add_participants メソッドを使用して、チャット スレッドに 1 人以上のユーザーを追加することができます (すべてのユーザーが新しいアクセス トークンと ID を使用できる場合)。

list(tuple(ChatParticipant, CommunicationError)) が返される。 参加者が正常に追加された場合は、空の一覧が予期されます。 参加者の追加中にエラーが発生した場合は、失敗した参加者と、発生したエラーが一覧に設定されます。

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

チャット スレッドのスレッド参加者の一覧を取得する

参加者の追加と同様、スレッドから参加者の一覧を取得することもできます。

スレッドの参加者を取得するには、list_participants を使用します。 次のコマンドはいずれも省略可能です。

  • ページごとに返される参加者の最大数を指定するには、results_per_page を使用します。
  • 応答内の指定した位置まで参加者をスキップするには、skip を使用します。

[ChatParticipant] の反復子は、参加者の一覧表示から返される応答です。

chat_thread_participants = chat_thread_client.list_participants()
for chat_thread_participant_page in chat_thread_participants.by_page():
    for chat_thread_participant in chat_thread_participant_page:
        print("ChatParticipant: ", chat_thread_participant)

コードの実行

アプリケーション ディレクトリから python コマンドを使用してアプリケーションを実行します。

python start-chat.py

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

設定

新しい Java アプリケーションを作成する

ターミナルまたはコマンド ウィンドウを開き、Java アプリケーションを作成するディレクトリに移動します。 次のコマンドを実行して、maven-archetype-quickstart テンプレートから Java プロジェクトを生成します。

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

"generate" ゴールにより、artifactId と同じ名前のディレクトリが作成されたことがわかります。 このディレクトリの下の src/main/java directory にはプロジェクトのソース コードが含まれており、src/test/java ディレクトリにはテスト ソースが含まれており、pom.xml ファイルはプロジェクトのプロジェクト オブジェクト モデル (POM) です。

Java 8 以降を使用するように、アプリケーションの POM ファイルを更新します。

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Chat SDK のパッケージ参照を追加する

POM ファイルで、チャット API を使用して azure-communication-chat パッケージを参照します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

認証の場合、クライアントは azure-communication-common パッケージを参照する必要があります。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

オブジェクト モデル

Java 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前 説明
ChatClient このクラスは、チャット機能に必要となります。 サブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除します。
ChatAsyncClient このクラスは、非同期チャット機能に必要となります。 サブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除します。
ChatThreadClient このクラスはチャット スレッド機能に必要です。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信/受信/更新/削除、ユーザーの追加/削除/取得、入力通知の送信、開封確認を行います。
ChatThreadAsyncClient このクラスは、非同期チャット スレッド機能に必要となります。 ChatAsyncClient を介してインスタンスを取得し、それを使用して、メッセージの送信/受信/更新/削除、ユーザーの追加/削除/取得、入力通知の送信、開封確認を行います。

チャット クライアントを作成する

チャット クライアントを作成するには、Communications Service エンドポイントと、前提条件の手順で生成されたアクセス トークンを使用します。 ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 サーバーでこれらのトークンを生成した後、それらをクライアント デバイスに渡します。 チャット クライアントにトークンを渡すには、Common SDK の CommunicationTokenCredential クラスを使用する必要があります。

詳細については、チャットのアーキテクチャに関するドキュメントを参照してください

import ステートメントを追加する場合は、com.azure.communication.chat.implementation 名前空間ではなく、com.azure.communication.chat および com.azure.communication.chat.models 名前空間からのインポートのみを追加してください。 Maven を使用して生成された App.java ファイルで、次のコードを使用して開始できます。

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

チャット スレッドを開始する

チャット スレッドは、createChatThread メソッドを使用して作成します。 スレッド要求は、createChatThreadOptions を使用して記述します。

  • このチャットにトピックを指定するには、コンストラクターの topic パラメーターを使用します。チャット スレッドの作成後に、UpdateThread 関数を使用してトピックを更新できます。
  • スレッドに追加するスレッド参加者をリストアップするには、participants を使用します。 ChatParticipant には、ユーザー アクセス トークンに関するクイックスタートで作成したユーザーが渡されます。

CreateChatThreadResult は、チャット スレッドの作成から返された応答です。 これには getChatThread() メソッドが含まれます。このメソッドは、スレッド クライアントを取得するために使用できる ChatThread オブジェクトを返します。そのスレッド クライアントから、作成されたスレッドに対して参加者の追加、メッセージの送信などの操作を実行するための ChatThreadClient を取得できます。ChatThread オブジェクトには、スレッドの一意の ID を取得する getId() メソッドも含まれます。

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

チャット スレッドを一覧表示する

listChatThreads メソッドを使用して、既存のチャット スレッドの一覧を取得します。

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

チャット スレッド クライアントを取得する

getChatThreadClient メソッドは、既に存在するスレッドのスレッド クライアントを返します。 作成したスレッドに対し、参加者の追加、メッセージの送信などの操作を実行するときに使用できます。chatThreadId は、既存のチャット スレッドの一意の ID です。

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

チャット スレッドにメッセージを送信する

作成したスレッド (chatThreadId で指定) にメッセージを送信するには、sendMessage メソッドを使用します。 チャット メッセージ要求は、sendChatMessageOptions を使用して記述します。

  • チャット メッセージの内容は、content を使用して設定します。
  • チャット メッセージのコンテンツの種類、テキスト、または HTML は、type を使用して指定します。
  • 送信者の表示名を指定するには、senderDisplayName を使用します。
  • メッセージと共に送信する追加データを含めるには、必要に応じて metadata を使用します。 このフィールドは、開発者がチャット メッセージ機能を拡張し、ユース ケースに応じたカスタム情報を追加するためのメカニズムを提供します。 たとえば、メッセージ内でファイル リンクを共有する場合、hasAttachment:true をメタデータに追加することで、受信者のアプリケーションがそれを解析して適切に表示できます。

応答である sendChatMessageResult には、id (そのメッセージの一意の ID) が含まれています。

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

チャット スレッドからチャット メッセージを受信する

チャット メッセージは、チャット スレッド クライアントで、特定の間隔で listMessages メソッドをポーリングすることによって取得できます。

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages は、メッセージに対して .editMessage() や .deleteMessage() を使用して行われた編集や削除を含む、最新バージョンのメッセージを返します。 削除されたメッセージについては、そのメッセージがいつ削除されたかを示す datetime 値が chatMessage.getDeletedOn() から返されます。 編集されたメッセージについては、メッセージがいつ編集されたかを示す datetime が chatMessage.getEditedOn() から返されます。 メッセージの最初の作成日時には、chatMessage.getCreatedOn() を使用してアクセスできます。これをメッセージの並べ替えに使用することができます。

メッセージの種類の詳細については、「メッセージの種類」をご覧ください。

開封確認メッセージを送信する

sendReadReceipt メソッドを使用すると、ユーザーに代わって開封確認イベントをチャット スレッドに送信できます。 chatMessageId は、開封されたチャット メッセージの一意の ID です。

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

チャット参加者を一覧表示する

chatThreadId によって識別されるチャット スレッドの参加者を含むページ コレクションを取得するには、listParticipants を使用します。

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

チャット スレッドに参加者としてユーザーを追加する

チャット スレッドの作成後、ユーザーを追加したり削除したりすることができます。 追加したユーザーには、チャット スレッドにメッセージを送信したり、他の参加者を追加、削除したりできるアクセス権が与えられます。 まず、そのユーザーの新しいアクセス トークンと ID を取得する必要があります。 addParticipants メソッドを呼び出す前に、そのユーザーの新しいアクセス トークンと ID を必ず取得してください。 チャット クライアントを初期化するためには、ユーザーにアクセス トークンが必要となります。

スレッドに参加者を追加するには、addParticipants メソッドを使用します。

  • communicationIdentifier (必須) は、ユーザー アクセス トークンに関するクイックスタートで CommunicationIdentityClient によって作成された CommunicationIdentifier です。
  • displayName (省略可) は、スレッド参加者の表示名です。
  • shareHistoryTime (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。 チャット スレッドの始めから履歴を共有する場合は、スレッドの作成日時と同じかそれ以前の任意の日付にこのプロパティを設定してください。 参加者が追加された時点よりも前の履歴は共有しない場合は、現在の日付に設定します。 部分的に履歴を共有するには、必要な日付に設定します。
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

コードの実行

pom.xml ファイルが格納されているディレクトリに移動し、次の mvn コマンドを使用してプロジェクトをコンパイルします。

mvn compile

次に、パッケージをビルドします。

mvn package

次の mvn コマンドを実行して、アプリを実行します。

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

開始する前に、必ず次のことを行ってください。

  • アクティブなサブスクリプションがある Azure アカウントを作成します。 詳細については、アカウントの無料作成に関するページを参照してください。

  • Android Studio をインストールします。Android Studio は、依存関係をインストールするためのクイックスタート用の Android アプリケーションを作成するために使用します。

  • Azure Communication Services リソースを作成します。 詳細については、Azure Communication Services リソースの作成に関するページを参照してください。 このクイック スタートでは、リソース エンドポイントと接続文字列を記録する必要があります。

  • 2 人 の Communication Services ユーザーを作成し、ユーザー アクセス トークン を発行します。 スコープを必ず chat に設定し、トークン文字列とuser_id文字列をメモしてください。 このクイックスタートでは、最初の参加者でスレッドを作成した後、そのスレッドに 2 人目の参加者を追加します。 Azure CLI を使用して、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

設定

新しい Android アプリケーションを作成する

  1. Android Studio を開き、Create a new project を選択します。
  2. 次のウィンドウで、プロジェクト テンプレートとして Empty Activity を選択します。
  3. オプションを選択する際に、プロジェクト名として「ChatQuickstart」と入力します。
  4. [次へ] をクリックし、プロジェクトの作成先ディレクトリを選択します。

ライブラリをインストールする

Gradle を使用して、必要な Communication Services の依存関係をインストールします。 コマンド ラインから、ChatQuickstart プロジェクトのルート ディレクトリ内に移動します。 アプリの build.gradle ファイルを開き、ChatQuickstart ターゲットに次の依存関係を追加します。

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

最新のバージョン番号について https://search.maven.org/artifact/com.azure.android/azure-communication-common と https://search.maven.org/artifact/com.azure.android/azure-communication-chat を参照してください。

ルートの build.gradle 内のパッケージ化オプションでメタ ファイルを除外する

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

(代替方法) Maven を使用してライブラリをインストールするには

Maven ビルド システムを使用してプロジェクトにライブラリをインポートするには、それをアプリの pom.xml ファイルの dependencies セクションに追加し、その成果物 ID と使用するバージョンを指定します。

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

Azure 関数を設定する

詳しくは、Azure 関数の統合に関する記事をご覧ください。 アプリケーション パラメーターのハードコーディングを回避するため、Azure 関数と統合することを強くお勧めします。

アプリケーションの定数を設定する

アプリケーションのすべての定数を格納する ApplicationConstants クラスを作成します。

public class ApplicationConstants {
    public static final String SDK_VERSION = "<your_version>";
    public final static String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    public final static String APPLICATION_ID = "Chat_Test_App";
    public final static String TAG = "[Chat Test App]";
    public static CommunicationTokenCredential COMMUNICATION_TOKEN_CREDENTIAL;
}

プレースホルダーを設定する

ファイル MainActivity.java を開いて編集します。 このクイック スタートでは、MainActivity にコードを追加し、コンソールにその出力を表示します。 UI の作成については、このクイックスタートでは取り上げません。 ファイルの先頭で、Azure Communication Common、Azure Communication Chat、その他のシステム ライブラリをインポートします。

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

ファイル MainActivity.java のクラス MainActivity に次のコードをコピーします。

    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Log.i(TAG, msg);
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // Initialize application parameters if one of the conditions in '### Initialize Application Parameters' are met.

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }

アプリケーションのパラメーターを初期化する

Note

次のいずれかの条件が当てはまる場合は、ApplicationConstants の初期化を MainActivity.java に追加する必要があります。1. プッシュ通知機能は有効になっていません。 2. Android 用 Azure Communication Chat ライブラリのバージョンは "2.0.0" 未満です。 それ以外の場合は、Android のプッシュ通知に関する記事のステップ 11 をご覧ください。 参考として、使っている SDK バージョンのサンプル APP をご覧ください。

ACS_ENDPOINT、FIRST_USER_ID、FIRST_USER_ACCESS_TOKEN は、Azure 関数の呼び出しから返されます。 詳しくは、Azure 関数の統合に関する記事をご覧ください。 Azure 関数の呼び出しからの応答を使って、パラメーターの一覧を初期化します。

  • ACS_ENDPOINT: Communication Services のリソース エンドポイント。
  • FIRST_USER_ID、SECOND_USER_ID: Communication Services リソースによって生成された有効な Communication Services ユーザー ID。
  • FIRST_USER_ACCESS_TOKEN: <FIRST_USER_ID> 用の Communication Services アクセス トークン。

Azure 関数を呼び出してアプリケーションのパラメーターを初期化するためのコード ブロック:

try {
        UserTokenClient userTokenClient = new UserTokenClient(AZURE_FUNCTION_URL);
        //First user context
        userTokenClient.getNewUserContext();
        ACS_ENDPOINT = userTokenClient.getACSEndpoint();
        FIRST_USER_ID = userTokenClient.getUserId();
        FIRST_USER_ACCESS_TOKEN = userTokenClient.getUserToken();
        COMMUNICATION_TOKEN_CREDENTIAL = new CommunicationTokenCredential(FIRST_USER_ACCESS_TOKEN);
        //Second user context
        userTokenClient.getNewUserContext();
        SECOND_USER_ID = userTokenClient.getUserId();
    } catch (Throwable throwable) {
        //Your handling code
        logger.logThrowableAsError(throwable);
    }

チャット クライアントを作成する

コメント <CREATE A CHAT CLIENT> を次のコードに置き換えます (import ステートメントはファイルの先頭に 配置します)。

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

オブジェクト モデル

JavaScript 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前 説明
ChatClient/ChatAsyncClient このクラスは、チャット機能に必要となります。 自分のサブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除し、チャット イベントにサブスクライブします。
ChatThreadClient/ChatThreadAsyncClient このクラスはチャット スレッド機能に必要です。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信/受信/更新/削除、ユーザーの追加/削除/取得、入力通知の送信、開封確認を行います。

チャット スレッドを開始する

ChatAsyncClient を使用して、最初のユーザーで新しいスレッドを作成します。

<CREATE A CHAT THREAD> コメントを、次のコードに置き換えます。

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

チャット スレッド クライアントを取得する

チャット スレッドを作成したので、そのスレッド内で操作を実行するために ChatThreadAsyncClient を取得します。 <CREATE A CHAT THREAD CLIENT> コメントを、次のコードに置き換えます。

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

チャット スレッドにメッセージを送信する

ここで、メッセージをそのスレッドに送信します。

<SEND A MESSAGE> コメントを、次のコードに置き換えます。

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

チャット スレッドからチャット メッセージを受信する

リアルタイム通知

リアルタイム シグナリングを使用すると、新しい受信メッセージをサブスクライブし、それに応じてメモリ内の現在のメッセージを更新することができます。 Azure Communication Services は、サブスクライブ可能な一連のイベントをサポートしています。

コメント <RECEIVE CHAT MESSAGES> を次のコードに置き換えます (import ステートメントはファイルの先頭に 配置します)。


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

重要

既知の問題: 同じアプリケーションで Android チャットと Calling SDK を一緒に使用している場合、Chat SDK のリアルタイム通知機能は機能しません。 依存関係の解決の問題が発生することがあります。 Microsoft がこの問題の解決に向けて取り組んでいる間、アプリの build.gradle ファイルに次の依存関係情報を追加し、代わりに GetMessages API をポーリングして受信メッセージをユーザーに表示することで、リアルタイム通知機能を無効にできます。

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

上記の更新では、アプリケーションが chatAsyncClient.startRealtimeNotifications() や chatAsyncClient.addEventHandler() のような通知 API にアクセスしようとすると、ランタイム エラーが発生することに注意してください。

プッシュ通知

詳細については、Android プッシュ通知を参照してください。

チャット スレッドに参加者としてユーザーを追加する

<ADD A USER> コメントを、次のコードに置き換えます。

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

スレッド内のユーザーを一覧表示する

コメント <LIST USERS> を次のコードに置き換えます (import ステートメントはファイルの先頭に配置します)。

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

チャット スレッドからユーザーを削除する

ここで、2 番目のユーザーをスレッドから削除します。

コメント <REMOVE A USER> を、次のコードに置き換えます。

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

入力通知を送信する

コメント <SEND A TYPING NOTIFICATION> を、次のコードに置き換えます。

chatThreadAsyncClient.sendTypingNotification().get();

開封確認メッセージを送信する

上記で送信されたメッセージの開封確認メッセージを送信します。

コメント <SEND A READ RECEIPT> を、次のコードに置き換えます。

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

開封確認メッセージを一覧表示する

コメント <READ RECEIPTS> を、次のコードに置き換えます。

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

コードの実行

Android Studio で [Run](実行) ボタンを押して、プロジェクトをビルドして実行します。 コンソールには、そのコードからの出力と ChatClient からのロガー出力が表示されます。

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

開始する前に、必ず次のことを行ってください。

  • アクティブなサブスクリプションがある Azure アカウントを作成します。 詳細については、アカウントの無料作成に関するページを参照してください。

  • Visual Studio

  • Azure Communication Services リソースを作成します。 詳細については、Azure Communication Services リソースの作成に関するページを参照してください。 このクイック スタートでは、リソース エンドポイントと接続文字列 を記録する必要があります。

  • ユーザー アクセス トークン。 スコープを必ず chat に設定し、トークン文字列と ser_id 文字列をメモしてください。 Azure CLI を使用して、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

設定

新しい C# アプリケーションを作成する

コンソール ウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、ChatQuickstart という名前で新しいコンソール アプリを作成します。 このコマンドにより、1 つのソース ファイルを使用する単純な "Hello World" C# プロジェクトが作成されます。Program.cs。

dotnet new console -o ChatQuickstart

新しく作成したアプリ フォルダーにディレクトリを変更し、dotnet build コマンドを使用してアプリケーションをコンパイルします。

cd ChatQuickstart
dotnet build

パッケージをインストールする

.NET 用 Azure Communication Chat SDK をインストールします

dotnet add package Azure.Communication.Chat

オブジェクト モデル

C# 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスにより処理されます。

名前 説明
ChatClient このクラスは、チャット機能に必要となります。 サブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除します。
ChatThreadClient このクラスは、チャット スレッド機能に必要となります。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信、受信、更新、削除、参加者の追加、削除、取得、入力通知の送信、開封確認を行います。

チャット クライアントを作成する

チャット クライアントを作成するには、Communication Services エンドポイントと、前提条件の手順で生成されたアクセス トークンを使用します。 ユーザーを作成し、トークンを発行して自分のチャット クライアントに渡すには、Identity SDK の CommunicationIdentityClient クラスを使用する必要があります。

詳細については、ユーザー アクセス トークンに関するページを参照してください。

このクイックスタートでは、チャット アプリケーションのトークンを管理するためのサービス レベルの作成については説明しませんが、サービス レベルを使用することをお勧めします。 詳細については、チャットのアーキテクチャに関するドキュメントを参照してください

次のコード スニペットをコピーして、ソース ファイル Program.cs に貼り付けます

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

チャット スレッドを開始する

チャット スレッドは、ChatClient で createChatThread メソッドを使用して作成します

  • このチャットにトピックを指定するには、topic を使用します。チャット スレッドの作成後に、UpdateTopic 関数を使用してトピックを更新することができます。
  • participants プロパティを使用して、チャット スレッドに追加する ChatParticipant オブジェクトのリストを渡します。 ChatParticipant オブジェクトは、CommunicationIdentifier オブジェクトを使用して初期化します。 CommunicationIdentifier は、CommunicationUserIdentifier、MicrosoftTeamsUserIdentifier、または PhoneNumberIdentifier タイプである場合もあります。 たとえば、CommunicationIdentifier オブジェクトを取得するには、「ユーザーの作成」の手順に従って作成したアクセス ID を渡す必要があります

createChatThread メソッドからの応答オブジェクトには、chatThread の詳細が含まれています。 チャット スレッドの操作 (参加者の追加、メッセージの送信、メッセージの削除など) とやり取りするには、ChatClient クライアントで GetChatThreadClient メソッドを使用して、chatThreadClient クライアント インスタンスをインスタンス化する必要があります。

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

チャット スレッド クライアントを取得する

GetChatThreadClient メソッドは、既に存在するスレッドのスレッド クライアントを返します。 作成したスレッドに対し、メンバーの追加、メッセージの送信などの操作を実行するために使用できます。threadId は、既存のチャット スレッドの一意の ID です。

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

すべてのチャット スレッドを一覧表示する

ユーザーが属しているすべてのチャット スレッドを取得するには、GetChatThreads を使用します。

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

チャット スレッドにメッセージを送信する

スレッドにメッセージを送信するには、SendMessage を使用します。

  • メッセージのコンテンツは、content を使用して設定します (必須)。
  • "Text" や "Html" などのメッセージのコンテンツの種類には type を使用します。 指定しない場合は、"Text" が設定されます。
  • 送信者の表示名を指定するには、senderDisplayName を使用します。 指定しない場合は、空の文字列が設定されます。
  • メッセージと共に送信する追加データを含めるには、必要に応じて metadata を使用します。 このフィールドは、開発者がチャット メッセージ機能を拡張し、ユース ケースに応じたカスタム情報を追加するためのメカニズムを提供します。 たとえば、メッセージ内でファイル リンクを共有する場合、'hasAttachment:true' をメタデータに追加することで、受信者のアプリケーションがそれを解析して適切に表示できます。
SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

チャット スレッドからチャット メッセージを受信する

チャット メッセージは、チャット スレッド クライアントで、特定の間隔で GetMessages メソッドをポーリングすることによって取得できます。

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages には、省略可能な DateTimeOffset パラメーターがあります。 このオフセットを指定した場合、その後に受信、更新、または削除されたメッセージを受け取ることになります。 オフセット時刻よりも前に受信したものの、その後、編集または削除されたメッセージも返されることに注意してください。

GetMessages は、メッセージに対して UpdateMessage や DeleteMessage を使用して行われた編集や削除を含む、最新バージョンのメッセージを返します。 削除されたメッセージについては、そのメッセージがいつ削除されたかを示す datetime 値が chatMessage.DeletedOn から返されます。 編集されたメッセージについては、メッセージがいつ編集されたかを示す datetime が chatMessage.EditedOn から返されます。 メッセージの最初の作成日時には、chatMessage.CreatedOn を使用してアクセスできます。これをメッセージの並べ替えに使用することができます。

GetMessages は、chatMessage.Type で識別できるさまざまな種類のメッセージを返します。 次の種類があります。

  • Text:スレッド メンバーによって送信された通常のチャット メッセージ。

  • Html:書式設定されたテキスト メッセージ。 Communication Services ユーザーは現在、RichText メッセージを送信できないことに注意してください。 このメッセージ型は、Teams の相互運用シナリオで、Teams ユーザーから Communication Services ユーザーに送信されるメッセージでサポートされています。

  • TopicUpdated:トピックが更新されたことを示すシステム メッセージ。 (読み取り専用)

  • ParticipantAdded: 1 人以上の参加者がチャット スレッドに追加されたことを示すシステム メッセージ。(読み取り専用)

  • ParticipantRemoved:参加者がチャット スレッドから削除されたことを示すシステム メッセージ。

詳細については、「メッセージの種類」を参照してください。

チャット スレッドに参加者としてユーザーを追加する

スレッドの作成後、ユーザーを追加したり削除したりすることができます。 追加したユーザーには、スレッドにメッセージを送信したり、他の参加者を追加または削除したりできるアクセス権が与えられます。 `add` を呼び出す前に必ず、そのユーザーの新しいアクセス トークンと ID を取得してください。 チャット クライアントを初期化するためには、ユーザーにアクセス トークンが必要となります。

チャット スレッドに 1 人以上の参加者を追加するには、AddParticipants を使用します。 各スレッド参加者でサポートされている属性は次のとおりです。

  • `id` (必須) は、スレッド参加者の ID です。
  • displayName (省略可) は、スレッド参加者の表示名です。
  • shareHistoryTime (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。
var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

スレッド参加者を取得する

チャット スレッドの参加者を取得するには、GetParticipants を使用します。

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

開封確認メッセージを送信する

メッセージがユーザーに読まれたことを他の参加者に通知するには、SendReadReceipt を使用します。

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

コードの実行

アプリケーション ディレクトリから dotnet run コマンドを使用してアプリケーションを実行します。

dotnet run

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

開始する前に、必ず次のことを行ってください。

  • アクティブなサブスクリプションがある Azure アカウントを作成します。 詳細については、アカウントの無料作成に関するページを参照してください。

  • [Xcode](https://developer.apple.com/xcode/) と [CocoaPods](https://cocoapods.org/) をインストールします。 Xcode は、このクイックスタート用の iOS アプリケーションの作成に、CocoaPods は依存関係のインストールに使用します。

  • Azure Communication Services リソースを作成します。 詳細については、「クイックスタート: Communication Services のリソースを作成して管理する」を参照してください。 このクイック スタートでは、リソース エンドポイントと接続文字列を記録する必要があります。

  • Azure Communication Services で 2 人のユーザーを作成し、それらに対してユーザー アクセス トークンを発行します。 スコープを必ず chat に設定し、トークン文字列と ser_id 文字列をメモしてください。 このクイックスタートでは、最初の参加者でスレッドを作成した後、そのスレッドに 2 人目の参加者を追加します。 Azure CLI を使用して、接続文字列を指定して次のコマンドを実行して、ユーザーとアクセス トークンを作成することもできます。

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    詳細については、「Azure CLI を使用してアクセス トークンを作成および管理する」を参照してください。

設定

新しい iOS アプリケーションを作成する

Xcode を開き、 [Create a new Xcode project (新しい Xcode プロジェクトを作成)] を選択します。 次に、プラットフォームとして **[iOS]** を選択し、テンプレートとして **[App](アプリ)** を選択します。

プロジェクト名として、「**ChatQuickstart**」と入力します。 次に、インターフェイスとして **[Storyboard](ストーリーボード)** 、ライフ サイクルとして **[UIKit App Delegate](UIKit アプリ デリゲート)** 、言語として **[Swift]** を選択します。

**[Next](次へ)** を選択し、プロジェクトの作成先ディレクトリを選択します。

ライブラリをインストールする

CocoaPods を使用して、必要な Communication Services の依存関係をインストールします。

コマンド ラインから、`ChatQuickstart` iOS プロジェクトのルート ディレクトリに移動します。 `pod init` コマンドを使用してポッドファイルを作成します。

そのポッドファイルを開き、`ChatQuickstart` ターゲットに次の依存関係を追加します。

pod 'AzureCommunicationChat', '~> 1.3.6'

`pod install` コマンドを使用して、依存関係をインストールします。 これにより、Xcode ワークスペースも作成されることに注意してください。

`pod install` を実行した後、新しく作成された `.xcworkspace` を選択して、Xcode でプロジェクトを再度開きます。

プレースホルダーを設定する

Xcode でワークスペース `ChatQuickstart.xcworkspace` を開いてから、`ViewController.swift` を開きます。

このクイックスタートでは、`viewController` にコードを追加し、その出力を Xcode コンソールで表示します。 このクイックスタートでは、iOS でのユーザー インターフェイスの構築については説明しません。

`viewController.swift` の先頭で、`AzureCommunication` および `AzureCommunicatonChat` ライブラリをインポートします。

import AzureCommunicationCommon
import AzureCommunicationChat

`ViewController` の `viewDidLoad()` メソッドに次のコードをコピーします。

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

デモンストレーション用に、コードの同期にはセマフォを使用します。 以降の手順では、Azure Communication Services の Chat ライブラリを使用して、プレースホルダーをサンプル コードに置き換えていきます。

チャット クライアントを作成する

チャット クライアントを作成するには、Communication Services エンドポイントと、前提条件の手順で生成されたアクセス トークンを使用します。

詳細については、[ユーザー アクセス トークン](../../access-tokens.md)に関するページを参照してください。

このクイックスタートでは、チャット アプリケーションのトークンを管理するためのサービス レベルの作成については説明しませんが、サービス レベルを使用することをお勧めします。 詳細については、[チャットのアーキテクチャ](../../../concepts/chat/concepts.md)に関するドキュメントを参照してください

コメント <CREATE A CHAT CLIENT> を以下のコード スニペットに置き換えます。

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

`` を、実際の Azure Communication Services リソースのエンドポイントに置き換えます。 `` を 有効な Communication Services アクセス トークンに置き換えます。

オブジェクト モデル

iOS 用 Azure Communication Services Chat SDK が備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前 説明
ChatClient このクラスはチャットの機能に必要です。 サブスクリプション情報を使用してインスタンス化し、それを使用してスレッドを作成、取得、削除し、チャット イベントにサブスクライブします。
ChatThreadClient このクラスはチャット スレッド機能に必要です。 ChatClient を介してインスタンスを取得し、それを使用して、メッセージの送信、受信、更新、および削除を行います。 また、これを使用して、ユーザーの追加、削除、取得、および入力通知と開封確認メッセージの送信を行うこともできます。

チャット スレッドを開始する

`CreateChatThreadResult` は、チャット スレッドの作成から返された応答です。 これには、ChatThreadProperties オブジェクトである chatThread プロパティが含まれています。 このオブジェクトには threadId が含まれており、作成されたスレッドに対する操作 (参加者の追加、メッセージの送信など) を実行するための ChatThreadClient を取得するときに使用できます。

コメント <CREATE A CHAT THREAD> を以下のコード スニペットに置き換えます。

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

`` は、有効な Communication Services のユーザー ID に置き換えます。

ここで、セマフォを使用して、処理を続行する前に完了ハンドラーを待機します。 後続の手順で、完了ハンドラーに返された応答の `threadId` を使用します。

すべてのチャット スレッドを一覧表示する

チャット スレッドを作成した後、`ChatClient` の `listChatThreads` メソッドを呼び出すことで、すべてのチャット スレッドを一覧表示できます。 <LIST ALL CHAT THREADS> コメントを、次のコードに置き換えます。

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

チャット スレッド クライアントを取得する

`createClient` メソッドは、既に存在するスレッドの `ChatThreadClient` を返します。 これは、作成したスレッドに対し、参加者の追加、メッセージの送信などの操作を実行する場合に使用できます。threadId は、既存のチャット スレッドの一意の ID です。

`` コメントを、次のコードに置き換えます。

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

チャット スレッドにメッセージを送信する

threadId で識別されるスレッドにメッセージを送信するには、send メソッドを使用します。

メッセージ要求は、`SendChatMessageRequest` を使用して記述します。

  • チャット メッセージの内容は、content を使用して設定します
  • 送信者の表示名を指定するには、senderDisplayName を使用します
  • 'text' や 'html' などのメッセージの種類を指定するには、type を使用します
  • メッセージと共に送信する追加データを含めるには、必要に応じて `metadata` を使用します。 このフィールドは、開発者がチャット メッセージ機能を拡張し、ユース ケースに応じたカスタム情報を追加するためのメカニズムを提供します。 たとえば、メッセージ内でファイル リンクを共有する場合、'hasAttachment:true' をメタデータに追加することで、受信者のアプリケーションがそれを解析して適切に表示できます。

`SendChatMessageResult` は、メッセージの送信から返された応答です。ここには ID (メッセージの一意の ID) が含まれています。

コメント <SEND A MESSAGE> を以下のコード スニペットに置き換えます。

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

開封確認メッセージを送信する

`sendReadReceipt` メソッドを使用すると、ユーザーに代わって開封確認イベントをチャット スレッドに送信できます。 `messageId` は、開封されたチャット メッセージの一意の ID です。

コメント <SEND A READ RECEIPT> を以下のコードに置き換えます。

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

チャット スレッドからチャット メッセージを受信する

リアルタイム シグナリングを使用すると、新しい受信メッセージをサブスクライブしてリッスンし、それに応じてメモリ内の現在のメッセージを更新することができます。 Azure Communication Services は、[サブスクライブ可能な一連のイベント](../../../concepts/chat/concepts.md#real-time-notifications)をサポートしています。

コメント <RECEIVE MESSAGES> を以下のコードに置き換えます。 通知を有効にした後、新しいメッセージを送信して ChatMessageReceivedEvents を確認してみてください。

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

チャット メッセージは、特定の間隔で `listMessages` メソッドをポーリングすることによって取得することもできます。 listMessages に対して次のコード スニペットを実行します

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

チャット スレッドに参加者としてユーザーを追加する

スレッドの作成後、ユーザーを追加したり削除したりすることができます。 追加したユーザーには、スレッドにメッセージを送信したり、他の参加者を追加または削除したりできるアクセス権が与えられます。 `add` を呼び出す前に必ず、そのユーザーの新しいアクセス トークンと ID を取得してください。 チャット クライアントを初期化するためには、ユーザーにアクセス トークンが必要となります。

チャット スレッドに 1 人以上の参加者を追加するには、ChatThreadClient の add メソッドを使用します。 各スレッド参加者でサポートされている属性は次のとおりです。

  • `id` (必須) は、スレッド参加者の ID です。
  • displayName (省略可) は、スレッド参加者の表示名です。
  • `shareHistoryTime` (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。

`` コメントを、次のコードに置き換えます。

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

`` を、追加するユーザーの Communication Services ユーザー ID に置き換えます。

スレッド内のユーザーを一覧表示する

特定のチャット スレッドのすべての参加者を取得するには、listParticipants メソッドを使用します。

コメント `` を、次のコードに置き換えます。

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

プッシュ通知

プッシュ通知は、モバイル アプリがフォアグラウンドで動作していない状況で、チャット スレッドでメッセージの着信をクライアントに通知することができます。 現在、Notification Hub を使用したチャット プッシュ通知の送信は、IOS SDK バージョン 1.3.0 でサポートされています。 詳細については、「チャット アプリでプッシュ通知を有効にする」の記事を参照してください。

コードの実行

Xcode で [Run](実行) ボタンをクリックし、プロジェクトをビルドして実行します。 コンソールには、そのコードからの出力と ChatClient からのロガー出力が表示されます。

**注:** `Build Settings > Build Options > Enable Bitcode` を `No` に設定します。 現時点では、AzureCommunicationChat SDK for iOS では bitcode の有効化がサポートされていません。次の GitHub のイシューによって追跡されています。

サンプル コード

このクイックスタートの最終的なコードは GitHub にあります。

前提条件

ユーザーの作成

Power Automate フローを編集モードで開いた状態で、以下の手順を Power Automate で行います。

Communication Services Identity コネクタを使用してワークフローに新しいステップを追加するには、以下の手順を行います。

  1. デザイナーで、新しいアクションの追加先となるステップで [新しいステップ] を選択します。 ステップとステップの間に新しいアクションを追加するには、それらのステップ間の矢印にポインターを合わせて、正符号 (+) を選択し、[アクションの追加] を選択します。

  2. [操作を選択してください] という検索ボックスに「Communication Services Identity」と入力します。 アクションの一覧から [ユーザーの作成] を選択します。

    Azure Communication Services Identity コネクタのユーザー作成アクションを示すスクリーンショット。

  3. 接続文字列を入力します。 Azure portal の接続文字列 URL を取得するには、Azure Communication Services リソースに移動します。 リソース メニューで [キー] を選択し、[接続文字列] を選択します。 コピー アイコンを選択して、接続文字列をコピーします。

    Azure Communication Services リソース内の [キー] ページを示すスクリーンショット。

  4. 接続名を入力します。

  5. [詳細オプションの表示] を選択し、トークン スコープを選択します。 このアクションにより、指定したスコープでのアクセス トークンとその有効期限が出力されます。 このアクションにより、Communication Services ユーザー ID となるユーザー ID も生成されます。

    Azure Communication Services Identity コネクタのユーザー作成アクションのオプションを示すスクリーンショット。

  6. [トークン スコープ アイテム] で、[チャット] を選択します。

    Azure Communication Services Chat コネクタの詳細オプションを示すスクリーンショット。

  7. ［作成］ を選択します ユーザー ID とアクセス トークンが表示されます。

チャット スレッドの作成

  1. 新しいアクションを追加します。

  2. [操作を選択してください] 検索ボックスに、「Communication Services Chat」と入力します。 アクションの一覧から [チャット スレッドの作成] を選択します。

    Azure Communication Services Chat コネクタのチャット スレッド作成アクションを示すスクリーンショット。

  3. Communication Services エンドポイント URL を入力します。 Azure portal のエンドポイント URL を取得するには、Azure Communication Services リソースに移動します。 リソース メニューで [キー] を選択し、[エンドポイント] を選択します。

  4. 接続名を入力します。

  5. 前のセクションで生成されたアクセス トークンを選択し、チャット スレッド トピックの説明を追加します。 作成したユーザーを追加し、参加者の名前を入力します。

    Azure Communication Services Chat コネクタのチャット スレッド作成アクションを示すスクリーンショット。

メッセージの送信

  1. 新しいアクションを追加します。

  2. [操作を選択してください] 検索ボックスに、「Communication Services Chat」と入力します。 アクションの一覧から [チャット スレッドにメッセージを送信] を選択します。

    Azure Communication Services Chat コネクタのチャット メッセージ送信アクションを示すスクリーンショット。

  3. アクセス トークン、スレッド ID、コンテンツ、名前を入力します。

    Azure Communication Services Chat コネクタのチャット メッセージ送信アクション ダイアログを示すスクリーンショット。

チャット スレッド メッセージの一覧表示

メッセージが正しく送信されたことを確認するには、以下を行います。

  1. 新しいアクションを追加します。

  2. [操作を選択してください] 検索ボックスに、「Communication Services Chat」と入力します。 アクションの一覧から [チャット スレッド メッセージの一覧表示] を選択します。

    Azure Communication Services Chat コネクタのチャット メッセージ一覧表示アクションを示すスクリーンショット。

  3. アクセス トークンとスレッド ID を入力します。

    Azure Communication Services Chat コネクタのチャット メッセージ一覧表示アクションを示すスクリーンショット。

ロジック アプリをテストする

ワークフローを手動で開始するには、デザイナーのツール バーの [実行] を選択します。 このワークフローでは、ユーザーを作成し、そのユーザーに対してアクセス トークンを発行した後、トークンを削除してユーザーを削除します。 詳細については、ワークフローを実行する方法に関するセクションを確認してください。

次に、[チャット スレッド メッセージの一覧表示] を選択します。 アクション出力で、送信されたメッセージを確認します。

Azure Communication Services Chat コネクタのチャット メッセージ送信アクションの結果を示すスクリーンショット。

ワークフロー リソースをクリーンアップする

ロジック アプリのワークフローおよび関連するリソースのクリーンアップについては、Logic Apps リソースのクリーンアップ方法に関するセクションを参照してください。

リソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして解除する場合は、リソースまたはリソース グループを削除できます。 リソース グループを削除すると、それに関連付けられている他のリソースも削除されます。 詳細については、リソースのクリーンアップに関する記事を参照してください。

次の手順

このクイック スタートでは、次の方法について説明しました。

  • チャット クライアントを作成する
  • 2人のユーザーでスレッドを作成する
  • メッセージをスレッドに送信する
  • スレッドからメッセージを受信する
  • スレッドからユーザーを削除する

チャット ヒーロー アプリを試す

次のことも実行できます。