Delen via

Use cases for string identifiers in Communication SDK's

  • Artikel

Dit artikel bevat use cases voor het kiezen van een tekenreeks (Raw ID) als een weergavetype van het Type CommunicationIdentifier in Azure Communication Services SDK's. Als u deze richtlijnen volgt, krijgt u inzicht in een aantal gebruiksvoorbeelden wanneer u mogelijk een Onbewerkte id wilt kiezen voor de afgeleide typen CommunicationIdentifier.

Gebruiksvoorbeelden voor het kiezen van een id

Een veelvoorkomende taak bij het implementeren van communicatiescenario's is het identificeren van deelnemers aan gesprekken. Wanneer u Communication Services-SDK's gebruikt, biedt CommunicationIdentifier de mogelijkheid om deze deelnemers uniek te identificeren.

CommunicationIdentifier heeft de volgende voordelen:

  • Biedt een goede automatische voltooiing in IDE's.
  • Hiermee staat u het gebruik van een switchcase per type toe om verschillende toepassingsstromen aan te pakken.
  • Hiermee kunt u de communicatie beperken tot specifieke typen.
  • Sta toegang tot id-gegevens toe en gebruik ze om andere API's (zoals de Microsoft Graph API) aan te roepen om een rijke ervaring te bieden voor communicatiedeelnemers.

Bovendien kunnen de CommunicationIdentifier en de afgeleide typen (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierenzovoort) worden geconverteerd naar de tekenreeksweergave (Raw ID) en worden hersteld vanuit de tekenreeks, waardoor de volgende scenario's eenvoudiger te implementeren zijn:

  • Sla id's op in een database en gebruik deze als sleutels.
  • Gebruik id's als sleutels in woordenlijsten.
  • Implementeer intuïtieve REST CRUD-API's met behulp van id's als sleutel in REST API-paden, in plaats van te vertrouwen op POST-nettoladingen.
  • Gebruik id's als sleutels in declaratieve UI-frameworks zoals React om onnodige re-rendering te voorkomen.

CommunicationIdentifier maken en onbewerkte id ophalen

CommunicationIdentifier kan worden gemaakt op basis van een onbewerkte id en een onbewerkte id kan worden opgehaald uit een type dat is afgeleid van CommunicationIdentifier. Het verwijdert de noodzaak van aangepaste serialisatiemethoden die alleen bepaalde objecteigenschappen kunnen overnemen en anderen weglaten. Het heeft bijvoorbeeld MicrosoftTeamsUserIdentifier meerdere eigenschappen, zoals IsAnonymous of Cloud methoden om deze waarden op te halen (afhankelijk van een platform). Het gebruik van methoden die worden geleverd door communication Identity SDK garandeert dat de manier van serialiseren van id's canoniek en consistent blijft, zelfs als er meer eigenschappen worden toegevoegd.

Onbewerkte id ophalen uit CommunicationUserIdentifier:

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

Instantiate CommunicationUserIdentifier van een onbewerkte id:

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

Meer platformspecifieke voorbeelden vindt u in het volgende artikel: Id-typen begrijpen

CommunicationIdentifier opslaan in een database

Een van de typische taken die u mogelijk nodig hebt, is het toewijzen van Azure Communication Services-gebruikers aan gebruikers die afkomstig zijn van de Contoso-gebruikersdatabase of -id-provider. Dit wordt meestal bereikt door een extra kolom of veld toe te voegen in Contoso-gebruikersdatabase of id-provider. Gezien de kenmerken van de Onbewerkte id (stabiel, wereldwijd uniek en deterministisch), kunt u deze echter ook kiezen als primaire sleutel voor de gebruikersopslag.

Ervan uitgaande dat een ContosoUser klasse een gebruiker van uw toepassing vertegenwoordigt en u deze samen met een bijbehorende CommunicationIdentifier wilt opslaan in de database. De oorspronkelijke waarde voor een CommunicationIdentifier kan afkomstig zijn van de communicatie-id, aanroepen of chat-API's of van een aangepaste Contoso-API, maar kan worden weergegeven als een string gegevenstype in uw programmeertaal, ongeacht het onderliggende type:

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

U hebt toegang tot RawId de eigenschap van de CommunicationId functie om een tekenreeks op te halen die kan worden opgeslagen in de database:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Als u de opgeslagen Onbewerkte id wilt ophalen CommunicationIdentifier , moet u de onbewerkte tekenreeks doorgeven aan FromRawId() de methode:

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

Het retourneertCommunicationUserIdentifier, MicrosoftTeamsUserIdentifier PhoneNumberIdentifierof UnknownIdentifier op basis van het id-type.

CommunicationIdentifier opslaan in verzamelingen

Als voor uw scenario meerdere CommunicationIdentifier-objecten in het geheugen moeten worden gebruikt, kunt u deze opslaan in een verzameling (woordenlijst, lijst, hashset, enzovoort). Een verzameling is bijvoorbeeld handig voor het onderhouden van een lijst met gespreks- of chatdeelnemers. Omdat de hash-logica afhankelijk is van de waarde van een onbewerkte id, kunt u CommunicationIdentifier gebruiken in verzamelingen waarvoor elementen een betrouwbaar hash-gedrag moeten hebben. In de volgende voorbeelden ziet u hoe u CommunicationIdentifier-objecten toevoegt aan verschillende typen verzamelingen en controleert of deze zich in een verzameling bevinden door nieuwe id's van een Raw ID-waarde te instantiëren.

In het volgende voorbeeld ziet u hoe raw-id kan worden gebruikt als sleutel in een woordenlijst om berichten van gebruikers op te slaan:

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

Aangezien de hash-logica afhankelijk is van de waarde van een Onbewerkte id, kunt u zichzelf als een sleutel in een woordenlijst rechtstreeks gebruiken 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")];
}

Met hashlogica die afhankelijk is van de waarde van een onbewerkte id, kunt u ook objecten toevoegen CommunicationIdentifier aan hashsets:

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

Een andere use-case is het gebruik van Raw-id's in mobiele toepassingen om deelnemers te identificeren. U kunt de gegevens van de deelnemer weergeven voor externe deelnemers injecteren als u deze informatie lokaal wilt verwerken in de UI-bibliotheek zonder deze naar Azure Communication Services te verzenden. Deze weergavegegevens kunnen een UIImage bevatten die de avatar vertegenwoordigt die moet worden weergegeven en een weergavenaam die ze eventueel kunnen weergeven. Zowel de communicationidentifier van de deelnemer als de onbewerkte id die eraan is opgehaald, kan worden gebruikt om een externe deelnemer uniek te identificeren.

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

Onbewerkte id gebruiken als sleutel in REST API-paden

Bij het ontwerpen van een REST API kunt u eindpunten hebben die een CommunicationIdentifier of een Raw ID-tekenreeks accepteren. Als de id bestaat uit verschillende onderdelen (zoals ObjectID, cloudnaam, enzovoort), MicrosoftTeamsUserIdentifiermoet u deze mogelijk doorgeven in de hoofdtekst van de aanvraag. Met raw-id kunt u echter de entiteit in het URL-pad adresseren in plaats van het hele samengestelde object door te geven als een JSON in de hoofdtekst. Zodat u een intuïtievere REST CRUD-API kunt hebben.

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-gegevens extraheren uit onbewerkte id's.

Consistente onderliggende onbewerkte id maakt het volgende mogelijk:

  • Deserialiseren naar het juiste id-type (op basis waarvan u de stroom van uw app kunt aanpassen).
  • Details van id's extraheren (zoals een oid voor MicrosoftTeamsUserIdentifier).

In het voorbeeld ziet u beide voordelen:

  • Met het type kunt u bepalen waar u de avatar vandaan wilt halen.
  • Met de uitgevouwen details kunt u op de juiste manier een query uitvoeren op de 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;
    }
}

U kunt toegang krijgen tot eigenschappen of methoden voor een specifiek CommunicationIdentifier-type dat is opgeslagen in een Contoso-database in een tekenreeks (Raw ID).

Onbewerkte id's gebruiken als sleutel in UI-frameworks

Het is mogelijk om onbewerkte id van een id als sleutel in UI-onderdelen te gebruiken om een bepaalde gebruiker bij te houden en onnodige re-rendering en API-aanroepen te voorkomen. In het voorbeeld wijzigen we de volgorde van de weergave van gebruikers in een lijst. In de praktijk willen we mogelijk nieuwe gebruikers eerst weergeven of gebruikers opnieuw orden op basis van een bepaalde voorwaarde (bijvoorbeeld met de hand opgevoed). Omwille van de eenvoud wordt in het volgende voorbeeld alleen de volgorde omgekeerd waarin de gebruikers worden weergegeven.

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

Volgende stappen

In dit artikel hebt u het volgende geleerd:

  • Gebruiksvoorbeelden voor het kiezen van een onbewerkte id correct identificeren
  • Converteren tussen onbewerkte id en verschillende typen communicationIdentifier

Voor meer informatie kunt u de volgende snelstartgidsen bekijken: