Поделиться через


Общие сведения о типах идентификаторов

Пакеты SDK служб коммуникации и ИНТЕРФЕЙСы REST API используют тип идентификатора, чтобы определить, кто взаимодействует с которым. Например, идентификаторы указывают, кто звонит или кто отправил сообщение чата.

В зависимости от контекста идентификаторы упаковываются с дополнительными свойствами, например в ChatParticipant пакете SDK чата или в RemoteParticipant пакете SDK для вызовов.

В этой статье вы узнаете о различных типах идентификаторов и о том, как они выглядят на разных языках программирования. Вы также получите советы по их использованию.

Тип CommunicationIdentifier

Существуют удостоверения пользователей, которые создаются самостоятельно, и существуют внешние удостоверения. Пользователи и номера телефонов Microsoft Teams — это внешние удостоверения, которые будут играть в сценариях взаимодействия. Каждый из этих типов удостоверений имеет соответствующий идентификатор, представляющий его. Идентификатор — это структурированный тип, который обеспечивает безопасность типов и хорошо работает с завершением кода редактора.

Пользователь связи

Интерфейс CommunicationUserIdentifier представляет удостоверение пользователя, созданное с помощью пакета SDK удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

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

// and then send newUser.communicationUserId down to your client application
// where you can again create an identifier for the user
const sameUser = { communicationUserId: newUserId };

Справочник по API

CommunicationUserIdentifier

Пользователь Microsoft Teams

Интерфейс MicrosoftTeamsUserIdentifier представляет пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере Microsoft Entra или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

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

MicrosoftTeamsUserIdentifier

Номер телефона

Интерфейс PhoneNumberIdentifier представляет номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

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

MicrosoftTeamsAppIdentifier

Неизвестно

Интерфейс UnknownIdentifier существует для дальнейшего проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового интерфейса

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает CommunicationIdentifierKindидентификатор, который является дискриминированным объединением. Это легко сузить до конкретного типа, и мы предлагаем оператор switch-case с сопоставлением шаблонов:

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 "microsoftTeamsApp":
        // narrowed to MicrosoftTeamsAppIdentifier
        console.log(`Teams app: ${communicationIdentifier.teamsAppId}`);
        break;
    case "phoneNumber":
         // narrowed to PhoneNumberKind
        console.log(`Phone number: ${communicationIdentifier.phoneNumber}`);
        break;
    case "unknown":
         // narrowed to UnknownIdentifierKind
        console.log(`Unknown: ${communicationIdentifier.id}`);
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Интерфейсы идентификаторов разработаны таким образом, чтобы вам не нужно было указывать kind для уменьшения детализации, а различающее объединение с kind свойством используется только при возврате из пакета SDK. Однако если вам нужно перевести идентификатор в соответствующий тип объединения дискриминации, можно использовать этот вспомогательный метод:

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

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Так как azure-communication-common@2.1.0 пакет SDK помогает с преобразованием:

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

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

Пользователь связи

Представляет CommunicationUserIdentifier удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

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

CommunicationUserIdentifier

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifier пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере Microsoft Entra или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

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

MicrosoftTeamsUserIdentifier

Номер телефона

Представляет PhoneNumberIdentifier номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

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

MicrosoftTeamsAppIdentifier

Неизвестно

Существует UnknownIdentifier для будущих проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового класса

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает CommunicationIdentifier протокол. Это легко привести к конкретному типу, и мы предлагаем оператор switch-case с сопоставлением шаблонов:

switch (communicationIdentifier)
{
    case CommunicationUserIdentifier communicationUser:
        Console.WriteLine($"Communication user: {communicationUser.Id}");
        break;
    case MicrosoftTeamsUserIdentifier teamsUser:
        Console.WriteLine($"Teams user: {teamsUser.UserId}");
        break;
    case MicrosoftTeamsAppIdentifier teamsApp:
        Console.WriteLine($"Teams app: {teamsApp.AppId}");
        break;
    case PhoneNumberIdentifier phoneNumber:
        Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}");
        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;
}

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Так как Azure.Communication.Common 1.2.0 пакет SDK помогает с преобразованием:

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

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

Пользователь связи

Представляет CommunicationUserIdentifier удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

# 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

CommunicationUserIdentifier

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifier пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере Microsoft Entra или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

# 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

MicrosoftTeamsUserIdentifier

Номер телефона

Представляет PhoneNumberIdentifier номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

# 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

MicrosoftTeamsAppIdentifier

Неизвестно

Существует UnknownIdentifier для будущих проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового класса

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает CommunicationIdentifier протокол. Конкретные классы идентификаторов — это только протокол CommunicationIdentifier вместе с типизированным словарем properties. Таким образом, можно использовать сопоставление шаблонов в переменной экземпляра kind протокола для преобразования в конкретный тип:

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.MICROSOFT_TEAMS_APP:
        print(f"Teams app: {communication_identifier.properties['app_id']}")
    case CommunicationIdentifierKind.PHONE_NUMBER:
        print(f"Phone number: {communication_identifier.properties['value']}")
    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

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Пакет SDK помогает преобразовать:

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

Пользователь связи

Представляет CommunicationUserIdentifier удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

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

CommunicationUserIdentifier

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifier пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере Microsoft Entra или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

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

MicrosoftTeamsUserIdentifier

Номер телефона

Представляет PhoneNumberIdentifier номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

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

MicrosoftTeamsAppIdentifier

Неизвестно

Существует UnknownIdentifier для будущих проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового класса

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает абстрактный CommunicationIdentifier. Вы можете вернуться к конкретному типу:

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  MicrosoftTeamsAppIdentifier) {
    Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    System.out.println("Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    System.out.println("Unknown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
}

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Так как azure-communication-common 1.2.0 пакет SDK помогает с преобразованием:

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

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

Пользователь связи

Представляет CommunicationUserIdentifier удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

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

CommunicationUserIdentifier

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifier пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере идентификатора или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

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

MicrosoftTeamsUserIdentifier

Номер телефона

Представляет PhoneNumberIdentifier номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

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

MicrosoftTeamsAppIdentifier

Неизвестно

Существует UnknownIdentifier для будущих проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового протокола

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает CommunicationIdentifier протокол. Легко вернуться к конкретному типу, и мы предлагаем оператор switch-case с сопоставлением шаблонов:

switch (communicationIdentifier)
{
    case let communicationUser as CommunicationUserIdentifier:
        print(#"Communication user: \(communicationUser.id)"#)
    case let teamsUser as MicrosoftTeamsUserIdentifier:
        print(#"Teams user: \(teamsUser.UserId)"#)
    case let teamsApp as MicrosoftTeamsAppIdentifier:
        print(#"Teams app: \(teamsApp.appId)"#)
    case let phoneNumber as PhoneNumberIdentifier:
        print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
    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;
}

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Так как Azure.Communication.Common 1.1.0 пакет SDK помогает с преобразованием:

Swift

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

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

Пользователь связи

Представляет CommunicationUserIdentifier удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование

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

CommunicationUserIdentifier

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifier пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере идентификатора или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

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

MicrosoftTeamsUserIdentifier

Номер телефона

Представляет PhoneNumberIdentifier номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

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

Справочник по API

PhoneNumberIdentifier

Приложение Microsoft Teams

Интерфейс MicrosoftTeamsAppIdentifier представляет бот приложений Голосовой связи Teams, таких как очередь вызовов и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

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

MicrosoftTeamsAppIdentifier

Неизвестно

Существует UnknownIdentifier для будущих проверки правописания, и вы можете столкнуться с ним, когда вы находитесь в старой версии пакета SDK, и новый тип идентификатора был введен недавно. Любой неизвестный идентификатор из службы будет десериализирован UnknownIdentifier в пакет SDK.

Базовое использование

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

Справочник по API

UnknownIdentifier

CommunicationIdentifier Обработка базового класса

При создании идентификаторов для конкретного типа, передаваемого в пакет SDK, пакет SDK возвращает абстрактный CommunicationIdentifier. Вы можете вернуться к конкретному типу:

if (communicationIdentifier instanceof CommunicationUserIdentifier) {
    Log.i(tag, "Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
    Log.i(tag, "Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof  MicrosoftTeamsAppIdentifier) {
    Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    Log.i(tag, "Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    Log.i(tag, "Unknown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
    // can introduce new identifier types
}

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Так как azure-communication-common 1.1.0 пакет SDK помогает с преобразованием:

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

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

Недопустимый необработанный идентификатор просто преобразуется UnknownIdentifier в пакет SDK, и любая проверка выполняется только на стороне службы.

В REST API идентификатор является полиморфным типом: вы создаете объект JSON и свойство, которое сопоставляется с конкретным подтипом идентификатора. Для удобства и обратной совместимости свойства являются необязательными в запросах, kind rawId но заполняются ответами службы.

Пользователь связи

Представляет CommunicationUserIdentifierModel удостоверение пользователя, созданное с помощью пакета SDK для удостоверений или REST API. Это единственный идентификатор, используемый, если приложение не использует возможности взаимодействия Microsoft Teams или телефонии.

Базовое использование


// at some point you will have created a new user identity in your trusted service
// you can specify an identifier with the id of the new user in a request
{
    "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
    }
}

// the corresponding serialization in a response
{
    "kind": "communicationUser",
    "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
    "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
    }
}

Пример запроса, который содержит идентификатор в REST API чата для добавления участника, а также пример ответа с идентификатором при получении сообщения чата.

Справочник по API

CommunicationUserIdentifierModel

Пользователь Microsoft Teams

Представляет MicrosoftTeamsUserIdentifierModel пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph. Кроме того, вы можете найти идентификатор в качестве oid утверждения в маркере Microsoft Entra или маркере доступа Microsoft Entra после входа пользователя и получения маркера.

Базовое использование

// request
{
    "microsoftTeamsUser": {
        "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
    }
}

// response
{
    "kind": "microsoftTeamsUser",
    "rawId": "8:orgid:00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "microsoftTeamsUser": {
        "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
    }
}


// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
    "microsoftTeamsUser": {
        "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "cloud": "gcch"
    }
}

// response
{
    "kind": "microsoftTeamsUser",
    "rawId": "8:gcch:00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "microsoftTeamsUser": {
        "userId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "isAnonymous": false,
        "cloud": "gcch"
    }
}

Справочник по API

MicrosoftTeamsUserIdentifierModel

Номер телефона

Представляет PhoneNumberIdentifierModel номер телефона. Служба предполагает, что номера телефонов форматируются в формате E.164.

Базовое использование

// request
{
    "phoneNumber": {
        "value": "+112345556789"
    }
}

// response
{
    "kind": "phoneNumber",
    "rawId": "4:+112345556789",
    "phoneNumber": {
        "value": "+112345556789"
    }
}

Справочник по API

PhoneNumberIdentifierModel

Приложение Microsoft Teams

Представляет MicrosoftTeamsAppIdentifierModel бот приложений Голосовой связи Teams, таких как очередь звонков и автосекретарь с идентификатором объекта бота Microsoft Entra. Приложения Teams должны быть настроены с учетной записью ресурса. Вы можете получить идентификатор объекта бота Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см . в обозревателе Graph и в пакете SDK для Graph.

Базовое использование

// request
{
    "microsoftTeamsApp": {
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
    }
}

// response
{
    "kind": "microsoftTeamsApp",
    "rawId": "28:orgid:00001111-aaaa-2222-bbbb-3333cccc4444",
    "microsoftTeamsApp": {
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444"
    }
}


// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
    "microsoftTeamsApp": {
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "cloud": "gcch"
    }
}

// response
{
    "kind": "microsoftTeamsApp",
    "rawId": "28:gcch:00001111-aaaa-2222-bbbb-3333cccc4444",
    "microsoftTeamsApp": {
        "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "cloud": "gcch"
    }
}

Справочник по API

MicrosoftTeamsAppIdentifierModel

Неизвестно

Если новый идентификатор появится в службе, он будет понижен до CommunicationIdentifierModel старой версии API.

Базовое использование

// request
{
    "rawId": "a raw id that originated in the service"
}

// response
{
    "kind": "unknown",
    "rawId": "a raw id that originated in the service"
}

Справочник по API

CommunicationIdentifierModel

CommunicationIdentifierModel Обработка ответов

Последние версии API заполняют kind свойство, которое можно использовать для дискриминации:

switch (communicationIdentifier.kind)
{
    case "communicationUser":
        console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
        break;
    case "microsoftTeamsUser":
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
        break;
    case "microsoftTeamsApp":
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsApp.appId}`);
        break;
    case "phoneNumber":
        console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
        break;
    case "unknown":
        console.log(`Unknown: ${communicationIdentifier.rawId}`);
        break;
    default:
        // this case should not be hit because adding a new identifier type requires a new API version
        // if it does get hit, please file an issue on https://github.com/Azure/azure-rest-api-specs/issues 
        break;
}

В более старых версиях API свойство отсутствует, kind и необходимо проверить наличие правильной подпропастерии:

if (communicationIdentifier.communicationUser) {
    console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
} else if (communicationIdentifier.microsoftTeamsUser) {
    console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
} else if (communicationIdentifier.microsoftTeamsApp) {
    console.log(`Teams app: ${communicationIdentifier.microsoftTeamsApp.appId}`);
} else if (communicationIdentifier.phoneNumber) {
    console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
} else {
    console.log(`Unknown: ${communicationIdentifier.rawId}`);
}

Представление необработанного идентификатора

Иногда необходимо сериализовать идентификатор в плоскую строку. Например, если вы хотите сохранить идентификатор в таблице базы данных или хотите использовать его в качестве параметра URL-адреса.

Для этого идентификаторы имеют другое представление RawId. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Если вы используете пакет SDK Azure, это поможет вам с преобразованием. Если вы используете REST API напрямую, необходимо создать необработанный идентификатор вручную, как описано ниже.

Пользователь связи

Идентификатор:

{
    "communicationUser": {
        "id": "[communicationUserId]"
    }
}

Необработанный идентификатор:

[communicationUserId]

Необработанный идентификатор совпадает с необработанным идентификатором communicationUser.id.

Пользователь Microsoft Teams

Идентификатор:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]"
    }
}

Необработанный идентификатор:

8:orgid:[entraUserId]

Необработанный идентификатор — это идентификатор пользовательского объекта Microsoft Entra с 8:orgid:префиксом .

Идентификатор:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]",
        "cloud": "gcch"
    }
}

Необработанный идентификатор:

8:gcch:[entraUserId]

Необработанный идентификатор — это идентификатор пользовательского объекта Microsoft Entra, префиксированный или 8:gcch: 8:dod: в зависимости от облачной среды.

Идентификатор:

{
    "microsoftTeamsUser": {
        "userId": "[visitorUserId]",
        "isAnonymous": true
    }
}

Необработанный идентификатор:

8:teamsvisitor:[visitorUserId]

Необработанный идентификатор — это идентификатор посетителя Teams, префиксированный с 8:teamsvisitor:. Идентификатор посетителя Teams — это временный идентификатор, который Teams создает для включения доступа к собранию.

Номер телефона

Идентификатор:

{
    "phoneNumber": {
        "value": "+1123455567"
    }
}

Необработанный идентификатор:

4:+1123455567

Необработанный идентификатор — это форматированный номер телефона E.164 с 4:префиксом.

Приложение Microsoft Teams

Идентификатор:

{
    "microsoftTeamsApp": {
        "appId": "[entraUserId]"
    }
}

Необработанный идентификатор:

28:orgid:[entraUserId]

Необработанный идентификатор — это идентификатор пользовательского объекта Entra приложения, префиксированный с 28:orgid:префиксом.

Идентификатор:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]",
        "cloud": "gcch"
    }
}

Необработанный идентификатор:

28:gcch:[entraUserId]

Необработанный идентификатор — это идентификатор пользовательского объекта Entra приложения, префиксированный или 28:gcch: 28:dod: в зависимости от облачной среды.

Неизвестно

Идентификатор:

{
    "rawId": "[unknown identifier id]"
}

Необработанный идентификатор:

[unknown identifier id]

Если необработанный идентификатор недопустим, служба завершится сбоем запроса.

Следующие шаги