Condividi tramite

Casi d'uso per gli identificatori di stringa negli SDK di comunicazione

  • Articolo

Questo articolo fornisce casi d'uso per la scelta di una stringa (ID non elaborato) come tipo di rappresentazione del tipo CommunicationIdentifier negli SDK di Servizi di comunicazione di Azure. Seguendo queste indicazioni è possibile comprendere alcuni casi d'uso quando si potrebbe voler scegliere un ID non elaborato sui tipi derivati CommunicationIdentifier.

Casi d'uso per la scelta di un identificatore

Un'attività comune quando si implementano scenari di comunicazione consiste nell'identificare i partecipanti alle conversazioni. Quando si usano gli SDK di Servizi di comunicazione, CommunicationIdentifier offre la possibilità di identificare in modo univoco questi partecipanti.

CommunicationIdentifier presenta i vantaggi seguenti:

  • Fornisce un buon completamento automatico negli IDE.
  • Consente l'uso di un caso switch per tipo per gestire flussi di applicazioni diversi.
  • Consente di limitare la comunicazione a tipi specifici.
  • Consentire l'accesso ai dettagli dell'identificatore e usarli per chiamare altre API (ad esempio l'API Microsoft Graph) per offrire un'esperienza completa per i partecipanti alla comunicazione.

Oltre a questo, CommunicationIdentifier e i tipi derivati (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifiere così via) possono essere convertiti nella relativa rappresentazione di stringa (ID non elaborato) e ripristinati dalla stringa, semplificando l'implementazione degli scenari seguenti:

  • Archiviare gli identificatori in un database e usarli come chiavi.
  • Usare gli identificatori come chiavi nei dizionari.
  • Implementare API CRUD REST intuitive usando gli identificatori come chiave nei percorsi dell'API REST, invece di dover fare affidamento sui payload POST.
  • Usare gli identificatori come chiavi nei framework dichiarativi dell'interfaccia utente, ad esempio React, per evitare il rendering non necessario.

Creazione di CommunicationIdentifier e recupero dell'ID non elaborato

CommunicationIdentifier può essere creato da un ID non elaborato e un ID non elaborato può essere recuperato da un tipo derivato da CommunicationIdentifier. Rimuove la necessità di qualsiasi metodo di serializzazione personalizzato che potrebbe accettare solo determinate proprietà dell'oggetto e omettere altri. Ad esempio, ha MicrosoftTeamsUserIdentifier più proprietà, ad IsAnonymous esempio o Cloud o metodi per recuperare questi valori (a seconda di una piattaforma). L'uso di metodi forniti da Communication Identity SDK garantisce che la modalità di serializzazione degli identificatori rimanga canonica e coerente anche se verranno aggiunte altre proprietà.

Ottenere l'ID non elaborato da CommunicationUserIdentifier:

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

Creare un'istanza di CommunicationUserIdentifier da un ID non elaborato:

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

Per altri esempi specifici della piattaforma, vedere l'articolo seguente: Informazioni sui tipi di identificatore

Archiviazione di CommunicationIdentifier in un database

Uno dei processi tipici che possono essere necessari è eseguire il mapping Servizi di comunicazione di Azure utenti agli utenti provenienti dal database utente contoso o dal provider di identità. Questa operazione viene in genere ottenuta aggiungendo una colonna o un campo aggiuntivo nel database utente contoso o nel provider di identità. Tuttavia, data le caratteristiche dell'ID non elaborato (stabile, univoco a livello globale e deterministico), è possibile sceglierlo anche come chiave primaria per l'archiviazione utente.

Supponendo che sia ContosoUser una classe che rappresenta un utente dell'applicazione e si vuole salvarla insieme a un Elemento CommunicationIdentifier corrispondente nel database. Il valore originale di un CommunicationIdentifier oggetto può provenire dalle API Di comunicazione, Chiamata o Chat o da un'API Contoso personalizzata, ma può essere rappresentato come un string tipo di dati nel linguaggio di programmazione indipendentemente dal tipo sottostante:

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

È possibile accedere alla RawId proprietà di CommunicationId per ottenere una stringa che può essere archiviata nel database:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Se si vuole ottenere CommunicationIdentifier dall'ID non elaborato archiviato, è necessario passare la stringa non elaborata al FromRawId() metodo :

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

Restituisce CommunicationUserIdentifier, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier o UnknownIdentifier in base al tipo di identificatore.

Archiviazione di CommunicationIdentifier nelle raccolte

Se lo scenario richiede l'uso di diversi oggetti CommunicationIdentifier in memoria, è possibile archiviarli in una raccolta (dizionario, elenco, set di hash e così via). Una raccolta è utile, ad esempio, per mantenere un elenco di partecipanti a chiamate o chat. Poiché la logica di hashing si basa sul valore di un ID non elaborato, è possibile usare CommunicationIdentifier nelle raccolte che richiedono che gli elementi abbiano un comportamento di hashing affidabile. Gli esempi seguenti illustrano l'aggiunta di oggetti CommunicationIdentifier a diversi tipi di raccolte e il controllo se sono contenuti in una raccolta creando un'istanza di nuovi identificatori da un valore DI ID non elaborato.

L'esempio seguente mostra come usare l'ID non elaborato come chiave in un dizionario per archiviare i messaggi dell'utente:

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

Poiché la logica di hashing si basa sul valore di un ID non elaborato, è possibile usarla CommunicationIdentifier direttamente come chiave in un dizionario:

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

La logica di hashing che si basa sul valore di un ID non elaborato consente anche di aggiungere CommunicationIdentifier oggetti ai set 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"))){
        //...
     }
}

Un altro caso d'uso consiste nell'usare GLI ID non elaborati nelle applicazioni per dispositivi mobili per identificare i partecipanti. Puoi inserire i dati della visualizzazione partecipante per il partecipante remoto se vuoi gestire queste informazioni localmente nella libreria dell'interfaccia utente senza inviarli a Servizi di comunicazione di Azure. Questi dati di visualizzazione possono contenere un oggetto UIImage che rappresenta l'avatar di cui eseguire il rendering e un nome visualizzato che possono invece visualizzare facoltativamente. Sia il partecipante CommunicationIdentifier che l'ID non elaborato recuperato da esso possono essere usati per identificare in modo univoco un partecipante remoto.

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

Uso dell'ID non elaborato come chiave nei percorsi dell'API REST

Quando si progetta un'API REST, è possibile avere endpoint che accettano una CommunicationIdentifier stringa ID non elaborata o . Se l'identificatore è costituito da più parti, ad esempio ObjectID, nome cloud e così via, se si usa MicrosoftTeamsUserIdentifier, potrebbe essere necessario passarlo nel corpo della richiesta. Tuttavia, l'uso di RAW ID consente di indirizzare l'entità nel percorso URL invece di passare l'intero oggetto composito come JSON nel corpo. In modo che sia possibile avere un'API CRUD REST più intuitiva.

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

Estrazione dei dettagli dell'identificatore dagli ID non elaborati.

L'ID non elaborato sottostante coerente consente:

  • Deserializzazione al tipo di identificatore corretto (in base al quale è possibile regolare il flusso dell'app).
  • Estrazione dei dettagli degli identificatori , ad esempio un oid per MicrosoftTeamsUserIdentifier.

L'esempio mostra entrambi i vantaggi:

  • Il tipo consente di decidere da dove prendere l'avatar.
  • I dettagli scomposti consentono di eseguire query sull'API nel modo corretto.
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;
    }
}

È possibile accedere a proprietà o metodi per un tipo CommunicationIdentifier specifico archiviato in un database Contoso sotto forma di stringa (ID non elaborato).

Uso di ID non elaborati come chiave nei framework dell'interfaccia utente

È possibile usare l'ID non elaborato di un identificatore come chiave nei componenti dell'interfaccia utente per tenere traccia di un determinato utente ed evitare chiamate API e rendering non necessari. Nell'esempio viene modificato l'ordine in cui viene eseguito il rendering degli utenti in un elenco. Nel mondo reale, potrebbe essere necessario mostrare prima i nuovi utenti o riordinare gli utenti in base a una condizione ( ad esempio, alzata a mano). Per semplicità, nell'esempio seguente viene semplicemente invertito l'ordine in cui viene eseguito il rendering degli utenti.

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

Passaggi successivi

In questo articolo si è appreso come:

  • Identificare correttamente i casi d'uso per la scelta di un ID non elaborato
  • Eseguire la conversione tra ID non elaborato e tipi diversi di communicationIdentifier

Per altre informazioni, è possibile esplorare le guide di avvio rapido seguenti: