識別子について

Microsoft Teams ユーザー

MicrosoftTeamsUserIdentifier インターフェイスは、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。 Teams アプリケーションは、リソースアカウントで構成する必要があります。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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();

// 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 を指定する必要がないように設計されています。また、 kind プロパティとの判別共用体は、SDK から返された場合にのみ使用されます。ただし、識別子を対応する判別共用体の型に変換する必要がある場合は、次のヘルパーを使用できます。

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

Raw ID 表現

識別子をフラットな文字列にシリアル化しなければならない場合もあります。たとえば、データベーステーブルに識別子を格納する場合や、URL パラメーターとして使用する場合などです。

その目的のために、識別子には別途、RawId と呼ばれる表現が用意されています。識別子は常に対応する Raw ID に変換でき、有効な Raw 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 に変換され、検証はサービス側でのみ行われます。

Communication ユーザー

CommunicationUserIdentifierは、Identity SDK または REST API を使用して作成されたユーザー ID を表します。 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 は、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。 Teams アプリケーションは、リソースアカウントで構成する必要があります。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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();

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

Raw ID 表現

識別子をフラットな文字列にシリアル化しなければならない場合もあります。たとえば、データベーステーブルに識別子を格納する場合や、URL パラメーターとして使用する場合などです。

その目的のために、識別子には別途、RawId と呼ばれる表現が用意されています。識別子は常に対応する Raw ID に変換でき、有効な Raw 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 に変換され、検証はサービス側でのみ行われます。

Communication ユーザー

CommunicationUserIdentifierは、Identity SDK または REST API を使用して作成されたユーザー ID を表します。 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 は、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。 Teams アプリケーションは、リソースアカウントで構成する必要があります。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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");

# 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

Raw ID 表現

識別子をフラットな文字列にシリアル化しなければならない場合もあります。たとえば、データベーステーブルに識別子を格納する場合や、URL パラメーターとして使用する場合などです。

その目的のために、識別子には別途、RawId と呼ばれる表現が用意されています。識別子は常に対応する Raw ID に変換でき、有効な Raw 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 に変換され、検証はサービス側でのみ行われます。

Communication ユーザー

CommunicationUserIdentifierは、Identity SDK または REST API を使用して作成されたユーザー ID を表します。 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 は、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。 Teams アプリケーションは、リソースアカウントで構成する必要があります。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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();

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

Raw ID 表現

識別子をフラットな文字列にシリアル化しなければならない場合もあります。たとえば、データベーステーブルに識別子を格納する場合や、URL パラメーターとして使用する場合などです。

その目的のために、識別子には別途、RawId と呼ばれる表現が用意されています。識別子は常に対応する Raw ID に変換でき、有効な Raw 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 に変換され、検証はサービス側でのみ行われます。

Communication ユーザー

CommunicationUserIdentifierは、Identity SDK または REST API を使用して作成されたユーザー ID を表します。 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 は、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の id プロパティから取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後、ID トークンoidMicrosoft 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。 Teams アプリケーションは、リソースアカウントで構成する必要があります。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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")

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

Raw ID 表現

識別子をフラットな文字列にシリアル化しなければならない場合もあります。たとえば、データベーステーブルに識別子を格納する場合や、URL パラメーターとして使用する場合などです。

その目的のために、識別子には別途、RawId と呼ばれる表現が用意されています。識別子は常に対応する Raw ID に変換でき、有効な Raw 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 に変換され、検証はサービス側でのみ行われます。

Communication ユーザー

CommunicationUserIdentifierは、Identity SDK または REST API を使用して作成されたユーザー ID を表します。 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 は、Microsoft Entra ユーザーオブジェクト ID を持つ Teams ユーザーを表します。 Microsoft Entra ユーザーオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の id プロパティから取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後、ID トークンoidMicrosoft 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 Voice アプリケーションのボットと、その Microsoft Entra ボットオブジェクト ID が提示されます。リソースアカウントを使用して Teams アプリケーションを構成します。 Microsoft Entra ボットオブジェクト ID は、Microsoft Graph REST API /users エンドポイントを介して応答の 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 Phone Extensibility で有効になっている Teams ユーザーを表します。 TeamsExtensionUserIdentifierには、Teams ユーザーの Microsoft Entra ユーザーオブジェクト ID、ユーザーが存在する Microsoft Entra テナント ID、および Azure Communication Services リソース ID が必要です。応答のプロパティから id エンドポイントを使用して Microsoft Entra ユーザーオブジェクト ID を取得し、応答のプロパティから id エンドポイントを介して Microsoft Entra テナント ID を取得できます。 Microsoft Graph の操作の詳細については、「 Graph エクスプローラー」を参照し、 Graph SDK を参照してください。または、ユーザーがサインインしてトークンを取得した後で、オブジェクト ID をoid要求として、テナント ID を tidまたは 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();

// 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 リファレンス