Opis typów identyfikatorów

Użytkownik aplikacji Microsoft Teams

Interfejs MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenieFirmy Microsoft Entra lub tokenie dostępu Firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Numer telefonu

Interfejs PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Nieznane

Interfejs UnknownIdentifier istnieje na potrzeby sprawdzania przyszłości i można go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Jak obsługiwać `CommunicationIdentifier` interfejs podstawowy

Podczas tworzenia identyfikatorów konkretnego typu przekazywanego do zestawu SDK zestaw SDK zwraca wartość , która jest związkiem CommunicationIdentifierKinddyskryminowanym. Łatwo jest zawęzić do konkretnego typu i sugerujemy instrukcję switch-case z dopasowaniem wzorca:

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

Interfejsy identyfikatorów zostały zaprojektowane tak, aby nie trzeba było określać kind w celu zmniejszenia szczegółowości, a dyskryminująca unia z właściwością kind jest używana tylko w przypadku powrotu z zestawu SDK. Jeśli jednak okaże się, że musisz przetłumaczyć identyfikator na odpowiadający mu typ unii dyskryminującej, możesz użyć tego pomocnika:

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

Nieprzetworzona reprezentacja identyfikatora

Czasami konieczne jest serializowanie identyfikatora do płaskiego ciągu. Jeśli na przykład chcesz przechowywać identyfikator w tabeli bazy danych lub jeśli chcesz użyć go jako parametru adresu URL.

W tym celu identyfikatory mają inną reprezentację o nazwie RawId. Identyfikator można zawsze przetłumaczyć na odpowiadający mu nieprzetworzony identyfikator, a prawidłowy nieprzetworzony identyfikator może być zawsze konwertowany na identyfikator.

Ponieważ azure-communication-common@2.1.0 zestaw SDK pomaga w konwersji:

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

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

Nieprawidłowy identyfikator pierwotny zostanie przekonwertowany tylko na element UnknownIdentifier w zestawie SDK, a każda walidacja odbywa się tylko po stronie usługi.

Użytkownik komunikacji

Reprezentuje CommunicationUserIdentifier tożsamość użytkownika, która została utworzona przy użyciu zestawu Identity SDK lub interfejsu API REST. Jest to jedyny identyfikator używany, jeśli aplikacja nie korzysta z funkcji współdziałania usługi Microsoft Teams ani telefonii.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Użytkownik aplikacji Microsoft Teams

Obiekt MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenieFirmy Microsoft Entra lub tokenie dostępu Firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Numer telefonu

Wartość PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Nieznane

Istnieje na UnknownIdentifier potrzeby sprawdzania przyszłości i możesz go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Jak obsługiwać klasę bazową `CommunicationIdentifier`

Podczas tworzenia identyfikatorów konkretnego typu przekazywanego do zestawu SDK zestaw SDK zwraca CommunicationIdentifier protokół. Łatwo jest rzutować w dół do konkretnego typu i sugerujemy instrukcję switch-case z dopasowaniem wzorca:

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

Nieprzetworzona reprezentacja identyfikatora

Czasami konieczne jest serializowanie identyfikatora do płaskiego ciągu. Jeśli na przykład chcesz przechowywać identyfikator w tabeli bazy danych lub jeśli chcesz użyć go jako parametru adresu URL.

W tym celu identyfikatory mają inną reprezentację o nazwie RawId. Identyfikator można zawsze przetłumaczyć na odpowiadający mu nieprzetworzony identyfikator, a prawidłowy nieprzetworzony identyfikator może być zawsze konwertowany na identyfikator.

Ponieważ Azure.Communication.Common 1.2.0 zestaw SDK pomaga w konwersji:

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

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

Nieprawidłowy identyfikator pierwotny zostanie przekonwertowany tylko na element UnknownIdentifier w zestawie SDK, a każda walidacja odbywa się tylko po stronie usługi.

Użytkownik komunikacji

Reprezentuje CommunicationUserIdentifier tożsamość użytkownika, która została utworzona przy użyciu zestawu Identity SDK lub interfejsu API REST. Jest to jedyny identyfikator używany, jeśli aplikacja nie korzysta z funkcji współdziałania usługi Microsoft Teams ani telefonii.

Podstawowy sposób użycia

# 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)

Odwołanie do interfejsu API

Użytkownik aplikacji Microsoft Teams

Obiekt MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenieFirmy Microsoft Entra lub tokenie dostępu Firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

# 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)

Odwołanie do interfejsu API

Numer telefonu

Wartość PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

# 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
        )

Odwołanie do interfejsu API

Nieznane

Istnieje na UnknownIdentifier potrzeby sprawdzania przyszłości i możesz go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Jak obsługiwać klasę bazową `CommunicationIdentifier`

Podczas tworzenia identyfikatorów konkretnego typu przekazywanego do zestawu SDK zestaw SDK zwraca CommunicationIdentifier protokół. Konkretne klasy identyfikatorów to tylko protokół CommunicationIdentifier wraz z typem słownika o nazwie properties. W związku z tym można użyć dopasowania wzorca w zmiennej kind wystąpienia protokołu, aby przetłumaczyć na konkretny typ:

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

Nieprzetworzona reprezentacja identyfikatora

Czasami konieczne jest serializowanie identyfikatora do płaskiego ciągu. Jeśli na przykład chcesz przechowywać identyfikator w tabeli bazy danych lub jeśli chcesz użyć go jako parametru adresu URL.

W tym celu identyfikatory mają inną reprezentację o nazwie RawId. Identyfikator można zawsze przetłumaczyć na odpowiadający mu nieprzetworzony identyfikator, a prawidłowy nieprzetworzony identyfikator może być zawsze konwertowany na identyfikator.

Zestaw SDK pomaga w konwersji:

# 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)

Nieprawidłowy identyfikator pierwotny zostanie przekonwertowany tylko na element UnknownIdentifier w zestawie SDK, a każda walidacja odbywa się tylko po stronie usługi.

Użytkownik komunikacji

Reprezentuje CommunicationUserIdentifier tożsamość użytkownika, która została utworzona przy użyciu zestawu Identity SDK lub interfejsu API REST. Jest to jedyny identyfikator używany, jeśli aplikacja nie korzysta z funkcji współdziałania usługi Microsoft Teams ani telefonii.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Użytkownik aplikacji Microsoft Teams

Obiekt MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenieFirmy Microsoft Entra lub tokenie dostępu Firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Numer telefonu

Wartość PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Nieznane

Istnieje na UnknownIdentifier potrzeby sprawdzania przyszłości i możesz go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Jak obsługiwać klasę bazową `CommunicationIdentifier`

Podczas tworzenia identyfikatorów konkretnego typu przekazywanego do zestawu SDK zestaw SDK zwraca abstrakcyjny CommunicationIdentifierelement . Można odlecieć z powrotem do konkretnego typu:

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
}

Nieprzetworzona reprezentacja identyfikatora

Czasami konieczne jest serializowanie identyfikatora do płaskiego ciągu. Jeśli na przykład chcesz przechowywać identyfikator w tabeli bazy danych lub jeśli chcesz użyć go jako parametru adresu URL.

W tym celu identyfikatory mają inną reprezentację o nazwie RawId. Identyfikator można zawsze przetłumaczyć na odpowiadający mu nieprzetworzony identyfikator, a prawidłowy nieprzetworzony identyfikator może być zawsze konwertowany na identyfikator.

Ponieważ azure-communication-common 1.2.0 zestaw SDK pomaga w konwersji:

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

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

Nieprawidłowy identyfikator pierwotny zostanie przekonwertowany tylko na element UnknownIdentifier w zestawie SDK, a każda walidacja odbywa się tylko po stronie usługi.

Użytkownik komunikacji

Reprezentuje CommunicationUserIdentifier tożsamość użytkownika, która została utworzona przy użyciu zestawu Identity SDK lub interfejsu API REST. Jest to jedyny identyfikator używany, jeśli aplikacja nie korzysta z funkcji współdziałania usługi Microsoft Teams ani telefonii.

Podstawowy sposób użycia

// 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)

Odwołanie do interfejsu API

Użytkownik aplikacji Microsoft Teams

Obiekt MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenie identyfikatora lub tokenie dostępu firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

// 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)

Odwołanie do interfejsu API

Numer telefonu

Wartość PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

// 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)

Odwołanie do interfejsu API

Nieznane

Istnieje na UnknownIdentifier potrzeby sprawdzania przyszłości i możesz go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Jak obsługiwać `CommunicationIdentifier` protokół podstawowy

Podczas tworzenia identyfikatorów konkretnego typu przekazywanego do zestawu SDK zestaw SDK zwraca CommunicationIdentifier protokół. Łatwo jest odlecieć z powrotem do konkretnego typu i sugerujemy instrukcję switch-case z dopasowaniem wzorca:

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

Nieprzetworzona reprezentacja identyfikatora

Czasami konieczne jest serializowanie identyfikatora do płaskiego ciągu. Jeśli na przykład chcesz przechowywać identyfikator w tabeli bazy danych lub jeśli chcesz użyć go jako parametru adresu URL.

W tym celu identyfikatory mają inną reprezentację o nazwie RawId. Identyfikator można zawsze przetłumaczyć na odpowiadający mu nieprzetworzony identyfikator, a prawidłowy nieprzetworzony identyfikator może być zawsze konwertowany na identyfikator.

Ponieważ Azure.Communication.Common 1.1.0 zestaw SDK pomaga w konwersji:

Swift

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

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

Nieprawidłowy identyfikator pierwotny zostanie przekonwertowany tylko na element UnknownIdentifier w zestawie SDK, a każda walidacja odbywa się tylko po stronie usługi.

Użytkownik komunikacji

Reprezentuje CommunicationUserIdentifier tożsamość użytkownika, która została utworzona przy użyciu zestawu Identity SDK lub interfejsu API REST. Jest to jedyny identyfikator używany, jeśli aplikacja nie korzysta z funkcji współdziałania usługi Microsoft Teams ani telefonii.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Użytkownik aplikacji Microsoft Teams

Obiekt MicrosoftTeamsUserIdentifier reprezentuje użytkownika usługi Teams z identyfikatorem obiektu użytkownika Entra firmy Microsoft. Identyfikator obiektu użytkownika Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK. Alternatywnie możesz znaleźć identyfikator jako oid oświadczenie w tokenie identyfikatora lub tokenie dostępu firmy Microsoft Entra po zalogowaniu się użytkownika i uzyskaniu tokenu.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Numer telefonu

Wartość PhoneNumberIdentifier reprezentuje numer telefonu. Usługa zakłada, że numery telefonów są sformatowane w formacie E.164.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Aplikacja Microsoft Teams

Interfejs MicrosoftTeamsAppIdentifier reprezentuje bota aplikacji Teams Voice, takich jak kolejka wywołań i automatyczna obsługa z identyfikatorem obiektu bota Entra firmy Microsoft. Aplikacje usługi Teams należy skonfigurować przy użyciu konta zasobu. Identyfikator obiektu bota Entra firmy Microsoft można pobrać za pośrednictwem punktu końcowego interfejsu API REST programu Microsoft Graph /users z id właściwości w odpowiedzi. Aby uzyskać więcej informacji na temat pracy z programem Microsoft Graph, wypróbuj Eksploratora programu Graph i zapoznaj się z zestawem GRAPH SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API

Nieznane

Istnieje na UnknownIdentifier potrzeby sprawdzania przyszłości i możesz go napotkać, gdy korzystasz ze starej wersji zestawu SDK, a niedawno wprowadzono nowy typ identyfikatora. Każdy nieznany identyfikator usługi zostanie zdeserializowany do UnknownIdentifier zestawu SDK.

Podstawowy sposób użycia

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

Odwołanie do interfejsu API