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

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

Интерфейс MicrosoftTeamsUserIdentifier представляет пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из свойства id в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, вы можете найти идентификатор в качестве 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/[email protected]").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

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

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

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

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

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

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

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

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

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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене 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/[email protected]").get();

// Get the tenantId from Graph API
const org = await graphClient.api("/organization").get();
const tenantId = org.value[0].id;

//Communication Services Resource ID
const resourceId = "<resource-id-guid>";

// create an identifier
const teamsExtensionUser = { userId: user.id, tenantId: tenantId, resourceId: resourceId };

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

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

Неизвестно

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

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

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

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

Как справиться с `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. Идентификатор всегда можно преобразовать в соответствующий необработанный идентификатор, и допустимый необработанный идентификатор всегда можно преобразовать в идентификатор.

Поскольку [email protected] 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 представляет собой удостоверение пользователя, созданное с помощью Identity 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

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

Элемент MicrosoftTeamsUserIdentifier обозначает пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из свойства id в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, вы можете найти идентификатор в качестве 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["[email protected]"]
    .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

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

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

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

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

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

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

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

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

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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене Microsoft Entra или токене доступа Microsoft Entra после входа пользователя и получения токена.

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

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

// Get the tenantId from Graph API
var organization = await graphClient.Organization
    .Request()
    .GetAsync();

string tenantId = organization.CurrentPage.FirstOrDefault()?.Id;

//Communication Services Resource ID
var resourceId = "<resource-id-guid>";

// create an identifier
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.Id, tenantId, resourceId);

// if you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(userId: user.Id, tenantId: tenantId, resourceId: resourceId, cloud: CommunicationCloudEnvironment.Gcch);

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

Неизвестно

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

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

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

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

Как обрабатывать базовый класс `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 представляет собой удостоверение пользователя, созданное с помощью Identity 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

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

Элемент MicrosoftTeamsUserIdentifier обозначает пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из свойства id в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, вы можете найти идентификатор в качестве 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/[email protected]").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

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

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

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

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

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

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

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

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

# 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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене 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/[email protected]").json().get("id");

# get the tenantId from Graph API
tenant_id = graph_client.get("/organization").json()["value"][0]["id"]

# Communication Services Resource ID
resourceId = "<resource-id-guid>"

# create an identifier
teams_user = TeamsExtensionUserIdentifier(user_id, tenant_id, resource_id)

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

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

Неизвестно

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

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

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

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

Как обрабатывать базовый класс `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 представляет собой удостоверение пользователя, созданное с помощью Identity 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

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

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

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

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("[email protected]")
    .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

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

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

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

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

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

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

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

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

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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене Microsoft Entra или токене доступа Microsoft Entra после входа пользователя и получения токена.

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

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("[email protected]")
    .buildRequest()
    .get();

// get the tenantId from Graph API
OrganizationCollectionPage organizations = graphClient.organization()
    .buildRequest()
    .get();
String tenantId = organizations.getCurrentPage().get(0).id;

// Communication Services Resource ID
var resourceId = "<resource-id-guid>";

// create an identifier
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId);

// if you're not operating in the public cloud, you must also set the right Cloud type.
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

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

Неизвестно

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

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

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

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

Как обрабатывать базовый класс `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 представляет собой удостоверение пользователя, созданное с помощью Identity 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

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

Элемент MicrosoftTeamsUserIdentifier обозначает пользователя Teams с идентификатором объекта пользователя Microsoft Entra. Вы можете получить идентификатор объекта пользователя Microsoft Entra с помощью REST API Microsoft Graph /users из свойства id в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Либо вы можете найти идентификатор в качестве 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("[email protected]")

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

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

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

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

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

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

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

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

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

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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене Microsoft Entra или токене доступа 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("[email protected]")

// get the tenantId from Graph API
let tenantId = await getTenantIdFromGraph()

// Communication Services Resource ID
let resourceId = "<resource-id-guid>"

// create an identifier
let teamsExtensionUser = TeamsExtensionUserIdentifier(userId: userId, tenantId: tenantId, resourceId: resourceId)

// if you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsExtensionUser = TeamsExtensionUserIdentifier(userId: userId, tenantId: tenantId, resourceId: resourceId, cloudEnvironment: CommunicationCloudEnvironment.Gcch)

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

Неизвестно

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

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

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

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

Как обрабатывать `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 помогает с преобразованием:

Скорый

// 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 представляет собой удостоверение пользователя, созданное с помощью Identity 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

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

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

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

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("[email protected]")
    .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

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

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

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

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

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

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

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

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

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

Пользователь расширения Teams

Интерфейс TeamsExtensionUserIdentifier представляет пользователя Teams, активированного для использования расширяемости телефонии Teams. Требуется идентификатор объекта пользователя Teams в Microsoft Entra, идентификатор клиента (tenant ID) в Microsoft Entra, в котором находится пользователь, и идентификатор ресурса Служб коммуникации Azure. Вы можете получить идентификатор пользовательского объекта Microsoft Entra с помощью REST API Microsoft Graph /users из id свойства в ответе и идентификатор клиента Microsoft Entra через конечную точку REST API Microsoft Graph /organization из id свойства в ответе. Дополнительные сведения о работе с Microsoft Graph см. в Graph Explorer и ознакомьтесь с Graph SDK. Кроме того, можно найти идентификатор объекта в виде утверждения oid, а идентификатор клиента — в виде утверждения tid в токене Microsoft Entra или токене доступа Microsoft Entra после входа пользователя и получения токена.

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

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("[email protected]")
    .buildRequest()
    .get();

// get the tenantId from Graph API
OrganizationCollectionPage organizations = graphClient.organization()
    .buildRequest()
    .get();
String tenantId = organizations.getCurrentPage().get(0).id;

// Communication Services Resource ID
var resourceId = "<resource-id-guid>";

// create an identifier
var teamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId);

// if you're not operating in the public cloud, you must also set the right Cloud type.
var gcchTeamsExtensionUser = new TeamsExtensionUserIdentifier(user.id, tenantId, resourceId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

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

Неизвестно

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

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

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

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