Grundlegendes zu Bezeichnertypen

Microsoft Teams-Benutzer

Die MicrosoftTeamsUserIdentifier-Schnittstelle stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem Microsoft Entra-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

// get the Teams user's ID from Graph APIs if only the email is known
const user = await graphClient.api("/users/bob@contoso.com").get();

// create an identifier
const teamsUser = { microsoftTeamsUserId: user.id };

// if you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsUser = { microsoftTeamsUserId: userId, cloud: "gcch" };

API-Referenz

Telefonnummer

Die PhoneNumberIdentifier-Schnittstelle stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

// create an identifier
const phoneNumber = { phoneNumber: "+112345556789" };

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

// Get the Microsoft Teams App's ID from Graph APIs
const users = await graphClient.api("/users")
                    .filter(filterConditions)
                    .select('displayName,id')
                    .get();
//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
const bot = getBotFromUsers(users);
// Create an identifier
const teamsAppIdentifier = { teamsAppId: bot.id };

// If you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsAppIdentifier = { teamsAppId: id, cloud: "gcch" };

API-Referenz

Unbekannt

Die UnknownIdentifier-Schnittstelle wurde aus Gründen der Zukunftssicherheit implementiert, und sie begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

// create an identifier
const unknownId = { id: "a raw id that originated in the service" };

API-Referenz

Behandeln der `CommunicationIdentifier`-Basisschnittstelle

Während Sie Bezeichner für einen konkreten Typ erstellen, den Sie an das SDK übergeben, gibt das SDK eine CommunicationIdentifierKind zurück, bei der es sich um eine Unterscheidungs-Union handelt. Diese kann einfach auf einen konkreten Typ eingegrenzt werden, und wir empfehlen die Verwendung einer Switch-Case-Anweisung mit Musterabgleich:

switch (communicationIdentifier.kind)
{
    case "communicationUser":
        // TypeScript has narrowed communicationIdentifier to be a CommunicationUserKind
        console.log(`Communication user: ${communicationIdentifier.communicationUserId}`);
        break;
    case "microsoftTeamsUser":
        // narrowed to MicrosoftTeamsUserKind
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUserId}`);
        break;
    case "phoneNumber":
         // narrowed to PhoneNumberKind
        console.log(`Phone number: ${communicationIdentifier.phoneNumber}`);
        break;
    case "unknown":
         // narrowed to UnknownIdentifierKind
        console.log(`Unknown: ${communicationIdentifier.id}`);
        break;
    case "microsoftBot":
        // narrowed to MicrosoftBotIdentifier
        console.log(`Microsoft bot: ${communicationIdentifier.botId}`);
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Die Bezeichnerschnittstellen wurden so ausgelegt, dass Sie kind nicht angeben müssen, um die Ausführlichkeit zu verringern, und die Unterscheidungs-Union mit der Eigenschaft kind wird nur bei Rückgaben aus dem SDK verwendet. Wenn Sie jedoch feststellen, dass Sie einen Bezeichner in den entsprechenden Unterscheidungs-Union-Typ übersetzen müssen, können Sie dieses Hilfsmittel verwenden:

const identifierKind = getIdentifierKind(identifier); // now you can switch-case on the kind

Unformatierte ID-Darstellung

Manchmal müssen Sie einen Bezeichner in eine flache Zeichenfolge serialisieren. Beispielsweise, wenn Sie den Bezeichner in einer Datenbanktabelle speichern oder ihn als URL-Parameter verwenden möchten.

Zu diesem Zweck gibt es für Bezeichner eine andere Darstellung, die als RawId bezeichnet wird. Ein Bezeichner kann immer in seine entsprechende unformatierte ID übersetzt werden, und eine gültige unformatierte ID kann immer in einen Bezeichner konvertiert werden.

Von Version azure-communication-common@2.1.0 an hilft das SDK bei der Konvertierung:

// get an identifier's raw Id
const rawId = getIdentifierRawId(communicationIdentifier);

// create an identifier from a given raw Id
const identifier = createIdentifierFromRawId(rawId);

Eine ungültige unformatierte ID wird im SDK nur in einen UnknownIdentifier konvertiert, und jegliche Überprüfung erfolgt nur dienstseitig.

Kommunikationsbenutzer

Das CommunicationUserIdentifier stellt eine Benutzeridentität dar, die mithilfe des Identity SDK oder der REST-API erstellt wurde. Es ist der einzige genutzte Bezeichner, wenn Ihre Anwendung keine Microsoft Teams-Features für Interoperabilität oder Telefonie verwendet.

Grundlegende Verwendung

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = await identityClient.CreateUser();

// and then send newUser.Id down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

API-Referenz

Microsoft Teams-Benutzer

MicrosoftTeamsUserIdentifier stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem Microsoft Entra-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

// get the Teams user's ID from Graph APIs if only the email is known
var user = await graphClient.Users["bob@contoso.com"]
    .Request()
    .GetAsync();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.Id);

// if you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch);

API-Referenz

Telefonnummer

Das PhoneNumberIdentifier stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

// Get the Microsoft Teams App's ID from Graph APIs
var users = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
	requestConfiguration.QueryParameters.Filter = filterConditions;
});

// Here we assume that you have a function GetBotFromUsers that gets the bot from the returned response
var bot = GetBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id, CommunicationCloudEnvironment.Gcch);

API-Referenz

Unbekannt

Der UnknownIdentifier wurde aus Gründen der Zukunftssicherheit implementiert, und er begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

API-Referenz

Behandeln der `CommunicationIdentifier`-Basisklasse

Während Sie Bezeichner für einen konkreten Typ erstellen, den Sie an das SDK übergeben, gibt das SDK das CommunicationIdentifier-Protokoll zurück. Dieses kann einfach auf einen konkreten Typ herabgewandelt werden, und wir empfehlen die Verwendung einer Switch-Case-Anweisung mit Musterabgleich:

switch (communicationIdentifier)
{
    case CommunicationUserIdentifier communicationUser:
        Console.WriteLine($"Communication user: {communicationUser.Id}");
        break;
    case MicrosoftTeamsUserIdentifier teamsUser:
        Console.WriteLine($"Teams user: {teamsUser.UserId}");
        break;
    case PhoneNumberIdentifier phoneNumber:
        Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}");
        break;
    case MicrosoftBotIdentifier bot:
        Console.WriteLine($"Microsoft bot: {bot.BotId}");
        break;
    case UnknownIdentifier unknown:
        Console.WriteLine($"Unknown: {unknown.Id}");
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Unformatierte ID-Darstellung

Manchmal müssen Sie einen Bezeichner in eine flache Zeichenfolge serialisieren. Beispielsweise, wenn Sie den Bezeichner in einer Datenbanktabelle speichern oder ihn als URL-Parameter verwenden möchten.

Zu diesem Zweck gibt es für Bezeichner eine andere Darstellung, die als RawId bezeichnet wird. Ein Bezeichner kann immer in seine entsprechende unformatierte ID übersetzt werden, und eine gültige unformatierte ID kann immer in einen Bezeichner konvertiert werden.

Von Version Azure.Communication.Common 1.2.0 an hilft das SDK bei der Konvertierung:

// get an identifier's raw Id
string rawId = communicationIdentifier.RawId;

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.FromRawId(rawId);

Eine ungültige unformatierte ID wird im SDK nur in einen UnknownIdentifier konvertiert, und jegliche Überprüfung erfolgt nur dienstseitig.

Kommunikationsbenutzer

Das CommunicationUserIdentifier stellt eine Benutzeridentität dar, die mithilfe des Identity SDK oder der REST-API erstellt wurde. Es ist der einzige genutzte Bezeichner, wenn Ihre Anwendung keine Microsoft Teams-Features für Interoperabilität oder Telefonie verwendet.

Grundlegende Verwendung

# at some point you will have created a new user identity in your trusted service
new_user = identity_client.create_user()

# and then send new_user.properties['id'] down to your client application
# where you can again create an identifier for the user
same_user = CommunicationUserIdentifier(new_user_id)

API-Referenz

Microsoft Teams-Benutzer

MicrosoftTeamsUserIdentifier stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem Microsoft Entra-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

# get the Teams user's ID from Graph APIs if only the email is known
user_id = graph_client.get("/users/bob@contoso.com").json().get("id");

# create an identifier
teams_user = MicrosoftTeamsUserIdentifier(user_id)

# if you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_user = MicrosoftTeamsUserIdentifier(user_id, cloud=CommunicationCloudEnvironment.GCCH)

API-Referenz

Telefonnummer

Das PhoneNumberIdentifier stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

# create an identifier
phone_number = PhoneNumberIdentifier("+112345556789")

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

# Get the Microsoft Teams App's ID from Graph APIs
users = graph_client.get("/users").json()

# Here we assume that you have a function get_bot_from_users that gets the bot from the returned response
bot = get_bot_from_users(users);

# Create an identifier
teams_app_identifier = MicrosoftTeamsAppIdentifier(app_id=bot.get("id"))

# If you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_app_identifier = MicrosoftTeamsAppIdentifier(
            app_id=bot.get("id"),
            cloud=CommunicationCloudEnvironment.GCCH
        )

API-Referenz

Unbekannt

Der UnknownIdentifier wurde aus Gründen der Zukunftssicherheit implementiert, und er begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

# create an identifier
unknown = UnknownIdentifier("a raw id that originated in the service")

API-Referenz

Behandeln der `CommunicationIdentifier`-Basisklasse

Während Sie Bezeichner für einen konkreten Typ erstellen, den Sie an das SDK übergeben, gibt das SDK das CommunicationIdentifier-Protokoll zurück. Konkrete Bezeichnerklassen sind lediglich das CommunicationIdentifier-Protokoll zusammen mit einem typisierten Wörterbuch mit dem Namen properties. Daher können Sie Musterabgleich auf die Instanzvariable kind des Protokolls anwenden, um in den konkreten Typ zu übersetzen:

match communication_identifier.kind:
    case CommunicationIdentifierKind.COMMUNICATION_USER:
        print(f"Communication user: {communication_identifier.properties['id']}")
    case CommunicationIdentifierKind.MICROSOFT_TEAMS_USER:
        print(f"Teams user: {communication_identifier.properties['user_id']}")
    case CommunicationIdentifierKind.PHONE_NUMBER:
        print(f"Phone number: {communication_identifier.properties['value']}")
    case CommunicationIdentifierKind.MICROSOFT_BOT:
        print(f"Microsoft bot: {communication_identifier.properties['bot_id']}")
    case CommunicationIdentifierKind.UNKNOWN:
        print(f"Unknown: {communication_identifier.raw_id}")
    case _:
        # be careful here whether you want to throw because a new SDK version
        # can introduce new identifier types

Unformatierte ID-Darstellung

Manchmal müssen Sie einen Bezeichner in eine flache Zeichenfolge serialisieren. Beispielsweise, wenn Sie den Bezeichner in einer Datenbanktabelle speichern oder ihn als URL-Parameter verwenden möchten.

Zu diesem Zweck gibt es für Bezeichner eine andere Darstellung, die als RawId bezeichnet wird. Ein Bezeichner kann immer in seine entsprechende unformatierte ID übersetzt werden, und eine gültige unformatierte ID kann immer in einen Bezeichner konvertiert werden.

Das SDK hilft bei der Konvertierung:

# get an identifier's raw Id
raw_id = communication_identifier.raw_id

# create an identifier from a given raw Id
identifier = identifier_from_raw_id(raw_id)

Eine ungültige unformatierte ID wird im SDK nur in einen UnknownIdentifier konvertiert, und jegliche Überprüfung erfolgt nur dienstseitig.

Kommunikationsbenutzer

Das CommunicationUserIdentifier stellt eine Benutzeridentität dar, die mithilfe des Identity SDK oder der REST-API erstellt wurde. Es ist der einzige genutzte Bezeichner, wenn Ihre Anwendung keine Microsoft Teams-Features für Interoperabilität oder Telefonie verwendet.

Grundlegende Verwendung

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

API-Referenz

Microsoft Teams-Benutzer

MicrosoftTeamsUserIdentifier stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem Microsoft Entra-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

API-Referenz

Telefonnummer

Das PhoneNumberIdentifier stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

// Get the Microsoft Teams App's ID from Graph APIs
var user = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
var bot = getBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

API-Referenz

Unbekannt

Der UnknownIdentifier wurde aus Gründen der Zukunftssicherheit implementiert, und er begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

API-Referenz

Behandeln der `CommunicationIdentifier`-Basisklasse

Während Sie Bezeichner für einen konkreten Typ erstellen, den Sie an das SDK übergeben, gibt das SDK den abstrakten CommunicationIdentifier zurück. Sie können ihn in einen konkreten Typ herabwandeln:

if (communicationIdentifier instanceof CommunicationUserIdentifier) {
    System.out.println("Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
    System.out.println("Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    System.out.println("Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof MicrosoftBotIdentifier) {
    Log.i(tag, "Microsoft bot: " + ((MicrosoftBotIdentifier)communicationIdentifier).getBotId());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    System.out.println("Unkown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
}

Unformatierte ID-Darstellung

Manchmal müssen Sie einen Bezeichner in eine flache Zeichenfolge serialisieren. Beispielsweise, wenn Sie den Bezeichner in einer Datenbanktabelle speichern oder ihn als URL-Parameter verwenden möchten.

Zu diesem Zweck gibt es für Bezeichner eine andere Darstellung, die als RawId bezeichnet wird. Ein Bezeichner kann immer in seine entsprechende unformatierte ID übersetzt werden, und eine gültige unformatierte ID kann immer in einen Bezeichner konvertiert werden.

Von Version azure-communication-common 1.2.0 an hilft das SDK bei der Konvertierung:

// get an identifier's raw Id
String rawId = communicationIdentifier.getRawId();

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);

Eine ungültige unformatierte ID wird im SDK nur in einen UnknownIdentifier konvertiert, und jegliche Überprüfung erfolgt nur dienstseitig.

Kommunikationsbenutzer

Das CommunicationUserIdentifier stellt eine Benutzeridentität dar, die mithilfe des Identity SDK oder der REST-API erstellt wurde. Es ist der einzige genutzte Bezeichner, wenn Ihre Anwendung keine Microsoft Teams-Features für Interoperabilität oder Telefonie verwendet.

Grundlegende Verwendung

// at some point you will have created a new user identity in your trusted service
// and send the new user id down to your client application
// where you can create an identifier for the user
let user = CommunicationUserIdentifier(newUserId)

API-Referenz

Microsoft Teams-Benutzer

MicrosoftTeamsUserIdentifier stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem ID-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

// get the Teams user's ID if only the email is known, assuming a helper method for the Graph API
let userId = await getUserIdFromGraph("bob@contoso.com")

// create an identifier
let teamsUser = MicrosoftTeamsUserIdentifier(userId: userId)

// if you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsUser = MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch)

API-Referenz

Telefonnummer

Das PhoneNumberIdentifier stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

// create an identifier
let phoneNumber = PhoneNumberIdentifier(phoneNumber: "+112345556789")

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

// Get the Microsoft Teams App's ID from Graph APIs, assuming a helper method for the Graph API
let botId = await getBotIdFromGraph()

// Create an identifier
let teamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId)

// If you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId, cloudEnvironment: CommunicationCloudEnvironment.Gcch)

API-Referenz

Unbekannt

Der UnknownIdentifier wurde aus Gründen der Zukunftssicherheit implementiert, und er begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

// create an identifier
let unknown = UnknownIdentifier("a raw id that originated in the service")

API-Referenz

Behandeln des `CommunicationIdentifier`-Basisprotokolls

Während Sie Bezeichner für einen konkreten Typ erstellen, den Sie an das SDK übergeben, gibt das SDK das CommunicationIdentifier-Protokoll zurück. Dieses kann einfach wieder zu einem konkreten Typ herabgewandelt werden, und wir empfehlen die Verwendung einer Switch-Case-Anweisung mit Musterabgleich:

switch (communicationIdentifier)
{
    case let communicationUser as CommunicationUserIdentifier:
        print(#"Communication user: \(communicationUser.id)"#)
    case let teamsUser as MicrosoftTeamsUserIdentifier:
        print(#"Teams user: \(teamsUser.UserId)"#)
    case let phoneNumber as PhoneNumberIdentifier:
        print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
    case let bot as MicrosoftBotIdentifier:
        print(#"Microsoft bot: \(bot.botId)"#)
    case let unknown as UnknownIdentifier:
        print(#"Unknown: \(unknown.Id)"#)
    @unknown default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Unformatierte ID-Darstellung

Manchmal müssen Sie einen Bezeichner in eine flache Zeichenfolge serialisieren. Beispielsweise, wenn Sie den Bezeichner in einer Datenbanktabelle speichern oder ihn als URL-Parameter verwenden möchten.

Zu diesem Zweck gibt es für Bezeichner eine andere Darstellung, die als RawId bezeichnet wird. Ein Bezeichner kann immer in seine entsprechende unformatierte ID übersetzt werden, und eine gültige unformatierte ID kann immer in einen Bezeichner konvertiert werden.

Von Version Azure.Communication.Common 1.1.0 an hilft das SDK bei der Konvertierung:

Swift

// get an identifier's raw Id
let rawId = communicationIdentifier.rawId;

// create an identifier from a given raw Id
let identifier = createCommunicationIdentifier(fromRawId: rawId);

Eine ungültige unformatierte ID wird im SDK nur in einen UnknownIdentifier konvertiert, und jegliche Überprüfung erfolgt nur dienstseitig.

Kommunikationsbenutzer

Das CommunicationUserIdentifier stellt eine Benutzeridentität dar, die mithilfe des Identity SDK oder der REST-API erstellt wurde. Es ist der einzige genutzte Bezeichner, wenn Ihre Anwendung keine Microsoft Teams-Features für Interoperabilität oder Telefonie verwendet.

Grundlegende Verwendung

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
CommunicationUserIdentifier sameUser = new CommunicationUserIdentifier(newUserId);

API-Referenz

Microsoft Teams-Benutzer

MicrosoftTeamsUserIdentifier stellt einen Teams-Benutzer mit seiner Microsoft Entra-Benutzerobjekt-ID dar. Sie können die Microsoft Entra-Benutzerobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen. Alternativ können Sie die ID als oid-Anspruch in einem ID-Token oder Microsoft Entra-Zugriffstoken finden, nachdem sich Ihr Benutzer angemeldet und ein Token erworben hat.

Grundlegende Verwendung

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
MicrosoftTeamsUserIdentifier gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

API-Referenz

Telefonnummer

Das PhoneNumberIdentifier stellt eine Telefonnummer dar. Der Dienst geht davon aus, dass Telefonnummern im E.164-Format vorliegen.

Grundlegende Verwendung

// create an identifier
PhoneNumberIdentifier phoneNumber = new PhoneNumberIdentifier("+112345556789");

API-Referenz

Microsoft Teams-Anwendung

Die MicrosoftTeamsAppIdentifier-Schnittstelle stellt einen Bot der Teams-Voice-Anwendungen wie Anrufwarteschleife und automatische Telefonzentrale mit seiner Microsoft Entra-Botobjekt-ID dar. Die Teams-Anwendungen müssen mit einem Ressourcenkonto konfiguriert werden. Sie können die Microsoft Entra-Botobjekt-ID über den Endpunkt Microsoft Graph-REST-API /users aus der Eigenschaft id in der Antwort abrufen. Weitere Informationen zum Arbeiten mit Microsoft Graph finden Sie im Graph-Explorer. Außerdem sollten Sie sich das Graph SDK ansehen.

Grundlegende Verwendung

// Get the Microsoft Teams App's ID from Graph APIs
UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
User bot = getBotFromUsers(users);

// Create an identifier
MicrosoftTeamsAppIdentifier teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

API-Referenz

Unbekannt

Der UnknownIdentifier wurde aus Gründen der Zukunftssicherheit implementiert, und er begegnet Ihnen möglicherweise, wenn Sie eine alte Version des SDK nutzen und kürzlich ein neuer Bezeichnertyp eingeführt wurde. Alle unbekannten Bezeichner aus dem Dienst werden im SDK in den UnknownIdentifier deserialisiert.

Grundlegende Verwendung

// create an identifier
UnknownIdentifier unknown = new UnknownIdentifier("a raw id that originated in the service");

API-Referenz