Compartilhar via

Serviços de Comunicação do Azure com suporte a identidades do Teams – Casos de uso

  • Artigo

O Microsoft Teams fornece identidades gerenciadas pela ID do Microsoft Entra e experiências de chamada controladas pelo Centro de Administração e políticas do Teams. Os usuários podem ter atribuído licenças para habilitar chamadas telefônicas e recursos avançados de chamada da Telefonia do Microsoft Teams. Os Serviços de Comunicação do Azure com suporte a identidades do Teams permite gerenciar chamadas voIP (voz por IP) do Teams e chamadas telefônicas do Teams, além de ingressar em reuniões do Teams. Os desenvolvedores podem estender os Serviços de Comunicação do Azure com a API do Graph para fornecer dados contextuais do ecossistema do Microsoft 365. Esta página está oferendo uma inspiração de como usar as tecnologias Microsoft existentes para fornecer uma experiência de ponta a ponta e cenários de chamada com usuários do Teams e SDKs de chamada dos Serviços de Comunicação do Azure.

Caso de uso 1: Fazer uma chamada PSTN de saída do Teams

Esse cenário mostra um caso de uso multilocatário, em que a empresa Contoso está fornecendo SaaS para a empresa Fabrikam. O SaaS permite que os usuários da Fabrikam façam chamadas telefônicas do Teams por meio de um site personalizado que usa a identidade do usuário do Teams e a configuração da conectividade PSTN atribuída a esse usuário.

O diagrama mostra a experiência do usuário da Alice ao fazer uma chamada telefônica do Teams para a cliente Megan.

O seguinte diagrama de sequência mostra as etapas detalhadas de inicialização de uma chamada telefônica do Teams:

O diagrama de sequência descreve o conjunto detalhado de etapas, que inicia uma chamada telefônica do Teams usando os Serviços de Comunicação do Azure e o Teams.

Etapas

  1. Autenticar a Alice da Fabrikam no aplicativo cliente da Contoso: Alice está usando um navegador para abrir a página da Web da Fabrikam e autenticar-se. Veja mais detalhes sobre a autenticação com a identidade do Teams. Se a autenticação for bem-sucedida, Alice será redirecionada à página inicial.
  2. Carregar clientes e os números PSTN: a Contoso fornece uma lógica personalizada para recuperar a lista de clientes e os números de telefone associados. Essa lista é renderizada na página inicial para Alice.
  3. Iniciar uma chamada para Carla: Alice seleciona um botão para iniciar uma chamada PSTN para Carla no aplicativo cliente da Contoso. O aplicativo cliente usa o SDK de chamada dos Serviços de Comunicação do Azure para fornecer a funcionalidade de chamadas. Primeiro, ele cria uma instância do callAgent, que contém o token de acesso dos Serviços de Comunicação do Azure adquirido durante a primeira etapa.
const callClient = new CallClient(); 
tokenCredential = new AzureCommunicationTokenCredential('<AlICE_ACCESS_TOKEN>');
callAgent = await callClient.createTeamsCallAgent(tokenCredential)

Depois, você precisa iniciar uma chamada para o número de telefone da Carla.

const pstnCallee = { phoneNumber: '<MEGAN_PHONE_NUMBER_E164_FORMAT>' }
const oneToOneCall = callAgent.startCall([pstnCallee], { threadId: '00000000-0000-0000-0000-000000000000' });
  1. Conectando a chamada PSTN à Carla: a chamada é encaminhada por meio da conectividade telefônica do Teams atribuída a Alice, alcançando a rede PSTN e tocando o telefone associado ao número fornecido. Carla vê uma chamada recebida do número de telefone associado ao usuário Alice do Teams.
  2. Carla aceita a chamada: Carla aceita a chamada e a conexão entre Alice e Carla é estabelecida.

Caso de uso 2: receber uma chamada telefônica de entrada do Teams

Esse cenário mostra um caso de uso multilocatário, em que a empresa Contoso está fornecendo SaaS para a empresa Fabrikam. O SaaS permite que os usuários da Fabrikam recebam chamada telefônica do Teams por meio de um site personalizado que usa a identidade do usuário do Teams e a configuração da conectividade PSTN atribuída a esse usuário.

O diagrama mostra a experiência do usuário da Alice ao receber uma chamada telefônica do Teams da cliente Megan.

O seguinte diagrama de sequência mostra etapas detalhadas para aceitar chamadas telefônicas de entrada do Teams:

O diagrama de sequência descreve o conjunto detalhado de etapas, que recebe uma chamada telefônica do Teams usando os Serviços de Comunicação do Azure e o Teams.

Etapas

  1. Autenticar a Alice da Fabrikam no aplicativo cliente da Contoso: Alice está usando um navegador para abrir a página da Web da Fabrikam e autenticar-se. Veja mais detalhes sobre a autenticação com a identidade do Teams. Se a autenticação for bem-sucedida, Alice será redirecionada à página inicial.
  2. Assinar chamadas recebidas: o aplicativo cliente usa o SDK de chamada dos Serviços de Comunicação do Azure para fornecer a funcionalidade de chamadas. Primeiro, ele cria uma instância do callAgent, que contém o token de acesso dos Serviços de Comunicação do Azure adquirido durante a primeira etapa.
const callClient = new CallClient(); 
tokenCredential = new AzureCommunicationTokenCredential('<AlICE_ACCESS_TOKEN>');
callAgent = await callClient.createTeamsCallAgent(tokenCredential)

Depois, você assina o evento de chamada recebida.

const incomingCallHandler = async (args: { teamsIncomingCall: TeamsIncomingCall }) => {
    
    const incomingCall = args.teamsIncomingCall;
    
    // Get information about caller
    var callerInfo = incomingCall.callerInfo
    
    showIncomingCall(callerInfo,incomingCall);
};
callAgent.on('incomingCall', incomingCallHandler);

O método showIncomingCall é um método personalizado da Contoso que processa uma interface do usuário para indicar chamadas de entrada e dois botões para aceitar e recusar a chamada. Se você selecionar o botão Aceitar, o seguinte código será usado:

// Accept the call
var call = await incomingCall.accept();

Se você selecionar o botão recusar, o seguinte código será usado:

// Reject the call
incomingCall.reject();
  1. Carla inicia uma chamada para o número PSTN atribuído ao usuário Alice do Teams: Carla usa o telefone para ligar para Alice. A rede da operadora se conectará à conectividade telefônica do Teams atribuída a Alice e ligará para todos os pontos de extremidade do Teams registrados para Alice. Ele inclui: a área de trabalho do Teams, dispositivos móveis, clientes web e aplicativos baseados nos Serviços de Comunicação do Azure que chamam o SDK.
  2. O aplicativo cliente da Contoso mostra a chamada de entrada da Carla: o aplicativo cliente recebe a notificação de chamada de entrada. O método showIncomingCall usaria a lógica da Contoso personalizada para converter o número de telefone no nome do cliente (por exemplo, um banco de dados que armazena pares de chave-valor que consistem em um número de telefone e um nome de cliente). Quando as informações são recuperadas, a notificação é mostrada como Alice no aplicativo cliente da Contoso.
  3. Alice aceita a chamada: Alice seleciona um botão para aceitar a chamada e a conexão entre Alice e Carla é estabelecida.

Caso de uso 3: Fazer uma chamada VoIP de saída do Teams

Esse cenário mostra um caso de uso multilocatário, em que a empresa Contoso está fornecendo SaaS para a empresa Fabrikam. O SaaS permite que os usuários da Fabrikam façam chamadas VoIP do Teams por meio de um site personalizado que usa a identidade do usuário do Teams.

O diagrama mostra a experiência do usuário da Alice ao fazer uma chamada VoIP do Teams para a colega Megan.

O seguinte diagrama de sequência mostra as etapas detalhadas de inicialização de uma chamada VoIP do Teams:

O diagrama de sequência descreve o conjunto detalhado de etapas, que inicia uma chamada VoIP do Teams usando os Serviços de Comunicação do Azure e o Teams.

Etapas

  1. Autenticar a Alice da Fabrikam no aplicativo cliente da Contoso: Alice está usando um navegador para abrir a página da Web da Fabrikam e autenticar-se. Veja mais detalhes sobre a autenticação com a identidade do Teams. Se a autenticação for bem-sucedida, Alice será redirecionada à página inicial.
  2. Carregar usuários da organização da Fabrikam e os identificadores: o aplicativo cliente da Contoso utiliza a API do Graph para obter uma lista de usuários do locatário da Fabrikam. Alice ou o administrador precisa dar consentimento para a API do Graph executar essa ação. Saiba mais sobre o comando da API do Graph na documentação.
GET https://graph.microsoft.com/v1.0/users
Permissions: User.ReadBasic.All (delegated)
Response: response.body.value[1].displayName; // ”Megan Bowen”
	  response.body.value[1].id; // "e8b753b5-4117-464e-9a08-713e1ff266b3"

O aplicativo cliente da Contoso mostrará a lista de usuários e a capacidade de iniciar uma chamada para um determinado usuário.

  1. Iniciar uma chamada para Carla: Alice seleciona um botão para iniciar uma chamada VoIP do Teams para Carla no aplicativo cliente da Contoso. O aplicativo cliente usa o SDK de chamada dos Serviços de Comunicação do Azure para fornecer a funcionalidade de chamadas. As chamadas em clientes do Teams são associadas ao chat do Teams. Primeiro, o aplicativo solicita a criação de um chat dedicado para a chamada VoIP.
POST https://graph.microsoft.com/v1.0/chats
Body:
{
    "chatType": "oneOnOne",
    "members": [
        {
            "@odata.type": "#microsoft.graph.aadUserConversationMember",
            "roles": [
                "owner"
            ],
            "user@odata.bind": "https://graph.microsoft.com/v1.0/users('8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca')"
        },
        {
            "@odata.type": "#microsoft.graph.aadUserConversationMember",
            "roles": [
                "owner"
            ],
            "user@odata.bind": "https://graph.microsoft.com/v1.0/users('e8b753b5-4117-464e-9a08-713e1ff266b3')"
        }
    ]
}
Permissions: Chat.Create (delegated)
Response: response.body.value.id; // "19:8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca_e8b753b5-4117-464e-9a08-713e1ff266b3@unq.gbl.spaces"

Em seguida, o aplicativo cliente cria uma instância de callAgent, que mantém o token de acesso dos Serviços de Comunicação do Azure adquirido durante a primeira etapa.

const callClient = new CallClient(); 
tokenCredential = new AzureCommunicationTokenCredential('<AlICE_ACCESS_TOKEN>');
callAgent = await callClient.createTeamsCallAgent(tokenCredential)

Depois, você inicia uma chamada para a ID do Teams da Carla.

var teamsUser = { microsoftTeamsUserId: 'e8b753b5-4117-464e-9a08-713e1ff266b3'};
const oneToOneCall = callAgent.startCall([teamsUser], { threadId: '19:8c0a1a67-50ce-4114-bb6c-da9c5dbcf6ca_e8b753b5-4117-464e-9a08-713e1ff266b3@unq.gbl.spaces' });
  1. Conectando a chamada VoIP à Carla: a chamada é encaminhada por meio do Teams e liga para os clientes do Teams associados à Carla. Megan vê uma chamada de entrada de Alice com o nome definido na ID do Microsoft Entra.
  2. Carla aceita a chamada: Carla aceita a chamada e a conexão entre Alice e Carla é estabelecida.

Caso de uso 4: Receber uma chamada recebida de VoIP do Teams

Esse cenário mostra um caso de uso multilocatário, em que a empresa Contoso está fornecendo SaaS para a empresa Fabrikam. O SaaS permite que os usuários da Fabrikam recebam uma chamada VoIP do Teams por meio de um site personalizado que usa a identidade do usuário do Teams e aplica as políticas de roteamento aplicadas a esse usuário.

O diagrama está mostrando a experiência do usuário da Alice ao receber uma chamada VoIP do Teams da cliente Megan.

O seguinte diagrama de sequência mostra etapas detalhadas para aceitar chamadas de entrada VoIP do Teams:

O diagrama de sequência descreve o conjunto detalhado de etapas, que recebe uma chamada VoIP do Teams usando os Serviços de Comunicação do Azure, a API do Graph e o Teams.

Etapas

  1. Autenticar a Alice da Fabrikam no aplicativo cliente da Contoso: Alice está usando um navegador para abrir a página da Web da Fabrikam e autenticar-se. Veja mais detalhes sobre a autenticação com a identidade do Teams. Se a autenticação for bem-sucedida, Alice será redirecionada à página inicial.
  2. Assinar chamadas recebidas: o aplicativo cliente usa o SDK de chamada dos Serviços de Comunicação do Azure para fornecer a funcionalidade de chamadas. Primeiro, ele cria uma instância do callAgent, que contém o token de acesso dos Serviços de Comunicação do Azure adquirido durante a primeira etapa.
const callClient = new CallClient(); 
tokenCredential = new AzureCommunicationTokenCredential('<AlICE_ACCESS_TOKEN>');
callAgent = await callClient.createTeamsCallAgent(tokenCredential)

Em seguida, o aplicativo assina o evento de chamada recebida.

const incomingCallHandler = async (args: { teamsIncomingCall: TeamsIncomingCall }) => {
    
    const incomingCall = args.teamsIncomingCall;
    
    // Get information about caller
    var callerInfo = incomingCall.callerInfo
    
    showIncomingCall(callerInfo,incomingCall);
};
callAgent.on('incomingCall', incomingCallHandler);

O método showIncomingCall é um método personalizado da Contoso que processa uma interface do usuário para indicar chamadas de entrada e dois botões para aceitar e recusar a chamada. Se você selecionar o botão Aceitar, o seguinte código será usado:

// Accept the call
var call = await incomingCall.accept();

Se você selecionar o botão recusar, o seguinte código será usado:

// Reject the call
incomingCall.reject();
  1. Carla inicia uma chamada VoIP para o usuário Alice do Teams: Carla usa o cliente Teams da área de trabalho para ligar para Alice. A infraestrutura do Teams ligará para todos os pontos de extremidade associados a Alice. Ele inclui: a área de trabalho do Teams, dispositivos móveis, clientes web e aplicativos baseados nos Serviços de Comunicação do Azure que chamam o SDK.
  2. O aplicativo cliente da Contoso mostra a chamada de entrada da Carla: o aplicativo cliente recebe a notificação de chamada de entrada. O método showIncomingCall usaria API do Graph para converter a ID do usuário do Teams no nome de exibição.
GET https://graph.microsoft.com/v1.0/users/e8b753b5-4117-464e-9a08-713e1ff266b3
Permissions: User.Read (delegated)
Response: response.body.value.displayName; // ”Megan Bowen”
	  response.body.value.id; // "e8b753b5-4117-464e-9a08-713e1ff266b3"

Quando as informações são recuperadas, a notificação é mostrada como Alice no aplicativo cliente da Contoso.

  1. Alice aceita a chamada: Alice seleciona um botão para aceitar a chamada e a conexão entre Alice e Carla é estabelecida.

Caso de uso 5: Ingressar em uma reunião do Teams

Esse cenário mostra um caso de uso multilocatário, em que a empresa Contoso está fornecendo SaaS para a empresa Fabrikam. O SaaS permite que os usuários da Fabrikam ingressem em reuniões do Teams por meio de um site personalizado que usa a identidade do usuário do Teams.

O diagrama mostra a experiência do usuário da Alice ao ingressar na reunião do Teams.

O seguinte diagrama de sequência mostra as etapas detalhadas para ingressar em uma reunião do Teams:

O diagrama de sequência descreve o conjunto detalhado de etapas, que ingressa em uma reunião do Teams usando os Serviços de Comunicação do Azure, a API do Graph e o Teams.

Etapas

  1. Autenticar a Alice da Fabrikam no aplicativo cliente da Contoso: Alice está usando um navegador para abrir a página da Web da Fabrikam e autenticar-se. Veja mais detalhes sobre a autenticação com a identidade do Teams. Se a autenticação for bem-sucedida, Alice será redirecionada à página inicial.
  2. Carregar as reuniões do Teams e os identificadores: o aplicativo cliente da Contoso utiliza a API do Graph para obter uma lista de reuniões do Teams para os usuários da Fabrikam. Alice ou o administrador precisa dar consentimento para a API do Graph executar essa ação. Saiba mais sobre o comando da API do Graph na documentação.
GET https://graph.microsoft.com/v1.0/me/calendar/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
Permissions: Calendars.Read (delegated)
Response: response.body.value[0].subject; // ”Project Tailspin”
	  response.body.value[0].onlineMeeting.joinUrl; // "https://teams.microsoft.com/l/meetup-join/..."
	  response.body.value[0].start.dateTime;
	  response.body.value[0].end.dateTime;
	  response.body.value[0].location.displayName;

O aplicativo cliente da Contoso mostrará a lista de reuniões do Teams e a capacidade de ingressar nelas.

  1. Ingressar na reunião do Teams "Reunião inicial do projeto": Alice seleciona um botão para ingressar nessa reunião do Teams no aplicativo cliente da Contoso. O aplicativo cliente usa o SDK de chamada dos Serviços de Comunicação do Azure para fornecer a funcionalidade de chamadas. Os aplicativos cliente criam uma instância de callAgent, que contém o token de acesso dos Serviços de Comunicação do Azure adquirido durante a primeira etapa.
const callClient = new CallClient(); 
tokenCredential = new AzureCommunicationTokenCredential('<AlICE_ACCESS_TOKEN>');
callAgent = await callClient.createTeamsCallAgent(tokenCredential)

Em seguida, o aplicativo ingressa em uma reunião por meio da URL de ingresso recebida.

var meetingLocator = new TeamsMeetingLinkLocator("https://teams.microsoft.com/l/meetup-join/...");
callAgent.startCallJoinAsync(meetingLocator , new JoinCallOptions());

Em seguida, Alice ingressa na reunião do Teams.

  1. Outros participantes que ingressaram na reunião do Teams: a experiência fornecida é uma reunião do Teams padrão. Com base na configuração e em convites, podem entrar na reunião do Teams o usuário do Teams, um usuário anônimo do Teams usando o web client do Teams, o cliente de área de trabalho do Teams ou o cliente móvel do Teams, o usuário dos Serviços de Comunicação do Azure por meio de aplicativos baseados em serviços de comunicação que chamam o SDK ou usuários que usam telefones.

Próximas etapas

Os artigos a seguir podem ser de seu interesse: