Případy použití identifikátorů řetězců ve komunikačních sadách SDK

Tento článek obsahuje případy použití pro výběr řetězce (Nezpracovaného ID) jako typu reprezentace typu CommunicationIdentifier v sadách SDK služby Azure Communication Services. Následující doprovodné materiály vám pomůžou porozumět některým případům použití, kdy můžete chtít zvolit nezpracované ID u odvozených typů CommunicationIdentifier.

Případy použití pro volbu identifikátoru

Běžným úkolem při implementaci komunikačních scénářů je identifikovat účastníky konverzací. Při používání sad SDK komunikačních služeb poskytuje CommunicationIdentifier schopnost jedinečně identifikovat tyto účastníky.

CommunicationIdentifier má následující výhody:

• Poskytuje dobré automatické dokončování v prostředích IDE.
• Umožňuje použití případu přepínače podle typu k řešení různých toků aplikací.
• Umožňuje omezit komunikaci na konkrétní typy.
• Povolte přístup k podrobnostem identifikátoru a použijte je k volání jiných rozhraní API (jako je rozhraní Microsoft Graph API), abyste účastníkům komunikace poskytli bohaté prostředí.

Kromě toho lze CommunicationIdentifier a odvozené typy (MicrosoftTeamsUserIdentifierPhoneNumberIdentifieratd.) převést na řetězcové vyjádření (Raw ID) a obnovit z řetězce, což usnadňuje implementaci následujících scénářů:

• Ukládejte identifikátory v databázi a používejte je jako klíče.
• V slovníkech používejte identifikátory jako klíče.
• Implementujte intuitivní rozhraní REST CRUD API pomocí identifikátorů jako klíče v cestách rozhraní REST API, a nemusíte se spoléhat na datové části POST.
• Identifikátory použijte jako klíče v deklarativních architekturách uživatelského rozhraní, jako je React, abyste se vyhnuli zbytečnému opětovnému vykreslování.

Vytváření communicationIdentifier a načítání nezpracovaných ID

CommunicationIdentifier lze vytvořit z nezpracovaného ID a Nezpracované ID lze načíst z typu odvozeného z CommunicationIdentifier. Odebere potřebu všech vlastních metod serializace, které by mohly převzít pouze určité vlastnosti objektu a vynechat ostatní. Například má více vlastností, MicrosoftTeamsUserIdentifier jako IsAnonymous jsou nebo Cloud metody pro načtení těchto hodnot (v závislosti na platformě). Použití metod poskytovaných sadou SDK komunikační identity zaručuje, že způsob serializace identifikátorů zůstane kanonický a konzistentní i v případě, že se přidají další vlastnosti.

Získání nezpracovaného ID z CommunicationUserIdentifier:

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

Vytvoření instance CommunicationUserIdentifier z nezpracovaného ID:

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

Další příklady specifické pro platformu najdete v následujícím článku: Vysvětlení typů identifikátorů

Ukládání CommunicationIdentifier v databázi

Jednou z typických úloh, které může být potřeba od vás, je mapování uživatelů služeb Azure Communication Services na uživatele přicházející z uživatelské databáze společnosti Contoso nebo zprostředkovatele identity. Toho obvykle dosáhnete přidáním dalšího sloupce nebo pole do databáze uživatele Contoso nebo zprostředkovatele identity. Nicméně vzhledem k charakteristikám nezpracovaného ID (stabilní, globálně jedinečné a deterministické), můžete ho také zvolit jako primární klíč pro uživatelské úložiště.

Za předpokladu, ContosoUser že je třída, která představuje uživatele vaší aplikace, a chcete ji uložit spolu s odpovídajícím CommunicationIdentifier databáze. Původní hodnota může CommunicationIdentifier pocházet z rozhraní API pro komunikaci, volání nebo chatu nebo z vlastního rozhraní CONTOSO API, ale může být reprezentována jako string datový typ v programovacím jazyce bez ohledu na to, jaký je základní typ:

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

RawId K vlastnosti CommunicationId získáte řetězec, který lze uložit v databázi:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Pokud chcete získat CommunicationIdentifier z uloženého NEZpracovaného ID, musíte předat nezpracovaný řetězec metodě FromRawId() :

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

CommunicationUserIdentifierVrátí hodnotu , PhoneNumberIdentifierMicrosoftTeamsUserIdentifier nebo UnknownIdentifier na základě typu identifikátoru.

Ukládání CommunicationIdentifieru v kolekcích

Pokud váš scénář vyžaduje práci s několika objekty CommunicationIdentifier v paměti, můžete je chtít uložit do kolekce (slovník, seznam, sada hodnot hash atd.). Kolekce je užitečná například při údržbě seznamu účastníků hovoru nebo chatu. Vzhledem k tomu, že logika hash spoléhá na hodnotu Raw ID, můžete použít CommunicationIdentifier v kolekcích, které vyžadují, aby prvky měly spolehlivé chování hash. Následující příklady ukazují přidání CommunicationIdentifier objektů do různých typů kolekcí a kontrolu, jestli jsou obsaženy v kolekci vytvořením instance nových identifikátorů z hodnoty Raw ID.

Následující příklad ukazuje, jak se dá raw ID použít jako klíč ve slovníku k ukládání zpráv uživatele:

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];
}

Vzhledem k tomu, že logika hash spoléhá na hodnotu Nezpracovaného ID, můžete ji použít CommunicationIdentifier jako klíč ve slovníku přímo:

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")];
}

Logika hash, která spoléhá na hodnotu Raw ID, umožňuje také přidat CommunicationIdentifier objekty do sad hash:

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"))){
        //...
     }
}

Dalším případem použití je použití nezpracovaných ID v mobilních aplikacích k identifikaci účastníků. Pokud chcete tyto informace zpracovávat místně v knihovně uživatelského rozhraní, můžete vložit data zobrazení účastníků pro vzdáleného účastníka, aniž byste je odesílali do služby Azure Communication Services. Tato data zobrazení můžou obsahovat UIImage, která představuje avatara, který se má vykreslit, a zobrazovaný název, který se místo toho může zobrazit. Účastník CommunicationIdentifier i Nezpracované ID načtené z něj lze použít k jedinečné identifikaci vzdáleného účastníka.

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)")
      }
    }
  }
}    

Použití nezpracovaných ID jako klíče v cestách k rozhraní REST API

Při návrhu rozhraní REST API můžete mít koncové body, které přijímají CommunicationIdentifier řetězec nebo řetězec nezpracovaného ID. Pokud se identifikátor skládá z několika částí (například ObjectID, název cloudu atd. MicrosoftTeamsUserIdentifier), možná ho budete muset předat do textu požadavku. Použití nezpracovaného ID však umožňuje adresovat entitu v cestě URL místo předání celého složeného objektu jako JSON v těle. Abyste mohli mít intuitivnější rozhraní 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();
}

Extrahování podrobností identifikátoru z nezpracovaných ID

Konzistentní základní nezpracované ID umožňuje:

• Deserializace na správný typ identifikátoru (na základě kterého můžete upravit tok aplikace).
• Extrahování podrobností identifikátorů (například identifikátor pro MicrosoftTeamsUserIdentifier).

Příklad ukazuje obě výhody:

• Typ vám umožní rozhodnout, odkud má avatar odcházet.
• Rozložené podrobnosti umožňují dotazovat se na rozhraní API správným způsobem.

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;
    }
}

K vlastnostem nebo metodám určitého typu CommunicationIdentifier , který je uložený v databázi Contoso ve formě řetězce (Raw ID).

Použití nezpracovaných ID jako klíče v architekturách uživatelského rozhraní

Nezpracované ID identifikátoru je možné použít jako klíč v součástech uživatelského rozhraní ke sledování určitého uživatele a vyhnout se zbytečným opakovaným vykreslováním a voláním rozhraní API. V tomto příkladu měníme pořadí vykreslování uživatelů v seznamu. V reálném světě můžeme chtít zobrazit nové uživatele jako první nebo znovu uspořádat uživatele na základě určité podmínky (například ručně vyvolaný). V zájmu jednoduchosti následující příklad pouze obrátí pořadí, ve kterém se uživatelé vykreslují.

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>;
});

---

Další kroky

V tomto článku jste se naučili:

• Správně identifikovat případy použití pro výběr nezpracovaného ID
• Převod mezi nezpracovaným ID a různými typy CommunicationIdentifier

Další informace najdete v následujících příručkách pro rychlý start:

• Principy typů identifikátorů
• Referenční dokumentace