Compartilhar via


Reconhecer tipos de identificador

SDKs de Serviços de Comunicação e APIs REST usam o tipo de identificador para identificar quem está se comunicando com quem. Por exemplo, os identificadores especificam para quem ligar ou quem enviou uma mensagem de chat.

Dependendo do contexto, os identificadores são encapsulados com propriedades extras, como dentro do ChatParticipant SDK do Chat ou dentro do RemoteParticipant SDK de Chamada.

Neste artigo, você aprenderá sobre diferentes tipos de identificadores e como eles se parecem em linguagens de programação. Você também receberá dicas de como usá-los.

O tipo CommunicationIdentifier

Existem identidades de usuário que você mesmo cria e identidades externas. Os usuários e números de telefone do Microsoft Teams são identidades externas que vêm a ser reproduzidas em cenários de interoperabilidade. Cada um desses diferentes tipos de identidade tem um identificador correspondente que o representa. Um identificador é um tipo estruturado que oferece segurança de tipo e funciona bem com a conclusão do código do editor.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

A interface MicrosoftTeamsUserIdentifierrepresenta um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token do Microsoft Entra ou um token de acesso do Microsoft Entra após o usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

A interface PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com a interface base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna um CommunicationIdentifierKind, que é uma união discriminada. É fácil restringir para um tipo concreto e sugerimos uma instrução switch-case com correspondência de padrões:

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

As interfaces do identificador foram projetadas para que você não precise especificar kind para reduzir o detalhamento, e a união discriminadora com a propriedade kind só é usada quando retornada do SDK. No entanto, se você encontrar a necessidade de traduzir um identificador para seu tipo de união discriminadora correspondente, poderá usar este auxiliar:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Como azure-communication-common@2.1.0 o SDK ajuda na conversão:

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

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifier representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token do Microsoft Entra ou um token de acesso do Microsoft Entra após o usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

O PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com a classe base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna um protocolo CommunicationIdentifier. É fácil restringir para um tipo concreto e sugerimos uma instrução switch-case com correspondência de padrões:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Como Azure.Communication.Common 1.2.0 o SDK ajuda na conversão:

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

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifier representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token do Microsoft Entra ou um token de acesso do Microsoft Entra após o usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

O PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com a classe base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna um protocolo CommunicationIdentifier. Classes de identificador concretas são apenas o protocolo CommunicationIdentifier junto a um dicionário de tipo chamado properties. Portanto, você pode usar a correspondência de padrões na variável de instância do protocolo kind para traduzir para o tipo concreto:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

O SDK ajuda na conversão:

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifier representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token do Microsoft Entra ou um token de acesso do Microsoft Entra após o usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

O PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com a classe base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna o tipo abstrato CommunicationIdentifier. Você pode reduzir a conversão de volta para um tipo concreto:

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
}

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Como azure-communication-common 1.2.0 o SDK ajuda na conversão:

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

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifier representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token de ID do Microsoft Entra ou um token de acesso do Microsoft Entra após seu usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

O PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com o protocolo base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna um protocolo CommunicationIdentifier. É fácil restringir para um tipo concreto e sugerimos uma instrução switch-case com correspondência de padrões:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Como Azure.Communication.Common 1.1.0 o SDK ajuda na conversão:

Swift

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

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Usuário de comunicação

A interface CommunicationUserIdentifier representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico

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

Referência da API

CommunicationUserIdentifier

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifier representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token de ID do Microsoft Entra ou um token de acesso do Microsoft Entra após seu usuário ter feito login e adquirido um token.

Uso básico

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

Referência da API

MicrosoftTeamsUserIdentifier

Número do telefone

O PhoneNumberIdentifier representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

Referência da API

PhoneNumberIdentifier

Aplicativo do Microsoft Teams

A interface MicrosoftTeamsAppIdentifier representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

Referência da API

MicrosoftTeamsAppIdentifier

Desconhecido

A interface UnknownIdentifier existe para revisão de texto futuro e você pode encontrá-la quando estiver em uma versão antiga do SDK e um novo tipo de identificador tiver sido introduzido recentemente. Qualquer identificador desconhecido do serviço será desserializado para o UnknownIdentifier no SDK.

Uso básico

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

Referência da API

UnknownIdentifier

Como lidar com a classe base CommunicationIdentifier

Enquanto você constrói identificadores para um tipo concreto que você passa para o SDK, o SDK retorna o tipo abstrato CommunicationIdentifier. Você pode reduzir a conversão de volta para um tipo concreto:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Como azure-communication-common 1.1.0 o SDK ajuda na conversão:

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

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

Uma ID bruta inválida será convertida em um UnknownIdentifier no SDK e qualquer validação só acontece no lado do serviço.

Nas APIs REST, o identificador é um tipo polimórfico: você constrói um objeto JSON e uma propriedade que mapeia para um subtipo de identificador concreto. Por motivos de conveniência e compatibilidade com versões anteriores, as propriedades kind e rawId são opcionais em solicitações, mas são populadas em respostas de serviço.

Usuário de comunicação

A interface CommunicationUserIdentifierModel representa uma identidade de usuário que foi criada usando o SDK de Identidade ou a API REST. Ele será o único identificador usado se seu aplicativo não usar recursos de interoperabilidade ou telefonia do Microsoft Teams.

Uso básico


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

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

Você pode encontrar um exemplo para uma solicitação que inclui um identificador na API REST do Chat para adicionar um participante e um exemplo para uma resposta com um identificador na mensagem de chat.

Referência da API

CommunicationUserIdentifierModel

Usuário do Microsoft Teams

O MicrosoftTeamsUserIdentifierModel representa um usuário do Teams com sua ID de objeto de usuário do Microsoft Entra. Você pode recuperar a ID de objeto de usuário do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph. Alternativamente, você pode encontrar a ID como a declaração oid em um token do Microsoft Entra ou um token de acesso do Microsoft Entra após o usuário ter feito login e adquirido um token.

Uso básico

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

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


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

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

Referência da API

MicrosoftTeamsUserIdentifierModel

Número do telefone

O PhoneNumberIdentifierModel representa um número de telefone. O serviço pressupõe que os números de telefone sejam formatados no formato E.164.

Uso básico

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

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

Referência da API

PhoneNumberIdentifierModel

Aplicativo do Microsoft Teams

O MicrosoftTeamsAppIdentifierModel representa um bot dos aplicativos de Voz do Teams, como a Fila de Espera de Chamadas, e o Atendente Automático com sua ID de objeto de bot do Microsoft Entra. Os aplicativos do Teams devem ser configurados com uma conta de recurso. Você pode recuperar a ID de objeto de bot do Microsoft Entra por meio do ponto de extremidade de usuários/API REST do Microsoft Graph da propriedade id na resposta. Para obter mais informações sobre como trabalhar com o Microsoft Graph, experimente o Graph Explorer e examine o SDK do Graph.

Uso básico

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

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


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

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

Referência da API

MicrosoftTeamsAppIdentifierModel

Desconhecido

Se um novo identificador for introduzido em um serviço, ele será rebaixado para CommunicationIdentifierModel no caso de você estar em uma versão antiga da API.

Uso básico

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

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

Referência da API

CommunicationIdentifierModel

Como lidar com CommunicationIdentifierModel em respostas

Versões recentes da API preenchem uma propriedade kind que você pode usar para discriminar em:

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

Em versões de API mais antigas, a propriedade kind está ausente e você precisa verificar a existência da subpropriedade correta:

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

Representação de ID bruta

Às vezes, você precisa serializar um identificador para uma cadeia de caracteres simples. Por exemplo, se você quiser armazenar o identificador em uma tabela de banco de dados ou se quiser usá-lo como um parâmetro de URL.

Para essa finalidade, os identificadores têm outra representação chamada RawId. Um identificador sempre pode ser traduzido para sua ID bruta correspondente e uma ID bruta válida sempre pode ser convertida em um identificador.

Se você estiver usando o SDK do Azure, ele o ajudará com a conversão. Se você usar a API REST diretamente, precisará construir a ID bruta manualmente, conforme descrito abaixo.

Usuário de comunicação

Identificador:

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

ID bruta:

[communicationUserId]

A ID bruta é a mesma que communicationUser.id.

Usuário do Microsoft Teams

Identificador:

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

ID bruta:

8:orgid:[entraUserId]

A ID bruta é a ID do objeto de usuário do Microsoft Entra prefixada com 8:orgid:.

Identificador:

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

ID bruta:

8:gcch:[entraUserId]

A ID bruta é a ID do objeto de usuário do Microsoft Entra prefixada com 8:gcch: ou 8:dod:, dependendo do ambiente de nuvem.

Identificador:

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

ID bruta:

8:teamsvisitor:[visitorUserId]

A ID bruta é a ID de visitante do Teams prefixada com 8:teamsvisitor:. A ID de visitante do Teams é uma ID temporária que o Teams gera para habilitar o acesso à reunião.

Número do telefone

Identificador:

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

ID bruta:

4:+1123455567

A ID bruta é o número de telefone no formato E.164 prefixado com 4:.

Aplicativo Microsoft Teams

Identificador:

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

ID bruta:

28:orgid:[entraUserId]

A ID bruta é a ID do objeto de usuário do Entra do aplicativo prefixada com 28:orgid:.

Identificador:

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

ID bruta:

28:gcch:[entraUserId]

A ID bruta é a ID do objeto de usuário do Entra do aplicativo prefixada com 28:gcch: ou 28:dod:, dependendo do ambiente de nuvem.

Desconhecido

Identificador:

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

ID bruta:

[unknown identifier id]

Se uma ID bruta for inválida, o serviço falhará na solicitação.

Próximas etapas