Cas d’usage pour les identificateurs de chaîne dans les kits SDK communication

Cet article fournit des cas d’usage pour choisir une chaîne (ID brut) comme type de représentation du type CommunicationIdentifier dans les kits SDK Azure Communication Services. Le suivi de ces conseils vous aidera à comprendre certains cas d’usage lorsque vous souhaiterez peut-être choisir un ID brut sur les types dérivés CommunicationIdentifier.

Cas d’usage pour choisir un identificateur

Une tâche courante lors de l’implémentation de scénarios de communication consiste à identifier les participants aux conversations. Lorsque vous utilisez des kits SDK Communication Services, CommunicationIdentifier offre la possibilité d’identifier de manière unique ces participants.

CommunicationIdentifier présente les avantages suivants :

• Fournit une bonne saisie semi-automatique dans les IDE.
• Permet d’utiliser un cas de commutateur par type pour traiter différents flux d’application.
• Permet de restreindre la communication à des types spécifiques.
• Autorisez l’accès aux détails de l’identificateur et utilisez-les pour appeler d’autres API (telles que l’API Microsoft Graph) afin de fournir une expérience riche pour les participants à la communication.

En plus de cela, communicationIdentifier et les types dérivés (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifieretc.) peuvent être convertis en sa représentation sous forme de chaîne (ID brut) et restaurés à partir de la chaîne, ce qui facilite l’implémentation des scénarios suivants :

• Stockez des identificateurs dans une base de données et utilisez-les comme clés.
• Utilisez des identificateurs comme clés dans les dictionnaires.
• Implémentez des API REST CRUD intuitives à l’aide d’identificateurs en tant que clé dans les chemins d’accès de l’API REST, au lieu de devoir compter sur des charges utiles POST.
• Utilisez des identificateurs en tant que clés dans des infrastructures d’interface utilisateur déclaratives telles que React pour éviter le réexécriture inutile.

Création de CommunicationIdentifier et récupération de l’ID brut

CommunicationIdentifier peut être créé à partir d’un ID brut et un ID brut peut être récupéré à partir d’un type dérivé de CommunicationIdentifier. Elle supprime le besoin de toutes les méthodes de sérialisation personnalisées qui peuvent prendre uniquement certaines propriétés d’objet et omettre d’autres. Par exemple, il MicrosoftTeamsUserIdentifier a plusieurs propriétés telles que IsAnonymous ou Cloud méthodes pour récupérer ces valeurs (en fonction d’une plateforme). L’utilisation de méthodes fournies par le Kit de développement logiciel (SDK) Communication Identity garantit que la façon de sérialiser les identificateurs reste canonique et cohérente, même si d’autres propriétés seront ajoutées.

Obtenir l’ID brut de CommunicationUserIdentifier :

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

Instanciez CommunicationUserIdentifier à partir d’un ID brut :

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

Vous trouverez des exemples spécifiques à la plateforme dans l’article suivant : Comprendre les types d’identificateurs

Stockage de CommunicationIdentifier dans une base de données

L’un des travaux classiques qui peuvent être requis à partir de vous consiste à mapper des utilisateurs Azure Communication Services aux utilisateurs provenant de la base de données utilisateur ou du fournisseur d’identité Contoso. Cela est généralement obtenu en ajoutant une colonne ou un champ supplémentaire dans la base de données utilisateur ou le fournisseur d’identité Contoso. Toutefois, étant donné les caractéristiques de l’ID brut (stable, globalement unique et déterministe), vous pouvez également le choisir comme clé primaire pour le stockage utilisateur.

En supposant qu’il ContosoUser s’agit d’une classe qui représente un utilisateur de votre application et que vous souhaitez l’enregistrer avec un CommunicationIdentifier correspondant dans la base de données. La valeur d’origine d’un CommunicationIdentifier peut provenir des API d’identité de communication, d’appel ou de conversation ou d’une API Contoso personnalisée, mais peut être représentée en tant que string type de données dans votre langage de programmation, quel que soit le type sous-jacent :

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

Vous pouvez accéder à RawId la CommunicationId propriété du fichier pour obtenir une chaîne qui peut être stockée dans la base de données :

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Si vous souhaitez obtenir CommunicationIdentifier à partir de l’ID brut stocké, vous devez passer la chaîne brute à FromRawId() la méthode :

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

Elle retourne CommunicationUserIdentifier, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier ou UnknownIdentifier en fonction du type d’identificateur.

Stockage de CommunicationIdentifier dans des collections

Si votre scénario nécessite l’utilisation de plusieurs objets CommunicationIdentifier en mémoire, vous pouvez les stocker dans une collection (dictionnaire, liste, ensemble de hachage, etc.). Une collection est utile, par exemple, pour maintenir une liste d’appels ou de participants de conversation. Comme la logique de hachage s’appuie sur la valeur d’un ID brut, vous pouvez utiliser CommunicationIdentifier dans les collections qui nécessitent des éléments pour avoir un comportement de hachage fiable. Les exemples suivants illustrent l’ajout d’objets CommunicationIdentifier à différents types de collections et de case activée ing s’ils sont contenus dans une collection en instanciant de nouveaux identificateurs à partir d’une valeur d’ID brut.

L’exemple suivant montre comment l’ID brut peut être utilisé comme clé dans un dictionnaire pour stocker les messages de l’utilisateur :

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

Comme la logique de hachage s’appuie sur la valeur d’un ID brut, vous pouvez l’utiliser CommunicationIdentifier comme clé dans un dictionnaire directement :

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 logique de hachage qui s’appuie sur la valeur d’un ID brut vous permet également d’ajouter CommunicationIdentifier des objets à des jeux de hachage :

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 autre cas d’usage utilise des ID bruts dans des applications mobiles pour identifier les participants. Vous pouvez injecter les données d’affichage des participants pour les participants distants si vous souhaitez gérer ces informations localement dans la bibliothèque d’interface utilisateur sans l’envoyer à Azure Communication Services. Ces données d’affichage peuvent contenir un UIImage qui représente l’avatar à afficher, et un nom d’affichage qu’ils peuvent éventuellement afficher à la place. Le participant CommunicationIdentifier et l’ID brut récupérés à partir de celui-ci peuvent être utilisés pour identifier de manière unique un participant distant.

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

Utilisation de l’ID brut comme clé dans les chemins d’accès de l’API REST

Lors de la conception d’une API REST, vous pouvez avoir des points de terminaison qui acceptent une chaîne d’ID CommunicationIdentifier brut ou une chaîne d’ID brut. Si l’identificateur se compose de plusieurs parties (comme ObjectID, cloud name, etc. si vous utilisez MicrosoftTeamsUserIdentifier), vous devrez peut-être le transmettre dans le corps de la demande. Toutefois, l’utilisation de l’ID brut vous permet d’adresser l’entité dans le chemin d’URL au lieu de passer l’objet composite entier en tant que JSON dans le corps. Vous pouvez donc disposer d’une API REST CRUD plus intuitive.

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

Extraction des détails de l’identificateur à partir d’ID bruts.

L’ID brut sous-jacent cohérent autorise :

• Désérialisation au type d’identificateur approprié (en fonction de laquelle vous pouvez ajuster le flux de votre application).
• Extraction des détails des identificateurs (par exemple, un oid pour MicrosoftTeamsUserIdentifier).

L’exemple montre les deux avantages :

• Le type vous permet de décider où prendre l’avatar.
• Les détails décomposés vous permettent d’interroger l’API de la manière appropriée.

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

Vous pouvez accéder aux propriétés ou méthodes d’un type CommunicationIdentifier spécifique stocké dans une base de données Contoso sous la forme d’une chaîne (ID brut).

Utilisation d’ID bruts comme clé dans les frameworks d’interface utilisateur

Il est possible d’utiliser l’ID brut d’un identificateur comme clé dans les composants de l’interface utilisateur pour suivre un certain utilisateur et éviter les appels inutiles de re-rendu et d’API. Dans l’exemple, nous modifions l’ordre de rendu des utilisateurs dans une liste. Dans le monde réel, nous pourrions souhaiter montrer aux nouveaux utilisateurs d’abord ou récommander les utilisateurs en fonction de certaines conditions (par exemple, levées à la main). Par souci de simplicité, l’exemple suivant inverse simplement l’ordre dans lequel les utilisateurs sont rendus.

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

Étapes suivantes

Dans cet article, vous avez appris à effectuer les opérations suivantes :

Pour en savoir plus, vous pouvez explorer les guides de démarrage rapide suivants :

• Comprendre les types d’identificateurs
• Documentation de référence