Communication SDK의 문자열 식별자에 대한 사용 사례

아티클
02/23/2024

이 문서에서는 문자열(원시 ID)을 Azure Communication Services SDK의 CommunicationIdentifier 형식 표현으로 선택하는 사용 사례를 제공합니다. 이 지침을 따르면 CommunicationIdentifier 파생 형식을 통해 원시 ID를 선택할 수 있는 몇 가지 사용 사례를 이해하는 데 도움이 됩니다.

식별자 선택에 대한 사용 사례

통신 시나리오를 구현할 경우의 일반적인 작업은 대화 참가자를 식별하는 것입니다. Communication Services SDK를 사용하는 경우 CommunicationIdentifier는 이러한 참가자를 고유하게 식별하는 기능을 제공합니다.

CommunicationIdentifier는 다음과 같은 이점을 제공합니다.

IDE에서 적절한 자동 완성 기능을 제공합니다.
형식별 전환 사례를 사용하여 다양한 애플리케이션 흐름을 처리할 수 있습니다.
통신을 특정 형식으로 제한할 수 있습니다.
식별자 세부 정보에 대한 액세스를 허용하고 이러한 정보를 사용하여 다른 API(예: Microsoft Graph API)를 호출함으로써 커뮤니케이션 참가자에게 풍부한 환경을 제공합니다.

또한 CommunicationIdentifier 및 파생 형식(MicrosoftTeamsUserIdentifier, PhoneNumberIdentifier 등)을 문자열 표현(원시 ID)으로 변환하고 문자열에서 복원할 수 있으므로 다음 시나리오를 보다 쉽게 구현할 수 있습니다.

데이터베이스에 식별자를 저장하고 키로 사용합니다.
식별자를 사전에서 키로 사용합니다.
POST 페이로드를 사용하는 대신 식별자를 REST API 경로에서 키로 사용하여 직관적인 REST CRUD API를 구현합니다.
불필요한 다시 렌더링을 방지하기 위해 React 같은 선언적 UI 프레임워크에서 식별자를 키로 사용합니다.

CommunicationIdentifier 만들기 및 원시 ID 검색

CommunicationIdentifier는 원시 ID에서 만들 수 있으며 CommunicationIdentifier에서 파생된 형식에서 원시 ID를 검색할 수 있습니다. 특정 개체 속성만 사용하고 다른 속성은 생략할 수 있는 사용자 지정 serialization 메서드의 필요성이 해소됩니다. 예를 들어 MicrosoftTeamsUserIdentifier에는 플랫폼에 따라 이러한 값을 검색하는 IsAnonymous 또는 Cloud 메서드와 같은 여러 속성이 있습니다. Communication Identity SDK에서 제공하는 메서드를 사용하면 더 많은 속성이 추가되더라도 식별자를 직렬화하는 방식이 정규화되고 일관되게 유지됩니다.

다음과 같이 CommunicationUserIdentifier에서 원시 ID를 가져옵니다.

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

원시 ID에서 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 Communication Services 사용자를 Contoso 사용자 데이터베이스 또는 ID 공급자의 사용자에게 매핑하는 것입니다. 이 작업은 일반적으로 Contoso 사용자 DB 또는 ID 공급자에 추가 열 또는 필드를 추가하여 수행됩니다. 그러나 원시 ID의 특성(안정적이고 전역적으로 고유하며 결정적)을 고려할 때 사용자 스토리지의 기본 키로 선택할 수도 있습니다.

ContosoUser가 애플리케이션의 사용자를 나타내는 클래스이며 해당 CommunicationIdentifier와 함께 데이터베이스에 저장하려 한다고 가정합니다. CommunicationIdentifier의 원래 값은 통신 ID, 통화 또는 채팅 API에서 제공되거나 사용자 지정 Contoso API에서 가져올 수 있지만 기본 형식에 관계없이 프로그래밍 언어에서 string 데이터 형식으로 나타낼 수 있습니다.

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

CommunicationId의 RawId 속성에 액세스하여 데이터베이스에 저장할 수 있는 문자열을 가져올 수 있습니다.

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

저장된 원시 ID에서 CommunicationIdentifier를 가져오려면 원시 문자열을 FromRawId() 메서드에 전달해야 합니다.

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

식별자 형식에 따라 CommunicationUserIdentifier, PhoneNumberIdentifier, MicrosoftTeamsUserIdentifier 또는 UnknownIdentifier를 반환합니다.

컬렉션에 CommunicationIdentifier 저장

시나리오에서 메모리의 여러 CommunicationIdentifier 개체를 사용해야 하는 경우 컬렉션(사전, 목록, 해시 집합 등)에 저장하려고 할 수 있습니다. 컬렉션은 예를 들어 통화 또는 채팅 참가자 목록을 유지 관리하는 데 유용합니다. 해시 논리는 원시 ID의 값을 사용하므로 요소가 신뢰할 수 있는 해시 동작을 유지해야 하는 컬렉션에서 CommunicationIdentifier를 사용할 수 있습니다. 다음 예제에서는 CommunicationIdentifier 개체를 다양한 유형의 컬렉션에 추가하고 원시 ID 값에서 새 식별자를 인스턴스화하여 컬렉션에 포함되어 있는지 확인하는 방법을 보여 줍니다.

다음 예제에서는 원시 ID를 사전의 키로 사용하여 사용자의 메시지를 저장하는 방법을 보여 줍니다.

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

해시 논리는 원시 ID의 값을 사용하므로 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")];
}

원시 ID의 값을 사용하는 해시 논리를 사용하면 해시 집합에 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"))){
        //...
     }
}

또 다른 사용 사례는 모바일 애플리케이션에서 원시 ID를 사용하여 참가자를 식별하는 것입니다. Azure Communication Services에 전송하지 않고 이 정보를 UI 라이브러리에서 로컬로 처리하려는 경우 원격 참가자에 대한 참가자 뷰 데이터를 삽입할 수 있습니다. 이 뷰 데이터는 렌더링할 아바타를 나타내는 UIImage와 필요에 따라 대신 표시할 수 있는 표시 이름을 포함할 수 있습니다. 여기에서 검색된 참가자 CommunicationIdentifier와 원시 ID를 모두 사용하여 원격 참가자를 고유하게 식별할 수 있습니다.

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 경로에서 원시 ID를 키로 사용

REST API를 디자인할 때 CommunicationIdentifier 또는 원시 ID 문자열을 수락하는 엔드포인트가 있을 수 있습니다. 식별자가 여러 부분으로 구성된 경우(예: ObjectID, 클라우드 이름 등) MicrosoftTeamsUserIdentifier를 사용하고 있으면 요청 본문에 전달해야 할 수 있습니다. 그러나 원시 ID를 사용하면 전체 복합 개체를 본문에 JSON으로 전달하는 대신 URL 경로에서 엔터티의 주소를 지정할 수 있습니다. 따라서 보다 직관적인 REST CRUD API를 유지할 수 있습니다.

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

원시 ID에서 식별자 세부 정보 추출.

일관된 기본 원시 ID를 사용하면 다음을 수행할 수 있습니다.

올바른 식별자 형식(앱의 흐름을 조정할 수 있는 기준)으로 역직렬화.
식별자의 세부 정보(예: MicrosoftTeamsUserIdentifier의 oid) 추출.

이 예제에서는 두 가지 이점을 모두 보여 줍니다.

이 형식을 사용하면 아바타를 가져올 원본 위치를 결정할 수 있습니다.
분해된 세부 정보를 사용하면 올바른 방법으로 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;
    }
}

Contoso 데이터베이스에 문자열 형식(원시 ID)으로 저장된 특정 CommunicationIdentifier 형식의 속성 또는 메서드에 액세스할 수 있습니다.

UI 프레임워크에서 원시 ID를 키로 사용

식별자의 원시 ID를 UI 구성 요소의 키로 사용하여 특정 사용자를 추적하고 불필요한 다시 렌더링 및 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>;
});

다음 단계

이 문서에서는 다음 방법에 대해 알아보았습니다.

원시 ID를 선택하기 위한 사용 사례를 올바르게 식별
원시 ID와 다양한 형식의 CommunicationIdentifier 간에 변환

자세히 알아보려면 다음 빠른 시작 가이드를 살펴봅니다.

다음을 통해 공유