Casos de uso de identificadores de cadena en SDK de comunicación

  • Artículo

En este artículo se proporcionan casos de uso para elegir una cadena (id. sin formato) como un tipo de representación del tipo CommunicationIdentifier en los SDK de Azure Communication Services. Siguiendo esta guía le ayudará a comprender algunos casos de uso cuando quiera elegir un identificador sin procesar en los tipos derivados CommunicationIdentifier.

Casos de uso para elegir un identificador

Una tarea común al implementar escenarios de comunicación es identificar a los participantes de las conversaciones. Cuando se usan SDK de Communication Services, CommunicationIdentifier proporciona la capacidad de identificar de forma única a estos participantes.

CommunicationIdentifier tiene las siguientes ventajas:

  • Proporciona un buen autocompletar en los IDE.
  • Permite usar un cambio de mayúsculas y minúsculas por tipo para abordar diferentes flujos de aplicación.
  • Permite restringir la comunicación a tipos específicos.
  • Permita el acceso a los detalles del identificador y úselos para llamar a otras API (como Microsoft Graph API) para proporcionar una experiencia enriquecida para los participantes de la comunicación.

Encima de esto, CommunicationIdentifier y los tipos derivados (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier, etc.) se pueden convertir en su representación de cadena (Id. sin procesar) y restaurarse a partir de la cadena, lo que facilita la implementación de los siguientes escenarios:

  • Almacene identificadores en una base de datos y úselos como claves.
  • Use identificadores como claves en diccionarios.
  • Implemente API CRUD DE REST intuitivas mediante el uso de identificadores como clave en las rutas de acceso de la API REST, en lugar de tener que confiar en cargas POST.
  • Use identificadores como claves en marcos de interfaz de usuario declarativos como React para evitar una nueva representación innecesaria.

Crear CommunicationIdentifier y recuperar el identificador sin procesar

CommunicationIdentifier se puede crear a partir de un identificador sin procesar y se puede recuperar un identificador sin procesar de un tipo derivado de CommunicationIdentifier. Quita la necesidad de cualquier método de serialización personalizado que pueda tomar solo determinadas propiedades de objeto y omitir otras. Por ejemplo, MicrosoftTeamsUserIdentifier tiene varias propiedades como IsAnonymous o Cloud métodos para recuperar estos valores (dependiendo de una plataforma). El uso de métodos proporcionados por communication Identity SDK garantiza que la forma de serializar identificadores permanecerá canónica y coherente incluso si se agregarán más propiedades.

Obtenga el identificador sin procesar de CommunicationUserIdentifier:

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

Cree una instancia de CommunicationUserIdentifier desde un identificador sin procesar:

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

Puede encontrar ejemplos más específicos de la plataforma en el siguiente artículo: Descripción de los tipos de identificadores

Almacenar CommunicationIdentifier en una base de datos

Uno de los trabajos típicos que puede ser necesario es asignar usuarios de Azure Communication Services a usuarios procedentes de la base de datos de usuario de Contoso o del proveedor de identidades. Normalmente, esto se logra agregando una columna o un campo adicionales en la base de datos de usuario o el proveedor de identidades de Contoso. Sin embargo, dadas las características del identificador sin procesar (estable, globalmente único y determinista), también puede elegirlo como clave principal para el almacenamiento del usuario.

Suponiendo que es ContosoUser una clase que representa a un usuario de la aplicación y quiere guardarla junto con un CommunicationIdentifier correspondiente en la base de datos. El valor original de puede CommunicationIdentifier proceder de las API de identidad de comunicación, llamadas o chat o de una API de Contoso personalizada, pero se puede representar como un string tipo de datos en el lenguaje de programación, independientemente del tipo subyacente:

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

Puede acceder a RawId la CommunicationId propiedad de para obtener una cadena que se puede almacenar en la base de datos:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Si desea obtener CommunicationIdentifier del identificador sin procesar almacenado, debe pasar la cadena sin formato al FromRawId() método :

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

Devolverá CommunicationUserIdentifier, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier o UnknownIdentifier en función del tipo de identificador.

Almacenamiento de CommunicationIdentifier en colecciones

Si el escenario requiere trabajar con varios objetos CommunicationIdentifier en memoria, es posible que quiera almacenarlos en una colección (diccionario, lista, conjunto hash, etc.). Una colección es útil, por ejemplo, para mantener una lista de participantes de llamadas o chat. Como la lógica de hash se basa en el valor de un identificador sin procesar, puede usar CommunicationIdentifier en colecciones que requieren que los elementos tengan un comportamiento hash confiable. En los ejemplos siguientes se muestra cómo agregar objetos CommunicationIdentifier a distintos tipos de colecciones y comprobar si están contenidos en una colección mediante la creación de instancias de nuevos identificadores de un valor de id. sin formato.

En el ejemplo siguiente se muestra cómo se puede usar raw ID como clave en un diccionario para almacenar los mensajes del usuario:

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

Como la lógica de hash se basa en el valor de un identificador sin formato, puede usarse CommunicationIdentifier como clave en un diccionario directamente:

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 lógica de hash que se basa en el valor de un identificador sin formato, también permite agregar CommunicationIdentifier objetos a conjuntos 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"))){
        //...
     }
}

Otro caso de uso es usar identificadores sin procesar en aplicaciones móviles para identificar a los participantes. Puede insertar los datos de vista del participante para el participante remoto si desea controlar esta información localmente en la biblioteca de interfaz de usuario sin enviarlo a Azure Communication Services. Estos datos de vista pueden contener una uiImage que representa el avatar que se va a representar y un nombre para mostrar que pueden mostrarse opcionalmente en su lugar. El participante CommunicationIdentifier y el identificador sin procesar recuperados de él se pueden usar para identificar de forma única a un participante 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 del identificador sin procesar como clave en las rutas de acceso de la API REST

Al diseñar una API REST, puede tener puntos de conexión que acepten o CommunicationIdentifier una cadena de identificador sin procesar. Si el identificador consta de varias partes (como ObjectID, nombre de nube, etc. si usa MicrosoftTeamsUserIdentifier), es posible que tenga que pasarlo en el cuerpo de la solicitud. Sin embargo, el uso de Raw ID permite dirigir la entidad en la ruta de acceso de la dirección URL en lugar de pasar todo el objeto compuesto como json en el cuerpo. Para que pueda tener una API CRUD DE REST más 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();
}

Extraer los detalles del identificador de los identificadores sin procesar.

El identificador sin procesar subyacente coherente permite:

  • Deserialización en el tipo de identificador correcto (en función del cual puedes ajustar el flujo de la aplicación).
  • Extracción de detalles de identificadores (por ejemplo, un oid para MicrosoftTeamsUserIdentifier).

En el ejemplo se muestran ambas ventajas:

  • El tipo le permite decidir de dónde tomar el avatar.
  • Los detalles descomponidos le permiten consultar la API de la manera correcta.
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;
    }
}

Puede acceder a propiedades o métodos para un tipo CommunicationIdentifier específico que se almacena en una base de datos de Contoso en forma de cadena (id. sin formato).

Uso de identificadores sin procesar como clave en marcos de interfaz de usuario

Es posible usar el identificador sin procesar de un identificador como clave en los componentes de la interfaz de usuario para realizar un seguimiento de un usuario determinado y evitar la nueva representación innecesaria y las llamadas API. En el ejemplo, vamos a cambiar el orden de cómo se representan los usuarios en una lista. En el mundo real, es posible que deseemos mostrar a los nuevos usuarios primero o volver a ordenar usuarios en función de alguna condición (por ejemplo, levantada a mano). Por motivos de simplicidad, el ejemplo siguiente simplemente invierte el orden en que se representan los usuarios.

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

Pasos siguientes

En este artículo, ha aprendido cómo:

  • Identificar correctamente los casos de uso para elegir un identificador sin formato
  • Conversión entre el identificador sin procesar y los distintos tipos de communicationIdentifier

Para más información, puede explorar las siguientes guías de inicio rápido: