Communication SDK での文字列識別子のユースケース

[アーティクル]
11/30/2023

この記事では、Azure Communication Services SDK で CommunicationIdentifier 型の表現型として文字列 (Raw ID) を選択した場合のユースケースについて説明します。このガイダンスに従うと、CommunicationIdentifier 派生型ではなく、Raw ID を選択すべきユースケースを理解することができます。

識別子を選択するユースケース

コミュニケーションシナリオを実装する際の一般的なタスクは、会話の参加者を識別することです。 Communication Services SDK を使用している場合、CommunicationIdentifier に、これらの参加者を一意に識別する機能が用意されています。

CommunicationIdentifier には、次の利点があります。

IDE で利用できる優れたオートコンプリートを提供します。
さまざまなアプリケーションフローに対応するため、型別にスイッチケースを使用できます。
特定の型への通信を制限できます。
識別子の詳細にアクセスできるようにし、それを使用して他の API (Microsoft Graph API など) を呼び出すことで、会話の参加者に豊富なエクスペリエンスを提供します。

さらに、CommunicationIdentifier とその派生型 (MicrosoftTeamsUserIdentifier や PhoneNumberIdentifier など) は、文字列表現 (Raw ID) に変換でき、その文字列から復元することもできるため、次のシナリオを簡単に実装できます。

識別子をデータベースに格納し、キーとして使用します。
識別子をディクショナリのキーとして使用します。
POST ペイロードに依存する代わりに、REST API パスのキーとして識別子を使用して、直感的な REST CRUD API を実装します。
React などの宣言型 UI フレームワークで識別子をキーとして使用して、不要な再レンダリングを回避します。

CommunicationIdentifier を作成して Raw ID を取得する

CommunicationIdentifier は Raw ID から作成でき、Raw ID は CommunicationIdentifier から派生した型から取得できます。これにより、特定のオブジェクトプロパティだけを取り込んで他のプロパティを省略するような、カスタムのシリアル化メソッドが不要になります。たとえば、MicrosoftTeamsUserIdentifier には、IsAnonymous や Cloud といった、これらの値を取得するために使用する複数のプロパティがあります (プラットフォームによって異なります)。 Communication Identity SDK で提供されるメソッドを使用することで、プロパティが追加されても、識別子のシリアル化方法を正規化し、一貫性を保つことができます。

CommunicationUserIdentifier から Raw ID を取得します。

public async Task GetRawId()
{
    ChatMessage message = await ChatThreadClient.GetMessageAsync("678f26ef0c");
    CommunicationIdentifier communicationIdentifier = message.Sender;
    String rawId = communicationIdentifier.RawId;
}

Raw ID から CommunicationUserIdentifier のインスタンスを作成します。

public void CommunicationIdentifierFromGetRawId()
{
    String rawId = "8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130";
    CommunicationIdentifier communicationIdentifier = CommunicationIdentifier.FromRawId(rawId);
}

プラットフォーム固有のその他の例については、識別子の型に関する記事を参照してください。

CommunicationIdentifier をデータベースに格納する

よくある作業の 1 つは、ACS ユーザーを Contoso ユーザーデータベースまたは ID プロバイダーから取得したユーザーにマッピングすることです。これは通常、Contoso ユーザー DB または ID プロバイダーに、列またはフィールドを追加することで行います。ただし、Raw ID の特性 (安定し、グローバルに一意で、決定論的) を考慮して、これをユーザーストレージの主キーとして選択することもできます。

ContosoUser をアプリケーションのユーザーを表すクラスと仮定し、対応する CommunicationIdentifier と共にデータベースに保存するとします。 CommunicationIdentifier の元の値は、Communication Identity、Calling API、Chat API、またはカスタム Contoso API から取得できますが、基になる型が何であっても、どのプログラミング言語でも string データ型として表すことができます。

public class ContosoUser
{
    public string Name { get; set; }
    public string Email { get; set; }
    public string CommunicationId { get; set; }
}

CommunicationId の RawId プロパティにアクセスすることで、データベースに格納できる文字列を取得できます。

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

    ContosoUser user = new ContosoUser()
    {
        Name = "John",
        Email = "john@doe.com",
        CommunicationId = communicationIdentifier.RawId
    };
    SaveToDb(user);
}

格納されている Raw ID から CommunicationIdentifier を取得する場合は、生文字列を FromRawId() メソッドに渡す必要があります。

public void GetFromDatabase()
{
    ContosoUser user = GetFromDb("john@doe.com");
    CommunicationIdentifier communicationIdentifier = CommunicationIdentifier.FromRawId(user.CommunicationId);
}

識別子の型に基づいて、CommunicationUserIdentifier、PhoneNumberIdentifier、MicrosoftTeamsUserIdentifier、UnknownIdentifier のいずれかが返されます。

CommunicationIdentifier をコレクションに格納する

複数の CommunicationIdentifier オブジェクトをメモリ上で操作する必要がある場合は、それらをコレクション (ディクショナリ、リスト、ハッシュセットなど) に格納することをお勧めします。コレクションは、通話やチャットの参加者のリストを管理する場合などに便利です。ハッシュロジックは Raw ID の値に依存するため、要素に信頼性の高いハッシュ動作が求められるコレクションでは CommunicationIdentifier を使用できます。次の例では、さまざまな種類のコレクションに CommunicationIdentifier オブジェクトを追加し、Raw ID の値から新しい識別子のインスタンスを作成することで、それらがコレクションに含まれているかどうかを確認する方法を示します。

次の例は、Raw ID をディクショナリのキーとして使用して、ユーザーのメッセージを格納する方法を示しています。

public void StoreMessagesForContosoUsers()
{
    var communicationUser = new CommunicationUserIdentifier("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130");
    var teamsUserUser = new CommunicationUserIdentifier("45ab2481-1c1c-4005-be24-0ffb879b1130");
    
    // A dictionary with a CommunicationIdentifier as key might be used to store messages of a user.
    var userMessages = new Dictionary<string, List<Message>>
    {
        { communicationUser.RawId, new List<Message>() },
        { teamsUserUser.RawId, new List<Message>() },
    };

    // Retrieve messages for a user based on their Raw ID.
    var messages = userMessages[communicationUser.RawId];
}

ハッシュロジックは Raw ID の値に依存するため、CommunicationIdentifier 自体をディクショナリのキーとして直接使用できます。

public void StoreMessagesForContosoUsers()
{
    // A dictionary with a CommunicationIdentifier as key might be used to store messages of a user.
    var userMessages = new Dictionary<CommunicationIdentifier, List<Message>>
    {
        { new CommunicationUserIdentifier("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130"), new List<Message>() },
        { new MicrosoftTeamsUserIdentifier("45ab2481-1c1c-4005-be24-0ffb879b1130"), new List<Message>() },
    };

    // Retrieve messages for a user based on their Raw ID.
    var messages = userMessages[CommunicationIdentifier.FromRawId("8:acs:bbbcbc1e-9f06-482a-b5d8-20e3f26ef0cd_45ab2481-1c1c-4005-be24-0ffb879b1130")];
}

Raw ID の値に依存するハッシュロジックでは、ハッシュセットに CommunicationIdentifier オブジェクトを追加することもできます。

public void StoreUniqueContosoUsers()
{
    // A hash set of unique users of a Contoso application.
    var users = new HashSet<CommunicationIdentifier>
    {
        new PhoneNumberIdentifier("+14255550123"),
        new UnknownIdentifier("28:45ab2481-1c1c-4005-be24-0ffb879b1130")
    };

    // Implement custom flow for a new communication user.
     if (users.Contains(CommunicationIdentifier.FromRawId("4:+14255550123"))){
        //...
     }
}

もう 1 つのユースケースは、参加者を識別するために、モバイルアプリケーションで Raw ID を使用することです。この情報を Azure Communication Services に送信せずに UI ライブラリでローカルに処理する場合は、リモート参加者の参加者ビューデータを挿入できます。このビューデータには、レンダリングするアバターを表す UIimage と、必要に応じて代わりに表示することのできる表示名を含めることができます。参加者の CommunicationIdentifier とそこから取得した Raw ID の両方を使用して、リモート参加者を一意に識別できます。

callComposite.events.onRemoteParticipantJoined = { identifiers in
  for identifier in identifiers {
    // map identifier to displayName
    let participantViewData = ParticipantViewData(displayName: "<DISPLAY_NAME>")
    callComposite.set(remoteParticipantViewData: participantViewData,
                      for: identifier) { result in
      switch result {
      case .success:
        print("Set participant view data succeeded")
      case .failure(let error):
        print("Set participant view data failed with \(error)")
      }
    }
  }
}

REST API パスで Raw ID をキーとして使用する

REST API を設計する際は、CommunicationIdentifier または Raw ID 文字列を指定できるエンドポイントを使用できます。識別子が複数の要素 (MicrosoftTeamsUserIdentifier を使用している場合は ObjectID、クラウド名など) で構成されている場合は、これを要求本文で渡す必要がある場合があります。しかし、Raw ID を使用することで、複合オブジェクト全体を JSON として本文に渡す代わりに、URL パスとしてエンティティのアドレスを指定することができます。これにより、より直観的な REST CRUD API を設計できます。

public async Task UseIdentifierInPath()
{
    CommunicationIdentifier user = GetFromDb("john@doe.com");
    
    using HttpResponseMessage response = await client.GetAsync($"https://contoso.com/v1.0/users/{user.RawId}/profile");
    response.EnsureSuccessStatusCode();
}

Raw ID から識別子の詳細を抽出する

基になる Raw ID に一貫性があることで、次のことが可能になります。

適切な識別子の型に逆シリアル化する (これに基づいて、アプリのフローを調整できます)。
識別子の詳細を抽出する (MicrosoftTeamsUserIdentifier の oid など)。

この例では、次の両方の利点を示します。

この型を使用すると、アバターを取得する場所を指定できるようになります。
詳細を分解することで、正しい方法で API をクエリできます。

public void ExtractIdentifierDetails()
{
    ContosoUser user = GetFromDb("john@doe.com");

    string rawId = user.CommunicationIdentifier;
    CommunicationIdentifier teamsUser = CommunicationIdentifier.FromRawId(rawId);
    switch (communicationIdentifier)
    {
        case MicrosoftTeamsUserIdentifier teamsUser:
            string getPhotoUri = $"https://graph.microsoft.com/v1.0/users/{teamsUser.UserId}/photo/$value";
            // ...
            break;
        case CommunicationIdentifier communicationUser:
            string getPhotoUri = GetAvatarFromDB(communicationUser.Id);
            // ...
            break;
    }
}

Contoso データベースに格納されている特定の CommunicationIdentifier 型のプロパティまたはメソッドには、文字列 (Raw ID) の形式でアクセスできます。

UI フレームワークで Raw ID をキーとして使用する

識別子の Raw ID を UI コンポーネントのキーとして使用して特定のユーザーを追跡することで、不要な再レンダリングと API 呼び出しを回避できます。この例では、ユーザーをリストに表示する順番を変更しています。実際に使用する際は、新規ユーザーを最初に表示したり、何らかの条件 (たとえば挙手した順など) に基づいてユーザーを並べ替えたりすることが考えられます。わかりやすくするために、次の例では、ユーザーの表示順を逆に並び替えるだけになっています。

import { getIdentifierRawId } from '@azure/communication-common';

function CommunicationParticipants() {
  const [users, setUsers] = React.useState([{ id: getIdentifierRawId(userA), name: "John" }, { id: getIdentifierRawId(userB), name: "Jane" }]);
  return (
    <div>
      {users.map((user) => (
      // React uses keys as hints while rendering elements. Each list item should have a key that's unique among its siblings. 
      // Raw ID can be utilized as a such key.
        <ListUser item={user} key={user.id} />
      ))}
      <button onClick={() => setUsers(users.slice().reverse())}>Reverse</button>
    </div>
  );
}

const ListUser = React.memo(function ListUser({ user }) {
  console.log(`Render ${user.name}`);
  return <div>{user.name}</div>;
});

次のステップ

この記事で学習した内容は次のとおりです。

Raw ID を選択するためのユースケースを正しく識別する
Raw ID とさまざまな種類の CommunicationIdentifier の間で変換する

詳細については、次のクイックスタートガイドを参照してください。

次の方法で共有

Communication SDK での文字列識別子のユースケース

識別子を選択するユースケース

CommunicationIdentifier を作成して Raw ID を取得する

CommunicationIdentifier をデータベースに格納する

CommunicationIdentifier をコレクションに格納する

REST API パスで Raw ID をキーとして使用する

Raw ID から識別子の詳細を抽出する

UI フレームワークで Raw ID をキーとして使用する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Communication SDK での文字列識別子のユース ケース

識別子を選択するユース ケース

CommunicationIdentifier を作成して Raw ID を取得する

CommunicationIdentifier をデータベースに格納する

CommunicationIdentifier をコレクションに格納する

REST API パスで Raw ID をキーとして使用する

Raw ID から識別子の詳細を抽出する

UI フレームワークで Raw ID をキーとして使用する

次のステップ

フィードバック

その他のリソース

Communication SDK での文字列識別子のユースケース

識別子を選択するユースケース