通訊 SDK 中字串識別碼的使用案例

發行項
04/25/2024

本文提供在 Azure 通訊服務 SDK 中選擇字串 (Raw ID) 作為 CommunicationIdentifier 型別來表示型別的使用案例。遵循本指南可協助您了解一些可能會想要透過 CommunicationIdentifier 衍生型別選擇 Raw ID 的使用案例。

選擇識別碼的使用案例

實作通訊案例時，常見的工作是識別交談的參與者。當您使用通訊服務 SDK 時，CommunicationIdentifier 會提供唯一識別這些參與者的功能。

CommunicationIdentifier 具有下列優點：

在整合式開發環境 (IDE) 中提供良好的自動完成。
允許依型別使用切換案例來解決不同應用程式流程。
允許限制特定型別的通訊。
允許存取標別碼詳細資料，並將其用於呼叫其他 API (例如 Microsoft Graph API)，以提供豐富的通訊參與者體驗。

除此之外，CommunicationIdentifier 和衍生型別 (MicrosoftTeamsUserIdentifier、PhoneNumberIdentifier 等) 可以轉換成其字串表示法 (Raw ID)，並從字串還原以讓下列案例更容易實作：

將識別碼儲存在資料庫中並當成索引鍵使用。
將標別碼當成字典中的索引鍵使用。
在 REST API 路徑中將識別碼當成索引鍵使用來實作直覺式 REST CRUD API，而不是依賴 POST 承載。
在宣告式 UI 架構中將識別碼當成索引鍵使用 (例如 React)，以避免不必要的重新轉譯。

建立 CommunicationIdentifier 並擷取 Raw ID

CommunicationIdentifier 可以從 Raw ID 建立，而 Raw ID 可以從衍生自 CommunicationIdentifier 的型別擷取。其會移除任何自訂序列化方法的需求，此類方法可能只接受特定物件屬性並會省略其他屬性。舉個例子，MicrosoftTeamsUserIdentifier 有多個屬性如 IsAnonymous、Cloud 或擷取這些值的方法 (視平台而定)。使用通訊身分識別 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 儲存在資料庫中

您可能需要的其中一個典型作業，就是將 Azure 通訊服務使用者對應至來自 Contoso 使用者資料庫或識別提供者的使用者。這通常是藉由在 Contoso 使用者 DB 或識別提供者中新增額外的資料行或欄位來達成。不過，由於 Raw ID 的特性 (穩定、全域唯一且具確定性)，您也可以選擇將其當成使用者儲存體的主索引鍵使用。

假設 ContosoUser 是代表您應用程式使用者的類別，而您想要將其連同對應的 CommunicationIdentifier 儲存至資料庫。 CommunicationIdentifier 的原始值可能來自通訊身分識別、電話撥接或聊天 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"))){
        //...
     }
}

另一個使用案例是在行動應用程式中使用 Raw ID 來識別參與者。如果您想要在 UI 程式庫中本機處理此資訊，而非傳送至 Azure 通訊服務，您可以插入遠端參與者的參與者檢視資料。此檢視資料可以包含 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 可讓您定址 URL 路徑中的實體，而非將整個複合物件當成本文中的 JSON 傳遞。因此，您可以擁有更直覺的 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;
    }
}

您可以存取特定 CommunicationIdentifier 的屬性或方法型別，該型別是以字串形式儲存在 Contoso 資料庫中 (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 的不同型別之間轉換

若要深入了解，建議您探索下列快速入門指南：

共用方式為