Partilhar via

Casos de uso para identificadores de cadeia de caracteres em SDKs de comunicação

  • Artigo

Este artigo fornece casos de uso para escolher uma cadeia de caracteres (ID bruta) como um tipo de representação do tipo CommunicationIdentifier nos SDKs dos Serviços de Comunicação do Azure. Seguir esta orientação ajudará você a entender alguns casos de uso em que você pode querer escolher uma ID bruta em vez dos tipos derivados de CommunicationIdentifier.

Casos de uso para escolher um identificador

Uma tarefa comum ao implementar cenários de comunicação é identificar os participantes das conversas. Quando você estiver usando SDKs de Serviços de Comunicação, o CommunicationIdentifier fornece a capacidade de identificar exclusivamente esses participantes.

CommunicationIdentifier tem as seguintes vantagens:

  • Fornece um bom preenchimento automático em IDEs.
  • Permite usar um switch caso por tipo para abordar diferentes fluxos de aplicativos.
  • Permite restringir a comunicação a tipos específicos.
  • Permita o acesso aos detalhes do identificador e use-os para chamar outras APIs (como a API do Microsoft Graph) para fornecer uma experiência rica para os participantes da comunicação.

Além disso, o CommunicationIdentifier e os tipos derivados (, , etc.) podem ser convertidos em sua representação de cadeia de caracteres (MicrosoftTeamsUserIdentifierRaw ID) e restaurados a partir da cadeia de caracteres, PhoneNumberIdentifiertornando os seguintes cenários mais fáceis de implementar:

  • Armazene identificadores em um banco de dados e use-os como chaves.
  • Use identificadores como chaves em dicionários.
  • Implemente APIs REST CRUD intuitivas usando identificadores como chave em caminhos de API REST, em vez de depender de cargas úteis POST.
  • Use identificadores como chaves em estruturas declarativas de interface do usuário, como o React, para evitar rerenderização desnecessária.

Criando CommunicationIdentifier e recuperando Raw ID

CommunicationIdentifier pode ser criado a partir de um Raw ID e um Raw ID pode ser recuperado de um tipo derivado de CommunicationIdentifier. Ele elimina a necessidade de quaisquer métodos de serialização personalizados que possam incluir apenas determinadas propriedades de objeto e omitir outras. Por exemplo, o MicrosoftTeamsUserIdentifier tem várias propriedades, como IsAnonymous ou Cloud métodos para recuperar esses valores (dependendo de uma plataforma). O uso de métodos fornecidos pelo SDK de identidade de comunicação garante que a maneira de serializar identificadores permanecerá canônica e consistente, mesmo se mais propriedades forem adicionadas.

Obtenha ID bruto de CommunicationUserIdentifier:

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

Instancie CommunicationUserIdentifier a partir de uma ID bruta:

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

Você pode encontrar mais exemplos específicos de plataforma no seguinte artigo: Compreender os tipos de identificador

Armazenando CommunicationIdentifier em um banco de dados

Um dos trabalhos típicos que podem ser exigidos de você é mapear usuários dos Serviços de Comunicação do Azure para usuários provenientes do banco de dados de usuários ou provedor de identidade da Contoso. Isso geralmente é conseguido adicionando uma coluna ou campo extra no banco de dados de usuário ou no provedor de identidade da Contoso. No entanto, dadas as características do Raw ID (estável, globalmente exclusivo e determinístico), você também pode escolhê-lo como uma chave primária para o armazenamento do usuário.

Supondo que a ContosoUser é uma classe que representa um usuário do seu aplicativo e você deseja salvá-lo junto com um CommunicationIdentifier correspondente no banco de dados. O valor original de um pode vir das APIs de Identidade de Comunicação, Chamada ou Chat ou de uma API personalizada da Contoso, mas pode ser representado como um CommunicationIdentifier string tipo de dados em sua linguagem de programação, independentemente do tipo subjacente:

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

Você pode acessar RawId a CommunicationId propriedade do para obter uma cadeia de caracteres que pode ser armazenada no banco de dados:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Se você quiser obter CommunicationIdentifier a partir da ID bruta armazenada, você precisa passar a cadeia de caracteres bruta para o FromRawId() método:

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

Ele retornará CommunicationUserIdentifier, PhoneNumberIdentifierou MicrosoftTeamsUserIdentifier UnknownIdentifier com base no tipo de identificador.

Armazenando CommunicationIdentifier em coleções

Se o seu cenário exigir o trabalho com vários objetos CommunicationIdentifier na memória, convém armazená-los em uma coleção (dicionário, lista, conjunto de hashes, etc.). Uma coleção é útil, por exemplo, para manter uma lista de participantes de chamadas ou chats. Como a lógica de hash depende do valor de uma ID bruta, você pode usar CommunicationIdentifier em coleções que exigem elementos para ter um comportamento de hash confiável. Os exemplos a seguir demonstram a adição de objetos CommunicationIdentifier a diferentes tipos de coleções e a verificação se eles estão contidos em uma coleção instanciando novos identificadores a partir de um valor de ID bruto.

O exemplo a seguir mostra como o ID bruto pode ser usado como uma chave em um dicionário para armazenar mensagens do usuário:

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 a lógica de hash depende do valor de uma ID bruta, você pode usar CommunicationIdentifier a si mesma como uma chave em um dicionário diretamente:

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

A lógica de hash que depende do valor de uma ID bruta também permite adicionar CommunicationIdentifier objetos a conjuntos de 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"))){
        //...
     }
}

Outro caso de uso é o uso de IDs brutos em aplicativos móveis para identificar participantes. Você pode injetar os dados de exibição do participante para o participante remoto se quiser manipular essas informações localmente na biblioteca da interface do usuário sem enviá-las para os Serviços de Comunicação do Azure. Esses dados de exibição podem conter um UIImage que representa o avatar a ser renderizado e um nome de exibição que eles podem exibir opcionalmente. Tanto o participante CommunicationIdentifier quanto o Raw ID recuperados dele podem ser usados para identificar exclusivamente um 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)")
      }
    }
  }
}

Usando a ID bruta como chave nos caminhos da API REST

Ao projetar uma API REST, você pode ter pontos de extremidade que aceitam uma ou uma CommunicationIdentifier cadeia de caracteres de ID bruto. Se o identificador consistir em várias partes (como ObjectID, nome da nuvem, etc., se você estiver usando MicrosoftTeamsUserIdentifier), talvez seja necessário passá-lo no corpo da solicitação. No entanto, o uso de Raw ID permite endereçar a entidade no caminho da URL em vez de passar todo o objeto composto como um JSON no corpo. Para que possa ter uma API REST CRUD mais 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();
}

Extraindo detalhes do identificador de IDs brutos.

O ID bruto subjacente consistente permite:

  • Desserialização para o tipo de identificador correto (com base no qual você pode ajustar o fluxo do seu aplicativo).
  • Extraindo detalhes de identificadores (como um oid para MicrosoftTeamsUserIdentifier).

O exemplo mostra ambos os benefícios:

  • O tipo permite que você decida de onde tirar o avatar.
  • Os detalhes decompostos permitem que você consulte a API da maneira correta.
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;
    }
}

Você pode acessar propriedades ou métodos para um tipo específico de CommunicationIdentifier armazenado em um banco de dados da Contoso na forma de uma cadeia de caracteres (ID bruto).

Usando IDs brutos como chave em estruturas de interface do usuário

É possível usar o ID bruto de um identificador como uma chave nos componentes da interface do usuário para rastrear um determinado usuário e evitar rerenderizações desnecessárias e chamadas de API. No exemplo, estamos alterando a ordem de como os usuários são renderizados em uma lista. No mundo real, podemos querer mostrar novos usuários primeiro ou reordenar usuários com base em alguma condição (por exemplo, mão levantada). Por uma questão de simplicidade, o exemplo a seguir apenas inverte a ordem em que os usuários são renderizados.

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

Próximos passos

Neste artigo, você aprendeu como:

  • Identificar corretamente os casos de uso para escolher uma ID bruta
  • Converter entre Raw ID e diferentes tipos de um CommunicationIdentifier

Para saber mais, explore os seguintes guias de início rápido: