Freigeben über

Anwendungsfälle für Zeichenfolgenbezeichner in Kommunikations-SDKs

  • Artikel

Dieser Artikel enthält Anwendungsfälle für die Auswahl einer Zeichenfolge (Raw ID) als Darstellungstyp des CommunicationIdentifier-Typs in Azure Communication Services SDKs. Anhand dieser Anleitung können Sie einige Anwendungsfälle verstehen, in denen Sie möglicherweise eine Roh-ID über die abgeleiteten CommunicationIdentifier-Typen auswählen möchten.

Anwendungsfälle für die Auswahl eines Bezeichners

Eine häufige Aufgabe bei der Implementierung von Kommunikationsszenarien besteht darin, Teilnehmer von Unterhaltungen zu identifizieren. Wenn Sie Kommunikationsdienste-SDKs verwenden, bietet CommunicationIdentifier die Möglichkeit, diese Teilnehmer eindeutig zu identifizieren.

CommunicationIdentifier hat die folgenden Vorteile:

  • Bietet eine gute AutoVervollständigen-Funktion in IDEs.
  • Ermöglicht die Verwendung eines Switch case by type to address different application flows.
  • Ermöglicht das Einschränken der Kommunikation auf bestimmte Typen.
  • Ermöglichen Sie den Zugriff auf Id-Details, und verwenden Sie sie, um andere APIs (z. B. die Microsoft Graph-API) aufzurufen, um eine umfassende Erfahrung für Kommunikationsteilnehmer bereitzustellen.

Darüber hinaus können CommunicationIdentifier und die abgeleiteten Typen (MicrosoftTeamsUserIdentifier, PhoneNumberIdentifierusw.) in ihre Zeichenfolgendarstellung (Raw ID) konvertiert und aus der Zeichenfolge wiederhergestellt werden, wodurch die folgenden Szenarien einfacher implementiert werden können:

  • Speichern Sie Bezeichner in einer Datenbank, und verwenden Sie sie als Schlüssel.
  • Verwenden Sie Bezeichner als Schlüssel in Wörterbüchern.
  • Implementieren Sie intuitive REST CRUD-APIs, indem Sie Bezeichner als Schlüssel in REST-API-Pfaden verwenden, anstatt sich auf POST-Nutzlasten verlassen zu müssen.
  • Verwenden Sie Bezeichner als Schlüssel in deklarativen UI-Frameworks wie React, um unnötiges Erneutes Rendern zu vermeiden.

Erstellen von CommunicationIdentifier und Abrufen der Roh-ID

CommunicationIdentifier kann aus einer Raw-ID erstellt werden, und eine Raw-ID kann aus einem von CommunicationIdentifier abgeleiteten Typ abgerufen werden. Es entfernt die Notwendigkeit von benutzerdefinierten Serialisierungsmethoden, die nur bestimmte Objekteigenschaften annehmen und andere weglassen können. Beispielsweise verfügt die MicrosoftTeamsUserIdentifier Eigenschaft über mehrere Eigenschaften, z IsAnonymous . B. oder Cloud Methoden zum Abrufen dieser Werte (je nach Plattform). Die Verwendung von Methoden, die vom Communication Identity SDK bereitgestellt werden, garantiert, dass die Art der Serialisierung von Bezeichnern kanonisch und konsistent bleibt, auch wenn weitere Eigenschaften hinzugefügt werden.

Roh-ID von CommunicationUserIdentifier abrufen:

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

Instanziieren Sie CommunicationUserIdentifier aus einer Roh-ID:

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

Weitere plattformspezifische Beispiele finden Sie im folgenden Artikel: Grundlegendes zu Bezeichnertypen

Speichern von CommunicationIdentifier in einer Datenbank

Eine der typischen Aufträge, die von Ihnen benötigt werden können, ist das Zuordnen von Azure Communication Services-Benutzern zu Benutzern, die aus der Contoso-Benutzerdatenbank oder dem Identitätsanbieter stammen. Dies wird in der Regel durch Hinzufügen einer zusätzlichen Spalte oder eines Zusätzlichen Felds in Contoso-Benutzer-DB oder Identitätsanbieter erreicht. Angesichts der Merkmale der Raw-ID (stabil, global eindeutig und deterministisch) können Sie sie jedoch auch als Primärschlüssel für den Benutzerspeicher auswählen.

Angenommen, eine ContosoUser Klasse, die einen Benutzer Ihrer Anwendung darstellt, und Sie möchten sie zusammen mit einem entsprechenden CommunicationIdentifier in der Datenbank speichern. Der ursprüngliche Wert für eine CommunicationIdentifier kann aus den Kommunikationsidentitäts-, Anruf- oder Chat-APIs oder aus einer benutzerdefinierten Contoso-API stammen, kann aber in Ihrer Programmiersprache unabhängig vom zugrunde liegenden Typ als string Datentyp dargestellt werden:

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

Sie können auf die Eigenschaft des CommunicationId Objekts zugreifenRawId, um eine Zeichenfolge abzurufen, die in der Datenbank gespeichert werden kann:

public void StoreToDatabase()
{
    CommunicationIdentifier communicationIdentifier;

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

Wenn Sie aus der gespeicherten Raw-ID abrufen CommunicationIdentifier möchten, müssen Sie die unformatierte Zeichenfolge an FromRawId() die Methode übergeben:

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

Sie gibt CommunicationUserIdentifier, PhoneNumberIdentifieroder MicrosoftTeamsUserIdentifier UnknownIdentifier basierend auf dem Bezeichnertyp zurück.

Speichern von CommunicationIdentifier in Sammlungen

Wenn In Ihrem Szenario mehrere CommunicationIdentifier-Objekte im Arbeitsspeicher verwendet werden müssen, können Sie sie in einer Sammlung (Wörterbuch, Liste, Hashsatz usw.) speichern. Eine Sammlung ist beispielsweise nützlich, um eine Liste von Anruf- oder Chatteilnehmern zu Standard enthalten. Da die Hashinglogik auf den Wert einer Roh-ID basiert, können Sie CommunicationIdentifier in Sammlungen verwenden, für die Elemente ein zuverlässiges Hashingverhalten erfordern. Die folgenden Beispiele veranschaulichen das Hinzufügen von CommunicationIdentifier-Objekten zu verschiedenen Auflistungstypen und überprüfen, ob sie in einer Auflistung enthalten sind, indem neue Bezeichner aus einem Raw-ID-Wert instanziiert werden.

Das folgende Beispiel zeigt, wie raw ID als Schlüssel in einem Wörterbuch zum Speichern von Benutzernachrichten verwendet werden kann:

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

Da die Hashinglogik auf den Wert einer Raw-ID basiert, können Sie sich selbst als Schlüssel in einem Wörterbuch direkt verwenden 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")];
}

Hashinglogik, die auf dem Wert einer Raw-ID basiert, ermöglicht ihnen auch das Hinzufügen CommunicationIdentifier von Objekten zu Hashsätzen:

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

Ein weiterer Anwendungsfall ist die Verwendung von Raw-IDs in mobilen Anwendungen, um Teilnehmer zu identifizieren. Sie können die Teilnehmeransichtsdaten für Remoteteilnehmer einfügen, wenn Sie diese Informationen lokal in der Benutzeroberflächenbibliothek verarbeiten möchten, ohne sie an Azure Communication Services zu senden. Diese Ansichtsdaten können ein UIImage enthalten, das den zu rendernden Avatar darstellt, und einen Anzeigenamen, den sie optional anzeigen können. Sowohl der Teilnehmer CommunicationIdentifier als auch die Roh-ID, die daraus abgerufen werden, können verwendet werden, um einen Remoteteilnehmer eindeutig zu identifizieren.

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

Verwenden der Roh-ID als Schlüssel in REST-API-Pfaden

Beim Entwerfen einer REST-API können Sie Endpunkte haben, die entweder eine CommunicationIdentifier oder eine Unformatierte ID-Zeichenfolge akzeptieren. Wenn der Bezeichner aus mehreren Teilen (z. B. ObjectID, Cloudname usw.) besteht, müssen Sie ihn möglicherweise im Anforderungstext MicrosoftTeamsUserIdentifierübergeben. Mithilfe der Raw-ID können Sie jedoch die Entität im URL-Pfad adressieren, anstatt das gesamte zusammengesetzte Objekt als JSON im Textkörper zu übergeben. Damit Sie eine intuitivere REST CRUD-API haben können.

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

Extrahieren von Id-Details aus unformatierten IDs.

Konsistente zugrunde liegende Raw-ID ermöglicht Folgendes:

  • Deserialisieren des richtigen Bezeichnertyps (basierend auf dem Sie den Fluss Ihrer App anpassen können).
  • Extrahieren von Details von Bezeichnern (z. B. ein Oid für MicrosoftTeamsUserIdentifier).

Das Beispiel zeigt beide Vorteile:

  • Mit dem Typ können Sie entscheiden, von wo der Avatar entfernt werden soll.
  • Mit den dekompilierten Details können Sie die API auf die richtige Weise abfragen.
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;
    }
}

Sie können auf Eigenschaften oder Methoden für einen bestimmten CommunicationIdentifier-Typ zugreifen, der in einer Contoso-Datenbank in form einer Zeichenfolge (Raw ID) gespeichert ist.

Verwenden von unformatierten IDs als Schlüssel in Benutzeroberflächenframeworks

Es ist möglich, die Roh-ID eines Bezeichners als Schlüssel in UI-Komponenten zu verwenden, um einen bestimmten Benutzer nachzuverfolgen und unnötige Erneutes Rendern und API-Aufrufe zu vermeiden. Im Beispiel ändern wir die Reihenfolge, in der Benutzer in einer Liste gerendert werden. In der realen Welt möchten wir möglicherweise neue Benutzer zuerst anzeigen oder benutzer basierend auf einer bestimmten Bedingung neu anordnen (z. B. Hand ausgelöst). Aus Gründen der Einfachheit kehrt das folgende Beispiel einfach die Reihenfolge um, in der die Benutzer gerendert werden.

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ächste Schritte

In diesem Artikel haben Sie Folgendes gelernt:

  • Richtige Identifizierung von Anwendungsfällen für die Auswahl einer Roh-ID
  • Konvertieren zwischen Roh-ID und verschiedenen Typen eines CommunicationIdentifier

Weitere Informationen finden Sie in den folgenden Schnellstartanleitungen: