FAQ da API de registos de chamadas do Microsoft Graph

Este tópico fornece respostas às perguntas mais frequentes sobre a API de registos de chamadas no Microsoft Graph.

O que é a API de registos de chamadas do Microsoft Graph?

A API de registos de chamadas do Microsoft Graph oferece informações de utilização e diagnóstico para chamadas e reuniões online que ocorrem na sua organização ao utilizar o Microsoft Teams ou Skype for Business. As organizações, também conhecidas como "inquilinos", podem utilizar a API de registos de chamadas para subscrever, listar, obter registos de chamadas por IDs de chamada e procurar chamadas para um participante. Para obter mais informações, consulte Trabalhar com a API de registos de chamadas no Microsoft Graph.

Que permissão é necessária para utilizar a API de registos de chamadas?

A sua aplicação precisa da permissão CallRecords.Read.All para aceder aos registos de chamadas no Microsoft Graph. Um administrador tem de conceder esta permissão à aplicação. Para saber mais, confira Referência de permissões do Microsoft Graph.

Posso utilizar permissões delegadas com a API de registos de chamadas?

Não, a API de registos de chamadas não suporta permissões delegadas.

Por que motivo não posso utilizar permissões delegadas com a API de registos de chamadas?

Não pode utilizar permissões delegadas porque não existe forma de limitar a permissão CallRecords.Read.All a chamadas ou utilizadores específicos. A permissão da aplicação é concedida ao nível da organização, não ao nível do utilizador individual.

Como fazer pedir um registo de chamada com a API de registos de chamadas?

Para pedir um registo de chamada, tem de fazer um GET pedido ao /communications/callRecords/{id} ponto final, onde {id} é o identificador exclusivo da chamada. Certifique-se de que tem a permissão CallRecords.Read.All e inclua o cabeçalho Autorização com um token de portador válido. Para obter mais informações, veja Obter a documentação get callRecord.

Onde posso encontrar os IDs de chamada das chamadas que ocorreram na minha organização?

Pode localizar e recolher IDs de chamada das seguintes formas:

• Subscrever notificações: subscreva o feed de notificações de alteração e receba notificações que contenham IDs de chamada sempre que for criado um novo registo de chamada.
• Listar registos de chamadas: obtenha uma lista de IDs de chamada ao pedi-la na API List callRecords.
• Pesquisa manual: se tiver acesso ao Call Analytics no Centro de Administração do Teams para Microsoft Teams, pode procurar manualmente um ID de chamada no histórico de um utilizador. No entanto, não existe nenhum sistema automatizado disponível para obter todos os IDs de chamada do Call Analytics.
• Utilize callChainId:: procure o ID da chamada através callChainId da API Obter chamada após a conclusão da chamada. Utilize esta abordagem quando a chamada for criada programaticamente e estiver a trabalhar com o tipo de recurso de chamada. Além disso, o callChainId pode diferir do ID do registo de chamada em determinados cenários, como chamadas de transferência, devido às especificidades da arquitetura. Por conseguinte, utilize os outros métodos nesta lista sempre que possível.

Quando está disponível um registo de chamada?

Normalmente, é gerada uma primeira versão de um registo de chamada e é enviada uma notificação no prazo de 15 minutos após o fim de uma chamada. No entanto, o serviço pode demorar até 60 minutos a disponibilizar o registo de chamada. Para obter mais informações, veja a página Latência .

Durante quanto tempo são retidos os registos de chamadas?

Os registos de chamadas são retidos durante 30 dias após o fim da chamada.

Posso obter registos de chamadas com mais de 30 dias?

Não, a API de registos de chamadas não devolve registos de chamadas com mais de 30 dias. Os pedidos para esses registos resultam numa 404 Not Found resposta de erro.

Por que motivo a minha primeira notificação de registo de chamada está atrasada?

A notificação do registo de chamada pode ser adiada porque o serviço pode demorar até 60 minutos a disponibilizar a primeira versão de um registo de chamada. Se ocorrer um atraso mais longo na entrega da primeira versão do registo de chamadas, marcar para interrupções comunicadas pela equipa da API de registos de chamadas no separador Estado de Funcionamento do Portal do Teams Administração. Além disso, pode abrir um pedido de suporte com a equipa da API de registos de chamadas.

Por que motivo as versões subsequentes do meu registo de chamada estão atrasadas?

As versões subsequentes de um registo de chamada podem ser entregues após a latência inicial de 60 minutos. Isto significa que, embora a primeira versão esteja disponível dentro de 60 minutos, as atualizações posteriores ao registo de chamadas podem chegar mais tarde devido a telemetria atrasada do cliente e outros fatores.

Porque é que um registo de chamada tem campos em falta?

Um registo de chamada pode ter campos em falta devido a telemetria atrasada de um cliente. Quando ficam disponíveis novos dados telemétricos, o sistema gera um novo registo de chamada com informações atualizadas, incrementa o valor da version propriedade e envia-lhe o registo de chamada atualizado. Se o registo de chamada tiver propriedades em falta, aguarde pela próxima versão do registo de chamada.

No entanto, é importante ter em atenção que alguns campos podem permanecer vazios por predefinição ou porque a telemetria do cliente nunca chegou, como valores de fluxo de multimédia.

Se os campos críticos ou entregues anteriormente estiverem em falta, abra um pedido de suporte com a equipa da API de registos de chamadas.

Como posso listar todos os participantes que assistiram a uma chamada?

Pode utilizar os seguintes métodos para listar todos os participantes da chamada:

1. Listar participants_v2 API

   Utilize a Lista participants_v2 API para recolher a lista completa de participantes para um ID de chamada pedido.

2. Utilize o parâmetro de consulta OData $expand no objeto callRecords para expandir a propriedade participants_v2

   Pode ligar GET communications/callRecords/{id}?$expand=participants_v2 para obter detalhes de chamadas de alto nível juntamente com a lista de participantes.

3. Criar uma lista de participantes personalizados

   Para ver todos os participantes, implemente uma solução personalizada para criar a lista de participantes a partir dos dados dos registos de chamadas:

   1. Chame a API Get callRecord e expanda a sessions propriedade : GET /communications/callRecords/{id}?$expand=sessions.
   2. Para chamadas ponto a ponto (P2P), leia as caller propriedades e callee de cada uma session na lista recebida sessions . Para chamadas de reunião, leia apenas a caller propriedade.
   3. Crie a sua lista de participantes personalizados com base na identidade do caller ponto final. Para chamadas P2P, inclua também a identidade do callee ponto final. Recolha as idpropriedades , displayName, e outras necessárias para cada participante.

Por que motivo não vejo todos os participantes que assistiram a uma chamada durante a lista de chamadas participants_v2 API?

Poderá não ver todos os participantes porque a Lista participants_v2 API suporta a paginação, limitando o número de participantes na resposta a 130 por página. Se existirem mais de 130 utilizadores na chamada, a primeira resposta de registo de chamada contém 130 participantes, juntamente com uma @odata.nextLink propriedade. Esta propriedade inclui o URL para chamar a API e receber o próximo conjunto de participantes. Continue este processo até que a ligação seguinte esteja vazia, o que indica que não há mais participantes para obter.

Por que motivo são devolvidas sessões duplicadas para um registo de chamada?

Uma sessão de registo de chamada representa exclusivamente uma única comunicação utilizador-utilizador em chamadas ponto a ponto ou uma única comunicação de serviço de utilizador numa chamada de grupo ou reunião. No entanto, em alguns cenários de chamada, uma única comunicação de serviço de utilizador pode envolver várias identidades de serviço numa única sessão, como uma transferência virtual entre um atendedor automático e uma fila de chamadas. Nestes cenários, um ID de sessão pode ser duplicado uma ou mais vezes para representar corretamente cada identidade envolvida na comunicação e a respetiva duração de comunicação.

Por que motivo recebo um erro 404 Não Encontrado?

Seguem-se algumas razões pelas quais poderá encontrar um 404 Not Found erro:

• Chamada recente: se a chamada tiver sido efetuada nos últimos 60 minutos, o registo de chamada poderá ainda não ter sido gerado. Aguarde 60 minutos após a chamada terminar e tente novamente.
• Chamada antiga: se a chamada tiver mais de 30 dias, a API de registos de chamadas devolve um 404 Not Found erro por predefinição.
• Outros problemas: se nenhum dos motivos se aplicar, marcar para quaisquer interrupções comunicadas pela equipa da API de registos de chamadas no separador Estado de Funcionamento do Portal do Teams Administração. Além disso, pode abrir um pedido de suporte com a equipa da API de registos de chamadas para obter assistência.