Användningsfall för strängidentifierare i Kommunikations-SDK:er

2025-04-17

Den här artikeln innehåller användningsfall för att välja en sträng (raw-ID) som en representationstyp av typen CommunicationIdentifier i Azure Communication Services SDK:er. Följ den här vägledningen för att förstå vissa användningsfall när du kanske vill välja ett raw-ID framför de Härledda typerna av CommunicationIdentifier.

Användningsfall för att välja en identifierare

En vanlig uppgift när du implementerar kommunikationsscenarier är att identifiera deltagare i konversationer. När du använder Communication Services SDK:er CommunicationIdentifier kan du unikt identifiera dessa deltagare.

Genom att använda CommunicationIdentifier får du följande fördelar:

Ger bra automatisk komplettering i IDE:er.
Möjliggör användning av ett växelläge beroende på typ för att hantera olika programflöden.
Gör det möjligt att begränsa kommunikationen till specifika typer.
Ger åtkomst till identifierarinformation och använder dem för att anropa andra API:er (till exempel Microsoft Graph API) för att ge kommunikationsdeltagarna en omfattande upplevelse.

Dessutom kan de härledda typerna CommunicationIdentifier och (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierosv.) konverteras till dess strängrepresentation (raw-ID) och återställas från strängen, vilket gör följande scenarier enklare att implementera:

Lagra identifierare i en databas och använd dem som nycklar.
Använd identifierare som nycklar i ordlistor.
Implementera intuitiva REST CRUD-API:er med hjälp av identifierare som nyckel i REST API-sökvägar, i stället för att behöva förlita sig på POST-nyttolaster.
Använd identifierare som nycklar i deklarativa gränssnittsramverk som React för att undvika onödig återgivning.

Skapa CommunicationIdentifier och hämta raw-ID

Du kan skapa CommunicationIdentifier från ett raw-ID. Du kan hämta ett raw-ID från en typ som härletts från CommunicationIdentifier. Det tar bort behovet av anpassade serialiseringsmetoder som kan ta in endast vissa objektegenskaper och utelämna andra. Till exempel MicrosoftTeamsUserIdentifier har flera egenskaper, till exempel IsAnonymous eller Cloud metoder för att hämta dessa värden (beroende på en plattform). Med hjälp av metoder som tillhandahålls av Communication Identity SDK garanterar att sättet att serialisera identifierare förblir kanoniskt och konsekvent även om fler egenskaper läggs till.

Hämta raw-ID från CommunicationUserIdentifier:

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

Instansiera CommunicationUserIdentifier från ett raw-ID:

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

Du hittar fler plattformsspecifika exempel i följande artikel: Förstå identifierartyper

Lagra CommunicationIdentifier i en databas

Ett av de vanliga jobb som kan krävas från dig är att mappa Azure Communication Services-användare till användare som kommer från Contosos användardatabas eller identitetsprovider. Du kan vanligtvis uppnå den här mappningen genom att lägga till en extra kolumn eller ett fält i Contoso-användardatabasen eller identitetsprovidern. Men med tanke på egenskaperna för raw-ID :t (stabilt, globalt unikt och deterministiskt) kanske du vill använda det som primärnyckel för användarlagringen.

Anta att en ContosoUser är en klass som representerar en användare av ditt program och du vill spara den tillsammans med en motsvarande CommunicationIdentifier till databasen. Det ursprungliga värdet för en CommunicationIdentifier kan komma från API:er för kommunikationsidentitet, samtal eller chatt eller från ett anpassat Contoso-API, men kan representeras som en string datatyp i programmeringsspråket oavsett vilken underliggande typ som är:

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

Du kan komma åt RawId egenskapen för CommunicationId för att hämta en sträng som kan lagras i databasen:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Om du vill hämta CommunicationIdentifier från det lagrade raw-ID:t måste du skicka råsträngen till FromRawId() metoden:

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

Den returnerar CommunicationUserIdentifier, PhoneNumberIdentifier, MicrosoftTeamsUserIdentifiereller UnknownIdentifier baserat på identifierartypen.

Lagra CommunicationIdentifier i samlingar

Om ditt scenario kräver att du arbetar med flera CommunicationIdentifier objekt i minnet kanske du vill lagra dem i en samling (ordlista, lista, hashuppsättning osv.). En samling är användbar, till exempel för att underhålla en lista över samtals- eller chattdeltagare. Eftersom hashningslogiken förlitar sig på värdet för ett raw-ID kan du använda CommunicationIdentifier i samlingar som kräver att element har ett tillförlitligt hashningsbeteende.

Följande exempel visar hur du lägger CommunicationIdentifier till objekt i olika typer av samlingar och kontrollerar om de finns i en samling genom att instansiera nya identifierare från ett raw-ID-värde.

I följande exempel visas hur du kan använda raw-ID:t som en nyckel i en ordlista för att lagra användarmeddelanden:

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

Eftersom hashningslogiken förlitar sig på värdet för ett raw-ID kan du använda CommunicationIdentifier sig själv som en nyckel i en ordlista direkt:

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

Med hashningslogik som förlitar sig på värdet för ett raw-ID kan du också lägga CommunicationIdentifier till objekt i hash-uppsättningar:

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

Ett annat användningsfall är att använda raw-ID:er i mobila program för att identifiera deltagare. Du kan mata in deltagarens visningsdata för fjärrdeltagare om du vill hantera den här informationen lokalt i användargränssnittsbiblioteket utan att skicka den till Azure Communication Services.

Dessa vydata kan innehålla en UIImage som representerar avataren som ska återges, och ett visningsnamn som kan visas i stället om så önskas.

Både deltagaren CommunicationIdentifier och Raw ID som hämtats från den kan användas för att unikt identifiera en fjärrdeltagare.

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

Använda raw-ID som nyckel i REST API-sökvägar

När du utformar ett REST-API kan du ha slutpunkter som antingen accepterar en CommunicationIdentifier eller en rå-ID-sträng. Om identifieraren består av flera delar (till exempel ObjectID, molnnamn osv. om du använder MicrosoftTeamsUserIdentifier) kan du behöva skicka den i begärandetexten. Om du använder raw-ID kan du dock adressera entiteten i URL-sökvägen i stället för att skicka hela det sammansatta objektet som en JSON i brödtexten. Så att du kan ha ett mer intuitivt 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();
}

Extrahera identifierarinformation från raw-ID:er.

Konsekvent underliggande Raw-ID möjliggör:

Deserialisera till rätt identifierartyp (baserat på vilken du kan justera flödet för din app).
Extrahera information om identifierare (till exempel en oid för MicrosoftTeamsUserIdentifier).

Exemplet visar båda fördelarna:

Med typen kan du bestämma var du ska ta avataren från.
Med den indelade informationen kan du fråga API:et på rätt sätt.

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

Du kan komma åt egenskaper eller metoder för en viss CommunicationIdentifier typ som lagras i en Contoso-databas i en form av en sträng (raw-ID).

Använda raw-ID:t som nyckel i användargränssnittsramverk

Du kan använda raw-ID:t för en identifierare som en nyckel i UI-komponenter för att spåra en viss användare och undvika onödig återgivning och API-anrop. I det här exemplet ändrar vi ordningen på hur användare återges i en lista. I verkligheten kanske vi vill visa nya användare först eller ändra ordning på användare baserat på något villkor (till exempel räcka upp handen). För enkelhetens skull ändrar följande exempel bara den ordning som användarna återges i.

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

Nästa steg

I den här artikeln beskrivs hur du:

Identifiera användningsfall för att välja ett raw-ID
Konvertera mellan raw-ID och olika typer av en CommunicationIdentifier