了解标识符

Microsoft Teams 用户

MicrosoftTeamsUserIdentifier 接口代表 Teams 用户及其 Microsoft Entra 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，在用户登录并获取令牌后，可以在 oid或 Microsoft Entra 访问令牌中找到该 ID 作为声明。

基本用法

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

电话号码

PhoneNumberIdentifier 接口表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。必须使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

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

// 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 时，可能会遇到这个接口，尤其是在最近引入新的标识符类型的情况下。在 SDK 中，来自服务的任何未知标识符都被反序列化为 UnknownIdentifier。

基本用法

// 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。此外，仅当从 SDK 返回时，才会使用与 kind 属性的区分联合。但是，如果需要将标识符转换为其相应的区分联合类型，则可以使用此帮助程序：

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

原始 ID 表示形式

有时需要将标识符序列化为平面字符串。例如，如果要将标识符存储在数据库表中，或者想要将其用作 URL 参数。

为此，标识符可以采用名为 RawId 的另一种表示形式。标识符始终可以转换为其对应的原始 ID，而有效的原始 ID 始终可以转换为标识符。

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

无效的原始 ID 在 SDK 中转换为 UnknownIdentifier ，并且任何验证仅发生在服务端。

通信用户

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 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，在登录并获取令牌后，可以在 oid或 Microsoft Entra 访问令牌中找到该 ID 作为声明。

基本用法

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

电话号码

PhoneNumberIdentifier 表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。必须使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

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

// 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 上时可能会遇到此问题，并且最近引入了新的标识符类型。在 SDK 中，来自服务的任何未知标识符都被反序列化为 UnknownIdentifier。

基本用法

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

原始 ID 表示形式

有时需要将标识符序列化为平面字符串。例如，如果要将标识符存储在数据库表中，或者想要将其用作 URL 参数。

为此，标识符可以采用名为 RawId 的另一种表示形式。标识符始终可以转换为其对应的原始 ID，而有效的原始 ID 始终可以转换为标识符。

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

无效的原始 ID 在 SDK 中转换为 UnknownIdentifier ，并且任何验证仅发生在服务端。

通信用户

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 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，在登录并获取令牌后，可以在 oid或 Microsoft Entra 访问令牌中找到该 ID 作为声明。

基本用法

# 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 参考

电话号码

PhoneNumberIdentifier 表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。必须使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

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

# 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 上时可能会遇到此问题，并且最近引入了新的标识符类型。服务中的任何未知标识符在 SDK 中反序列化为 UnknownIdentifier。

基本用法

# 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

原始 ID 表示形式

有时需要将标识符序列化为平面字符串。例如，如果要将标识符存储在数据库表中，或者想要将其用作 URL 参数。

为此，标识符可以采用名为 RawId 的另一种表示形式。标识符始终可以转换为其对应的原始 ID，而有效的原始 ID 始终可以转换为标识符。

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)

无效的原始 ID 在 SDK 中转换为 UnknownIdentifier ，并且任何验证仅发生在服务端。

通信用户

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 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，在用户登录并获取令牌后，可以在 oid或 Microsoft Entra 访问令牌中找到该 ID 作为声明。

基本用法

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

电话号码

PhoneNumberIdentifier 表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。必须使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("bob@contoso.com")
    .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 上时可能会遇到此问题，并且最近引入了新的标识符类型。在 SDK 中，来自服务的任何未知标识符都被反序列化为 UnknownIdentifier。

基本用法

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

原始 ID 表示形式

有时需要将标识符序列化为平面字符串。例如，如果要将标识符存储在数据库表中，或者想要将其用作 URL 参数。

为此，标识符可以采用名为 RawId 的另一种表示形式。标识符始终可以转换为其对应的原始 ID，而有效的原始 ID 始终可以转换为标识符。

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

无效的原始 ID 在 SDK 中转换为 UnknownIdentifier ，并且任何验证仅发生在服务端。

通信用户

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 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，可以在用户登录并获取令牌后，在 oid或 Microsoft Entra 访问令牌中找到作为声明提供的 ID。

基本用法

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

电话号码

PhoneNumberIdentifier 表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。必须使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

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

// 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 上时可能会遇到此问题，并且最近引入了新的标识符类型。在 SDK 中，来自服务的任何未知标识符都被反序列化为 UnknownIdentifier。

基本用法

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

原始 ID 表示形式

有时需要将标识符序列化为平面字符串。例如，如果要将标识符存储在数据库表中，或者想要将其用作 URL 参数。

为此，标识符可以采用名为 RawId 的另一种表示形式。标识符始终可以转换为其对应的原始 ID，而有效的原始 ID 始终可以转换为标识符。

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

无效的原始 ID 在 SDK 中转换为 UnknownIdentifier，并且任何验证仅在服务端进行。

通信用户

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 用户对象 ID。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 用户对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。或者，可以在用户登录并获取令牌后，在 oid或 Microsoft Entra 访问令牌中找到作为声明提供的 ID。

基本用法

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

电话号码

PhoneNumberIdentifier 表示电话号码。服务假设电话号码采用 E.164 格式。

基本用法

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

API 参考

Microsoft Teams 应用程序

MicrosoftTeamsAppIdentifier 接口代表 Teams 语音应用程序的机器人，例如通话队列和自动助理及其 Microsoft Entra 机器人对象 ID。使用资源帐户配置 Teams 应用程序。可以通过 Microsoft Graph REST API /users 终结点从响应中的 id 属性检索 Microsoft Entra 机器人对象 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 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 用户。 A TeamsExtensionUserIdentifier 需要 Teams 用户的 Microsoft Entra 用户对象 ID、用户所在的 Microsoft Entra 租户 ID 和 Azure 通信服务资源 ID。可以通过响应中的属性中的 Microsoft Graph REST API /users 终结点 id 检索 Microsoft Entra 用户对象 ID，并通过响应中属性中的 Microsoft Graph REST API /organization 终结点检索 id Microsoft Entra 租户 ID。有关使用 Microsoft Graph 的详细信息，请参阅 Graph 资源管理器并查看 Graph SDK。也可在用户登录并获取令牌后，在 oid或 tid中找到作为声明提供的对象 ID 和作为声明提供的租户 ID。

基本用法

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("bob@contoso.com")
    .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 上时可能会遇到此问题，并且最近引入了新的标识符类型。在 SDK 中，来自服务的任何未知标识符都被反序列化为 UnknownIdentifier。

基本用法

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

API 参考