Dela via

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

  • Artikel

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. Genom att följa den här vägledningen får du hjälp 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 ger CommunicationIdentifier möjligheten att unikt identifiera dessa deltagare.

CommunicationIdentifier har följande fördelar:

  • Ger bra automatisk komplettering i IDE:er.
  • Tillåter användning av ett växelfall efter typ för att hantera olika programflöden.
  • Tillåter begränsning av kommunikation till specifika typer.
  • Tillåt åtkomst till identifierarinformation och använd dem för att anropa andra API:er (till exempel Microsoft Graph API) för att ge kommunikationsdeltagarna en omfattande upplevelse.

Dessutom kan CommunicationIdentifier och de härledda typerna (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

CommunicationIdentifier kan skapas från ett raw-ID och ett raw-ID kan hämtas från en typ som härletts från CommunicationIdentifier. Det tar bort behovet av anpassade serialiseringsmetoder som bara kan ta in 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. Detta uppnås vanligtvis genom att lägga till en extra kolumn eller ett extra fält i Contoso-användardatabasen eller identitetsprovidern. Men med tanke på egenskaperna för raw-ID :t (stabilt, globalt unikt och deterministiskt) kan du lika gärna välja 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, PhoneNumberIdentifierMicrosoftTeamsUserIdentifier eller UnknownIdentifier baserat på identifierartyp.

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 till CommunicationIdentifier-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 raw-ID kan användas som en nyckel i en ordlista för att lagra användarens meddelanden:

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 ett användargränssnitt som representerar avataren som ska återges och ett visningsnamn som de kan visa i stället. 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 tillåter:

  • 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 specifik CommunicationIdentifier-typ som lagras i en Contoso-databas i form av en sträng (raw-ID).

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

Det går att använda raw-ID för en identifierare som en nyckel i användargränssnittskomponenter för att spåra en viss användare och undvika onödig återgivning och API-anrop. I exemplet ändrar vi ordningen på hur användare återges i en lista. I verkligheten kanske vi vill visa nya användare först eller beställa om användare baserat på något villkor (till exempel handupphöjt). 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 lärde du dig att:

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

Om du vill veta mer kanske du vill utforska följande snabbstartsguider: