Compartilhar 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 bom preenchimento automático em IDEs.
  • Permite usar um caso de switch por tipo para endereçar 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 POST.
  • Use identificadores como chaves em estruturas de interface do usuário declarativas, como o React, para evitar rerenderização desnecessária.

Criando CommunicationIdentifier e recuperando ID Raw

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

Obtenha a ID bruta 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: Entender 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 do provedor de identidade da Contoso. Isso geralmente é obtido adicionando uma coluna ou campo extra no banco de dados do usuário da Contoso ou no Provedor de Identidade. No entanto, dadas as características do ID bruto (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á-la 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 Bate-papo 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 da ID bruta armazenada, será necessário passar a cadeia de caracteres bruta para FromRawId() o método:

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

Ele retornará CommunicationUserIdentifier, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier ou UnknownIdentifier com base no tipo de identificador.

Armazenando CommunicationIdentifier em coleções

Se o seu cenário exigir trabalhar com vários objetos CommunicationIdentifier na memória, convém armazená-los em uma coleção (dicionário, lista, conjunto de hash, etc.). Uma coleção é útil, por exemplo, para manter uma lista de participantes de chamadas ou bate-papos. 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 a ID bruta pode ser usada 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 aos 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 CommunicationIdentifier do participante quanto o ID bruto recuperado 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 em caminhos de API REST

Ao criar 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 da ID bruta permite que você aborde a entidade no caminho da URL em vez de passar todo o objeto composto como um JSON no corpo. Para que você 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.

A ID bruta 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 CommunicationIdentifier específico armazenado em um banco de dados da Contoso em uma forma de cadeia de caracteres (ID bruta).

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

É possível usar a ID bruta de um identificador como uma chave nos componentes da interface do usuário para rastrear um determinado usuário e evitar rerenderização desnecessária 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, levantada à mão). 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óximas etapas

Neste artigo, você aprendeu a:

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

Para saber mais, talvez você queira explorar os seguintes guias de início rápido: