Варианты использования строковых идентификаторов в пакетах SDK для связи

Статья
10/26/2023

В этой статье приведены варианты использования для выбора строки (необработанного идентификатора) в качестве типа представления типа CommunicationIdentifier в Службы коммуникации Azure пакетах SDK. В этом руководстве описаны некоторые варианты использования, когда может потребоваться выбрать необработанный идентификатор для производных типов CommunicationIdentifier.

Варианты использования для выбора идентификатора

Обычной задачей при реализации сценариев обмена данными является определение участников бесед. При использовании пакетов SDK служб коммуникации CommunicationIdentifier предоставляет возможность уникальной идентификации этих участников.

CommunicationIdentifier имеет следующие преимущества:

Обеспечивает хорошую автоматическую завершение в idEs.
Позволяет использовать вариант коммутатора по типу для решения различных потоков приложений.
Позволяет ограничить обмен данными определенными типами.
Разрешите доступ к сведениям об идентификаторе и используйте их для вызова других API (таких как API Microsoft Graph), чтобы обеспечить широкий интерфейс взаимодействия для участников связи.

Поверх этого средство CommunicationIdentifier и производные типы (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierи т. д.) можно преобразовать в его строковое представление (необработанный идентификатор) и восстановить из строки, что упрощает реализацию следующих сценариев:

Храните идентификаторы в базе данных и используйте их в качестве ключей.
Используйте идентификаторы в качестве ключей в словарях.
Реализуйте интуитивно понятные API REST CRUD с помощью идентификаторов в качестве ключа в путях REST API вместо того, чтобы полагаться на полезные данные POST.
Используйте идентификаторы в качестве ключей в декларативных платформах пользовательского интерфейса, таких как React, чтобы избежать необходимости повторной отрисовки.

Создание Объекта CommunicationIdentifier и получение необработанного идентификатора

CommunicationIdentifier можно создать из необработанного идентификатора, а необработанный идентификатор можно получить из типа, производного от CommunicationIdentifier. Он удаляет необходимость любых пользовательских методов сериализации, которые могут принимать только определенные свойства объекта и опустить другие. Например, MicrosoftTeamsUserIdentifier имеет несколько свойств, таких как IsAnonymous или Cloud методы для получения этих значений (в зависимости от платформы). Использование методов, предоставляемых пакетом SDK для удостоверений связи, гарантирует, что способ сериализации идентификаторов будет оставаться каноническим и согласованным, даже если будут добавлены дополнительные свойства.

Получение необработанного идентификатора из CommunicationUserIdentifier:

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

Создайте экземпляр CommunicationUserIdentifier из необработанного идентификатора:

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

Дополнительные примеры для конкретной платформы см. в следующей статье. Общие сведения о типах идентификаторов

Хранение CommunicationIdentifier в базе данных

Одно из типичных заданий, которые могут потребоваться от вас, заключается в сопоставлении Службы коммуникации Azure пользователей с пользователями, поступающими из базы данных пользователя Contoso или поставщика удостоверений. Обычно это достигается путем добавления дополнительного столбца или поля в базу данных пользователя Contoso или поставщика удостоверений. Тем не менее, учитывая характеристики необработанного идентификатора (стабильный, глобально уникальный и детерминированный), вы также можете выбрать его в качестве первичного ключа для хранилища пользователей.

Предположим, что класс ContosoUser , представляющий пользователя приложения, и вы хотите сохранить его вместе с соответствующим CommunicationIdentifier в базе данных. Исходное значение может CommunicationIdentifier поступать из API удостоверений связи, вызовов или чатов или из пользовательского API Contoso, но может быть представлено как string тип данных на языке программирования независимо от того, какой базовый тип:

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

Чтобы получить строку, которую можно сохранить в базе данных, можно получить свойство RawId CommunicationId :

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Если вы хотите получить CommunicationIdentifier из сохраненного необработанного идентификатора, необходимо передать необработанную строку методу FromRawId() :

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

Он возвращает CommunicationUserIdentifierили PhoneNumberIdentifierMicrosoftTeamsUserIdentifier UnknownIdentifier зависит от типа идентификатора.

Хранение CommunicationIdentifier в коллекциях

Если сценарий требует работы с несколькими объектами CommunicationIdentifier в памяти, их может потребоваться сохранить в коллекции (словарь, список, хэш-набор и т. д.). Коллекция полезна, например для поддержания списка участников звонка или чата. Так как логика хэширования зависит от значения необработанного идентификатора, вы можете использовать CommunicationIdentifier в коллекциях, требующих наличия надежного хэширования элементов. В следующих примерах показано добавление объектов CommunicationIdentifier в различные типы коллекций и проверка, если они содержатся в коллекции путем создания экземпляров новых идентификаторов из значения необработанного идентификатора.

В следующем примере показано, как необработанный идентификатор можно использовать в качестве ключа в словаре для хранения сообщений пользователя:

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

Так как логика хэширования зависит от значения необработанного идентификатора, вы можете использовать CommunicationIdentifier себя в качестве ключа в словаре напрямую:

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

Логика хэширования, которая зависит от значения необработанного идентификатора, также позволяет добавлять CommunicationIdentifier объекты в хэш-наборы:

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"))){
        //...
     }
}

Другим вариантом использования является использование необработанных идентификаторов в мобильных приложениях для идентификации участников. Вы можете внедрить данные представления участников для удаленного участника, если вы хотите локально обрабатывать эти сведения в библиотеке пользовательского интерфейса, не отправляя его в Службы коммуникации Azure. Эти данные представления могут содержать uiImage, представляющий аватар для отрисовки, и отображаемое имя, которое они могут отображать вместо этого. И участник CommunicationIdentifier, и необработанный идентификатор, полученные из него, можно использовать для уникальной идентификации удаленного участника.

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

Использование необработанного идентификатора в качестве ключа в путях REST API

При разработке REST API можно использовать конечные точки, принимающие CommunicationIdentifier строку необработанного идентификатора или конечную точку. Если идентификатор состоит из нескольких частей (например, ObjectID, имя облака и т. д. MicrosoftTeamsUserIdentifier), может потребоваться передать его в текст запроса. Однако использование необработанного идентификатора позволяет обращаться к сущности в пути URL-адреса вместо передачи всего составного объекта в виде JSON в тексте. Таким образом, у вас может быть более интуитивно понятный API REST CRUD.

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

Извлечение сведений об идентификаторах из необработанных идентификаторов.

Согласованный базовый необработанный идентификатор позволяет:

Десериализация в нужный тип идентификатора (на основе которого можно настроить поток приложения).
Извлечение сведений об идентификаторах (например, oid for MicrosoftTeamsUserIdentifier).

В примере показаны оба преимущества:

Тип позволяет решить, откуда взять аватар.
Разложенные сведения позволяют запрашивать API правильно.

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

Вы можете получить доступ к свойствам или методам для определенного типа CommunicationIdentifier , хранящегося в базе данных Contoso в виде строки (необработанный идентификатор).

Использование необработанных идентификаторов в качестве ключа в платформах пользовательского интерфейса

Можно использовать необработанный идентификатор идентификатора в качестве ключа в компонентах пользовательского интерфейса для отслеживания определенного пользователя и предотвращения ненужных повторных отрисовок и вызовов API. В этом примере мы изменяем порядок отображения пользователей в списке. В реальном мире мы можем показать новых пользователей первым или повторно заказать пользователей на основе некоторых условий (например, поднятой рукой). Для простоты следующий пример просто изменяет порядок отрисовки пользователей.

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

Следующие шаги

Из этой статьи вы узнали, как выполнять следующие задачи:

Правильно определить варианты использования для выбора необработанного идентификатора
Преобразование между необработанным идентификатором и различными типами CommunicationIdentifier

Дополнительные сведения см. в следующих кратких руководствах.

Поделиться через