Udostępnij za pośrednictwem

Przypadki użycia identyfikatorów ciągów w zestawach SDK komunikacji

  • Artykuł

Ten artykuł zawiera przypadki użycia wybierania ciągu (nieprzetworzonego identyfikatora) jako typu reprezentacji typu CommunicationIdentifier w zestawach SDK usług Azure Communication Services. Poniższe wskazówki ułatwią zrozumienie niektórych przypadków użycia, gdy warto wybrać nieprzetworzone identyfikatory dla typów pochodnych CommunicationIdentifier.

Przypadki użycia wybierania identyfikatora

Typowym zadaniem podczas implementowania scenariuszy komunikacyjnych jest zidentyfikowanie uczestników konwersacji. W przypadku korzystania z zestawów SDK usług Communication Services funkcja CommunicationIdentifier zapewnia możliwość unikatowego identyfikowania tych uczestników.

Element CommunicationIdentifier ma następujące zalety:

  • Zapewnia dobre automatyczne uzupełnianie w środowiskach IDE.
  • Umożliwia używanie wielkości liter przełącznika według typu w celu obsługi różnych przepływów aplikacji.
  • Umożliwia ograniczenie komunikacji do określonych typów.
  • Zezwól na dostęp do szczegółów identyfikatora i użyj ich do wywoływania innych interfejsów API (takich jak interfejs API programu Microsoft Graph), aby zapewnić zaawansowane środowisko dla uczestników komunikacji.

Ponadto klasy CommunicationIdentifier i pochodne typy (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifieritp.) można przekonwertować na jego reprezentację ciągu (nieprzetworzony identyfikator) i przywrócić z ciągu, co ułatwia zaimplementowanie następujących scenariuszy:

  • Przechowywanie identyfikatorów w bazie danych i używanie ich jako kluczy.
  • Użyj identyfikatorów jako kluczy w słownikach.
  • Zaimplementuj intuicyjne interfejsy API REST CRUD przy użyciu identyfikatorów jako klucza w ścieżkach interfejsu API REST, zamiast polegać na ładunkach POST.
  • Użyj identyfikatorów jako kluczy w deklaratywnych strukturach interfejsu użytkownika, takich jak React, aby uniknąć niepotrzebnego ponownego renderowania.

Tworzenie identyfikatora CommunicationIdentifier i pobieranie nieprzetworzonego identyfikatora

Identyfikator komunikacji można utworzyć na podstawie nieprzetworzonego identyfikatora, a identyfikator nieprzetworzonego można pobrać z typu pochodzącego z klasy CommunicationIdentifier. Eliminuje ona potrzebę wszelkich niestandardowych metod serializacji, które mogą przyjmować tylko niektóre właściwości obiektu i pomijać inne. Na przykład element MicrosoftTeamsUserIdentifier ma wiele właściwości, takich jak IsAnonymous lub Cloud metody pobierania tych wartości (w zależności od platformy). Użycie metod dostarczanych przez zestaw SDK tożsamości komunikacji gwarantuje, że sposób serializacji identyfikatorów pozostanie kanoniczny i spójny, nawet jeśli zostaną dodane więcej właściwości.

Pobierz nieprzetworzone identyfikatory z elementu CommunicationUserIdentifier:

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

Utworzenie wystąpienia elementu CommunicationUserIdentifier z nieprzetworzonego identyfikatora:

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

Więcej przykładów specyficznych dla platformy można znaleźć w następującym artykule: Opis typów identyfikatorów

Przechowywanie identyfikatora CommunicationIdentifier w bazie danych

Jednym z typowych zadań, które mogą być wymagane od Ciebie, jest mapowanie użytkowników usług Azure Communication Services na użytkowników pochodzących z bazy danych użytkowników firmy Contoso lub dostawcy tożsamości. Jest to zwykle osiągane przez dodanie dodatkowej kolumny lub pola w bazie danych użytkownika firmy Contoso lub dostawcy tożsamości. Jednak biorąc pod uwagę cechy nieprzetworzonego identyfikatora (stabilnego, globalnie unikatowego i deterministycznego), możesz również wybrać go jako klucz podstawowy dla magazynu użytkownika.

Zakładając, że klasa ContosoUser jest klasą reprezentującą użytkownika aplikacji i chcesz zapisać ją wraz z odpowiednim elementem CommunicationIdentifier w bazie danych. Oryginalna wartość elementu CommunicationIdentifier może pochodzić z interfejsów API komunikacji, wywoływania lub czatu albo z niestandardowego interfejsu API firmy Contoso, ale może być reprezentowana jako string typ danych w języku programowania niezależnie od typu bazowego:

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

Możesz uzyskać dostęp do RawId właściwości , CommunicationId aby uzyskać ciąg, który może być przechowywany w bazie danych:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Jeśli chcesz pobrać CommunicationIdentifier dane z przechowywanego nieprzetworzonego identyfikatora, musisz przekazać nieprzetworzonego ciągu do FromRawId() metody:

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

Zwróci wartość CommunicationUserIdentifier, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier lub UnknownIdentifier na podstawie typu identyfikatora.

Przechowywanie elementu CommunicationIdentifier w kolekcjach

Jeśli scenariusz wymaga pracy z kilkoma obiektami CommunicationIdentifier w pamięci, warto przechowywać je w kolekcji (słownik, lista, zestaw skrótów itp.). Kolekcja jest przydatna, na przykład do obsługi listy rozmów lub uczestników czatu. Ponieważ logika tworzenia skrótów opiera się na wartości nieprzetworzonego identyfikatora, można użyć elementu CommunicationIdentifier w kolekcjach, które wymagają od elementów niezawodnego zachowania skrótu. W poniższych przykładach pokazano dodawanie obiektów CommunicationIdentifier do różnych typów kolekcji i sprawdzanie, czy znajdują się one w kolekcji, tworząc wystąpienie nowych identyfikatorów z wartości nieprzetworzonego identyfikatora.

W poniższym przykładzie pokazano, jak nieprzetworzonego identyfikatora można użyć jako klucza w słowniku do przechowywania komunikatów użytkownika:

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

Ponieważ logika tworzenia skrótów opiera się na wartości nieprzetworzonego identyfikatora, możesz bezpośrednio użyć CommunicationIdentifier go jako klucza w słowniku:

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 wyznaczania wartości nieprzetworzonego identyfikatora umożliwia również dodawanie CommunicationIdentifier obiektów do zestawów skrótów:

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

Innym przypadkiem użycia jest użycie nieprzetworzonych identyfikatorów w aplikacjach mobilnych do identyfikowania uczestników. Możesz wstrzyknąć dane widoku uczestnika dla uczestnika zdalnego, jeśli chcesz obsługiwać te informacje lokalnie w bibliotece interfejsu użytkownika bez wysyłania ich do usług Azure Communication Services. Te dane widoku mogą zawierać element UIImage reprezentujący awatar do renderowania, a nazwa wyświetlana, którą można opcjonalnie wyświetlić. Zarówno uczestnik CommunicationIdentifier, jak i Nieprzetworzone identyfikatory pobrane z niego mogą służyć do unikatowego identyfikowania uczestnika zdalnego.

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

Używanie nieprzetworzonego identyfikatora jako klucza w ścieżkach interfejsu API REST

Podczas projektowania interfejsu API REST można mieć punkty końcowe, które akceptują ciąg identyfikatora CommunicationIdentifier nieprzetworzonego lub nieprzetworzonego. Jeśli identyfikator składa się z kilku części (takich jak ObjectID, nazwa chmury itp., jeśli używasz MicrosoftTeamsUserIdentifier), może być konieczne przekazanie go w treści żądania. Jednak użycie nieprzetworzonego identyfikatora umożliwia adresowania jednostki w ścieżce adresu URL zamiast przekazywania całego obiektu złożonego jako kodu JSON w treści. Dzięki temu możesz mieć bardziej intuicyjny interfejs API REST CRUD.

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

Wyodrębnianie szczegółów identyfikatora z nieprzetworzonych identyfikatorów.

Spójny podstawowy identyfikator pierwotny umożliwia:

  • Deserializowanie do odpowiedniego typu identyfikatora (na podstawie którego można dostosować przepływ aplikacji).
  • Wyodrębnianie szczegółów identyfikatorów (takich jak identyfikator oid dla MicrosoftTeamsUserIdentifierelementu ).

W przykładzie przedstawiono obie korzyści:

  • Typ pozwala zdecydować, skąd wziąć awatara.
  • Rozłożone szczegóły umożliwiają wykonywanie zapytań dotyczących interfejsu API we właściwy sposób.
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;
    }
}

Dostęp do właściwości lub metod dla określonego typu CommunicationIdentifier , który jest przechowywany w bazie danych Contoso w postaci ciągu (nieprzetworzonego identyfikatora).

Używanie nieprzetworzonych identyfikatorów jako klucza w strukturach interfejsu użytkownika

Można użyć nieprzetworzonego identyfikatora identyfikatora jako klucza w składnikach interfejsu użytkownika, aby śledzić określonego użytkownika i unikać niepotrzebnego ponownego renderowania i wywołań interfejsu API. W tym przykładzie zmieniamy kolejność renderowania użytkowników na liście. W świecie rzeczywistym możemy chcieć pokazać nowych użytkowników jako pierwszych lub ponownie zamówić użytkowników na podstawie pewnego warunku (na przykład ręcznie podniesionego). Dla uproszczenia poniższy przykład po prostu odwraca kolejność renderowania użytkowników.

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

Następne kroki

W tym artykule zawarto informacje na temat wykonywania następujących czynności:

  • Poprawnie zidentyfikuj przypadki użycia wybierania nieprzetworzonego identyfikatora
  • Konwertowanie między nieprzetworzonym identyfikatorem a różnymi typami elementu CommunicationIdentifier

Aby dowiedzieć się więcej, warto zapoznać się z następującymi przewodnikami Szybki start: