Solução de problemas nos Serviços de Comunicação do Azure
Esse documento ajuda a solucionar problemas que você pode enfrentar na sua solução de Serviços de Comunicação. Se estiver solucionando problemas de SMS, você poderá habilitar o relatório de entrega com a Grade de Eventos para capturar os detalhes da entrega do SMS.
Obtendo ajuda
Incentivamos os desenvolvedores a enviarem perguntas, sugerirem recursos e relatarem problemas. Para ajudar na obtenção de ajuda, temos uma página dedicada de suporte e opções de ajuda que lista suas opções de suporte.
Para ajudá-lo a solucionar determinados tipos de problemas, você pode ser solicitado a fornecer qualquer uma das seguintes informações:
- MS-CV ID: Esse ID é usado para solucionar problemas de chamadas e mensagens.
- ID de chamada: Esse ID é usado para identificar chamadas dos Serviços de Comunicação.
- ID da mensagem SMS: Esse ID é usado para identificar mensagens SMS.
- ID do resumo do programa de código curto: essa ID é usada para identificar um resumo de programa de aplicativo de código curto.
- ID do resumo da campanha de verificação gratuita: esse ID é usado para identificar um aplicativo de resumo da campanha de verificação gratuita.
- Email ID da mensagem: essa ID é usada para identificar solicitações de Enviar Email.
- ID de Correlação: essa ID é usada para identificar solicitações feitas usando a Automação de Chamadas.
- Registros de chamadas: esses registros contêm informações detalhadas que podem ser usadas para solucionar problemas de chamadas e de rede.
Confira também nossa documentação de limites de serviço para obter mais informações sobre limitações.
Acessar sua ID do MS-CV
A ID do MS-CV pode ser acessada configurando o diagnóstico na instância do objeto clientOptions ao inicializar os SDKs. O diagnóstico pode ser configurado para qualquer um dos SDKs do Azure, incluindo chat, identidade e chamadas de voz por IP.
Exemplo das opções do cliente
Os trechos de código a seguir demonstram a configuração de diagnóstico. Quando os SDKs são usados com diagnósticos habilitados, os detalhes do diagnóstico podem ser emitidos para o ouvinte de eventos configurado:
// 1. Import Azure.Core.Diagnostics
using Azure.Core.Diagnostics;
// 2. Initialize an event source listener instance
using var listener = AzureEventSourceListener.CreateConsoleLogger();
Uri endpoint = new Uri("https://<RESOURCE-NAME>.communication.azure.net");
var (token, communicationUser) = await GetCommunicationUserAndToken();
CommunicationUserCredential communicationUserCredential = new CommunicationUserCredential(token);
// 3. Setup diagnostic settings
var clientOptions = new ChatClientOptions()
{
Diagnostics =
{
LoggedHeaderNames = { "*" },
LoggedQueryParameters = { "*" },
IsLoggingContentEnabled = true,
}
};
// 4. Initialize the ChatClient instance with the clientOptions
ChatClient chatClient = new ChatClient(endpoint, communicationUserCredential, clientOptions);
ChatThreadClient chatThreadClient = await chatClient.CreateChatThreadAsync("Thread Topic", new[] { new ChatThreadMember(communicationUser) });
IDs de acesso necessárias para a Automação de Chamadas
Ao solucionar problemas com o SDK de Automação de chamadas, como problemas de gerenciamento ou gravação de chamadas, você precisa coletar os IDs que ajudam a identificar a chamada ou operação com falha. Você pode fornecer qualquer uma das duas IDs mencionadas aqui.
No cabeçalho da resposta da API, localize o campo
X-Ms-Skype-Chain-Id.
Registros de chamadas: esses registros contêm informações detalhadas que podem ser usadas para solucionar problemas de chamadas e de rede. Por exemplo
CallConnectedouPlayFailed, localize o CorrelationID.
Além de uma dessas IDs, forneça os detalhes sobre o caso de uso com falha e o carimbo de data/hora de quando a falha foi observada.
Acessar sua ID de chamada do cliente
Ao solucionar problemas de chamadas de voz ou de vídeo, você pode precisar fornecer um call ID. Esse valor pode ser acessado através da propriedade id do objeto call:
// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)
Acessar sua ID de mensagem de SMS
Para problemas de SMS, você pode coletar a ID da mensagem do objeto de resposta.
// Instantiate the SMS client
const smsClient = new SmsClient(connectionString);
async function main() {
const result = await smsClient.send({
from: "+18445792722",
to: ["+1972xxxxxxx"],
message: "Hello World 👋🏻 via Sms"
}, {
enableDeliveryReport: true // Optional parameter
});
console.log(result); // your message ID is in the result
}
Acessar a ID do resumo do programa de código curto
A ID do resumo do programa pode ser encontrada no portal do Azure na folha Códigos Curtos.
Acesse seu ID de resumo de campanha de verificação gratuito
O ID do resumo do programa pode ser encontrado no portal do Azure na folha Documentos Regulatórios.
Acesse seu ID de operação de email
Ao solucionar problemas de envio de email ou solicitações de status de mensagem de email, você pode ser solicitado a fornecer um operation ID. Esse valor pode ser acessado na resposta:
var emailSendOperation = await emailClient.SendAsync(
wait: WaitUntil.Completed,
senderAddress: sender,
recipientAddress: recipient,
subject: subject,
htmlContent: htmlContent);
/// Get the OperationId so that it can be used for tracking the message for troubleshooting
Console.WriteLine($"Email operation id = {emailSendOperation.Id}");
Acessando arquivos de suporte no SDK de chamada
Chamar o SDK fornece métodos convenientes para obter acesso aos arquivos de log. Esses arquivos podem ser valiosos para especialistas e engenheiros de suporte da Microsoft. Recomenda-se a coleta proativa desses logs quando problemas são detectados.
Habilitar e acessar registros de chamadas
[JavaScript]
O SDK de Chamada dos Serviços de Comunicação do Azure se baseiam internamente na biblioteca @azure/logger para controlar o registro em log.
Use o método setLogLevel do pacote @azure/logger para configurar o nível de saída do log. Crie um registrador e passe-o para o construtor CallClient:
import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });
Você pode usar o AzureLogger para redirecionar a saída de log dos SDKs do Azure substituindo o método AzureLogger.log: você pode fazer logon no console do navegador, em um arquivo, em buffer, enviar para nosso próprio serviço, etc. Se você for enviar logs pela rede para seu próprio serviço, não envie uma solicitação por linha de log, pois isso afetará o desempenho do navegador. Em vez disso, acumule linhas de log e envie-as em lotes.
// Redirect log output
AzureLogger.log = (...args) => {
// To console, file, buffer, REST API, etc...
console.log(...args);
};
SDK nativo (Android/iOS)
Para Android, iOS e Windows, o SDK de Chamada dos Serviços de Comunicação do Azure oferece acesso a arquivos de log.
Para chamar SDKs nativos, consulte os tutoriais de acesso ao arquivo de log
Bibliotecas de UI (Android, iOS)
Se você estiver usando as Bibliotecas de UI dos Serviços de Comunicação do Azure para Android ou iOS, os comentários do usuário poderá ser solicitado por meio do formulário de suporte integrado.
Para obter mais informações sobre como usar a funcionalidade de suporte do formulário Calling UI Support, veja o Tutorial de integração do formulário de suporte. Esse documento orienta você na adição do manipulador de eventos necessário e na criação de uma implementação cliente/servidor básica para armazenamento centralizado de informações de suporte. Esse guia foi elaborado para orientá-lo em seu caminho rumo à integração com os serviços de suporte que sua organização utiliza.
Construindo fluxos de suporte completos em suas integrações ACS
Esteja você usando o Calling SDK ou o Calling UI SDK, fornecer suporte aos usuários finais é um componente essencial de qualquer integração robusta. O documento a seguir destaca as principais considerações em cada ponto do ciclo de comentários do suporte e fornece pontos de partida para saber mais.
Localizando informações do Microsoft Entra
- Obter a ID do Diretório
- Obter a ID do Aplicativo
- Obter a identificação de usuário
Obter a ID do Diretório
Para encontrar o ID do seu diretório (locatário), siga essas etapas:
Navegue até o portal do Azure e entre usando as credenciais.
No painel esquerdo, selecione Microsoft Entra ID.
Na página Visão geral do ID do Microsoft Entra, copie o ID do diretório (locatário) e armazene-o no código do seu aplicativo.
Obter a ID do Aplicativo
Para encontrar o ID do seu aplicativo, siga essas etapas:
Navegue até o portal do Azure e entre usando as credenciais.
No painel esquerdo, selecione Microsoft Entra ID.
Em Registros de aplicativo no Microsoft Entra ID, selecione seu aplicativo.
Copie a ID do aplicativo e armazene-a no código do aplicativo.
A ID do diretório (locatário) também pode ser encontrada na página de visão geral do aplicativo.
Obter a identificação de usuário
Para encontrar seu ID de usuário, siga essas etapas:
Navegue até o portal do Azure e entre usando as credenciais.
No painel esquerdo, selecione Microsoft Entra ID.
Em Usuários no Microsoft Entra ID, selecione seu usuário.
Na página Perfil dos usuários do Microsoft Entra, copie o ID do objeto e armazene-o no código do seu aplicativo.
Obtendo a ID do recurso imutável
Às vezes, você também precisa fornecer a ID de recurso imutável do recurso do Serviço de Comunicação. Para encontrá-lo, siga essas etapas:
- Navegue até o portal do Azure e entre usando as credenciais.
- Abra seu recurso do Serviço de Comunicação do Azure.
- No painel esquerdo, selecione Visão geral e mude para uma visualização JSON
- Na página JSON do Recurso, copie o valor
immutableResourceIde forneça-o à sua equipe de suporte.
Verificação da qualificação da licença do Teams para usar o suporte dos Serviços de Comunicação do Azure para usuários do Teams
Há duas maneiras de verificar a qualificação de sua Licença do Teams para usar o suporte dos Serviços de Comunicação do Azure para usuários do Teams:
- Verificação por meio do cliente Web do Teams
- Verificar sua licença atual do Teams por meio da API do Microsoft Graph
Verificação por meio do cliente Web do Teams
Para verificar a elegibilidade da licença do Teams por meio do cliente Web do Teams, siga essas etapas:
- Abra o navegador e navegue até o Cliente Web do Teams.
- Entre com credenciais que tenham uma licença válida do Teams.
- Se a autenticação for bem-sucedida e você permanecer no domínio https://teams.microsoft.com/, sua Licença do Teams estará qualificada. Se a autenticação falhar ou você for redirecionado para o domínio https://teams.live.com/v2/, sua Licença do Teams não estará qualificada para usar o suporte dos Serviços de Comunicação do Azure para usuários do Teams.
Verificar sua licença atual do Teams por meio da API do Microsoft Graph
Você pode encontrar sua licença atual do Teams usando licenseDetails Microsoft Graph API que retorna as licenças atribuídas a um usuário. Siga essas etapas para usar a ferramenta Graph Explorer para visualizar licenças atribuídas a um usuário:
Abra o navegador e navegue até o Explorador do Graph
Entre no Explorador do Graph usando as credenciais.
Na caixa de consulta, insira a seguinte API e clique em Executar Consulta:
https://graph.microsoft.com/v1.0/me/licenseDetails
Ou você pode consultar um usuário específico fornecendo a ID do usuário usando a seguinte API:
https://graph.microsoft.com/v1.0/users/{id}/licenseDetailsO painel Visualização de resposta exibe a saída da seguinte maneira:
Observe que o objeto de resposta mostrado aqui pode ser reduzido para facilitar a leitura.
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('071cc716-8147-4397-a5ba-b2105951cc0b')/assignedLicenses", "value": [ { "skuId": "b05e124f-c7cc-45a0-a6aa-8cf78c946968", "servicePlans":[ { "servicePlanId":"57ff2da0-773e-42df-b2af-ffb7a2317929", "servicePlanName":"TEAMS1", "provisioningStatus":"Success", "appliesTo":"User" } ] } ] }Localize detalhes da licença em que a propriedade
servicePlanNametem um dos valores na tabela Licenças qualificadas do Teams
Como chamar códigos de erro do SDK
O SDK de Chamada dos Serviços de Comunicação do Azure usa os códigos de erro a seguir para ajudar você a solucionar problemas de chamada. Esses códigos de erro são expostos por meio da propriedade call.callEndReason depois que uma chamada é encerrada.
| Código do erro | Descrição | Ação a ser tomada |
|---|---|---|
| 403 | Proibido/Falha na autenticação. | Verifique se o token dos Serviços de Comunicação é válido e se não expirou. |
| 404 | Chamada não encontrada. | Verifique se o número que você está chamando (ou a chamada em que está ingressando) existe. |
| 408 | O controlador de chamada atingiu o tempo limite. | O controlador de chamada atingiu o tempo limite aguardando as mensagens de protocolo dos pontos de extremidade do usuário. Verifique se os clientes estão conectados e disponíveis. |
| 410 | Erro de pilha de mídia local ou infraestrutura de mídia. | Verifique se você está usando o SDK mais recente em um ambiente com suporte. |
| 430 | Não foi possível entregar a mensagem ao aplicativo cliente. | Verifique se o aplicativo cliente está em execução e disponível. |
| 480 | Ponto de extremidade de cliente remoto não registrado. | Verifique se o ponto de extremidade remoto está disponível. |
| 481 | Falha na manipulação da chamada de entrada. | Abra uma solicitação de suporte por meio do portal do Azure. |
| 487 | Chamada cancelada, recusada localmente, encerrada devido a um problema de incompatibilidade de ponto de extremidade ou com falha na geração da oferta de mídia. | Comportamento esperado. |
| 490, 491, 496, 497, 498 | Problemas de rede do ponto de extremidade local. | Verifique sua rede. |
| 500, 503, 504 | Erro de infraestrutura dos Serviços de Comunicação. | Abra uma solicitação de suporte por meio do portal do Azure. |
| 603 | Chamada globalmente recusada pelo participante dos Serviços de Comunicação remota | Comportamento esperado. |
Códigos de erro do SDK de Automação de Chamadas
Os códigos de erro abaixo são expostos pelo SDK de Automação de Chamadas.
| Código do Erro | Descrição | Ações a serem tomadas |
|---|---|---|
| 400 | Solicitação inválida | A solicitação de entrada é inválida. Examine a mensagem de erro para determinar qual entrada está incorreta. |
| 400 | Falha ao executar | Verifique se o arquivo de áudio é WAV, 16KHz, Mono e verifique se o URL do arquivo está acessível publicamente. |
| 400 | Falha no reconhecimento | Verifique a mensagem de erro. A mensagem destaca se essa falha é devido ao tempo limite ter sido atingido ou se a operação foi cancelada. Para obter mais informações sobre os códigos de erro e mensagens, verifique nosso guia de instruções para coletar a entrada do usuário. |
| 401 | Não Autorizado | A autenticação HMAC falhou. Verifique se a cadeia de conexão usada para criar CallAutomationClient está correta. |
| 403 | Proibido | A solicitação é proibida. Verifique se você pode obter acesso ao recurso que está tentando acessar. |
| 404 | Recurso não encontrado | A chamada em que você está tentando agir não existe. Por exemplo, transferir uma chamada que já foi desconectada. |
| 429 | Número excessivo de solicitações | Tente novamente após um atraso sugerido no cabeçalho Retry-After e, em seguida, faça a retirada exponencial. |
| 500 | Erro interno do servidor | Tente novamente após atraso. Se ele persistir, acione um tíquete de suporte. |
| 500 | Falha ao executar | Abra uma solicitação de suporte por meio do portal do Azure. |
| 500 | Falha no reconhecimento | Verifique a mensagem de erro e confirme se o formato do arquivo de áudio é válido (WAV, 16KHz, Mono), se o formato de arquivo for válido, registre uma solicitação de suporte por meio de portal do Azure. |
| 502 | Gateway inválido | Após um atraso, tente novamente com um novo cliente HTTP. |
Considere as dicas abaixo ao solucionar determinados problemas.
- O aplicativo não está recebendo o evento da Grade de Eventos IncomingCall: verifique se o ponto de extremidade do aplicativo foi validado com a Grade de Eventos no momento da criação da assinatura do evento. O status de provisionamento da sua assinatura de evento será marcado como bem-sucedido se a validação for bem-sucedida.
- Receber o erro 'O campo CallbackUri é inválido': a Automação de Chamadas não dá suporte a pontos de extremidade HTTP. Verifique se a URL de retorno de chamada fornecida dá suporte a HTTPS.
- A ação PlayAudio não reproduz tudo: atualmente, somente o formato Wave file (.wav) tem suporte para arquivos de áudio. O conteúdo de áudio no arquivo de onda deve ser mono (canal único), amostras de 16 bits com uma taxa de amostragem de 16.000 (16KHz).
- As ações em pontos de extremidade PSTN não estão funcionando: CreateCall, Transfer, AddParticipant e Redirect para números de telefone exigem que você defina SourceCallerId na solicitação de ação. A menos que você esteja usando o Roteamento Direto, a ID do chamador de origem deve ser um número de telefone pertencente ao recurso dos Serviços de Comunicação para que a ação seja bem-sucedida.
Consulte este artigo para saber mais sobre os problemas conhecidos que estão sendo acompanhados pela equipe de produtos.
Chat de códigos de erro do SDK
O SDK do Chat dos Serviços de Comunicação do Azure usa os códigos de erro a seguir para ajudar você a solucionar problemas de chat. Os códigos de erro são expostos por meio da propriedade error.code na resposta de erro.
| Código do erro | Descrição | Ação a ser tomada |
|---|---|---|
| 401 | Não Autorizado | Verifique se o token dos Serviços de Comunicação é válido e se não expirou. |
| 403 | Proibido | Verifique se o iniciador da solicitação tem acesso ao recurso. |
| 429 | Número excessivo de solicitações | Verifique se o aplicativo do lado do cliente lida com esse cenário de maneira amigável. Se o erro persistir, envie uma solicitação de suporte. |
| 503 | Serviço indisponível | Abra uma solicitação de suporte por meio do portal do Azure. |
Códigos de erro de SMS
O SDK de SMS dos Serviços de Comunicação do Azure usa os códigos de erro a seguir para ajudar você a solucionar problemas de SMS. Os códigos de erro são expostos por meio do campo "DeliveryStatusDetails" no relatório de entrega do SMS.
| Código do erro | Descrição | Ação a ser tomada |
|---|---|---|
| 2000 | Mensagem entregue com êxito | |
| 4000 | A mensagem foi rejeitada devido à detecção de fraudes | Verifique se você não está excedendo o número máximo de mensagens permitido para seu número |
| 4001 | A mensagem foi rejeitada devido ao formato de número de origem inválido | Verifique se o número Para está no formato E.164 e o formato do número Para está no formato E.164 ou no formato de Código curto |
| 4002 | A mensagem foi rejeitada devido ao formato de número de Destino/Para inválido | Verifique se o número Para está no formato E.164 |
| 4003 | Falha ao entregar a mensagem devido a um destino sem suporte | Verifique se o destino que você está tentando enviar tem suporte |
| 4004 | Falha ao entregar a mensagem, pois o número de Destino/Para não existe | Verifique se o número Para o qual você está enviando é válido |
| 4005 | A mensagem está bloqueada pela operadora de destino | |
| 4006 | O número de Destino/Para não está acessível | Tente enviar novamente a mensagem mais tarde |
| 4007 | O número de Destino/Para recusou o recebimento de mensagens de você | Marque o número de Destino/Para como recusado para que nenhuma outra tentativa de mensagem seja feita ao número |
| 4008 | Você excedeu o número máximo de mensagens permitidas para seu perfil | Verifique se você não está excedendo o número máximo de mensagens permitidas para seu número ou use filas para enviar as mensagens em lote |
| 4009 | A mensagem é rejeitada pelo Sistema de Direitos da Microsoft | Na maioria das vezes, isso acontece se for detectada atividade fraudulenta. Entre em contato com o suporte para obter mais detalhes |
| 4010 | A mensagem foi bloqueada devido ao número de chamada gratuita não ter sido verificado | Examine os limites de envio não verificados e envie a verificação de chamada gratuita assim que possível |
| 5.000 | Falha na entrega da mensagem. Entre em contato com a equipe de suporte da Microsoft para obter mais detalhes | Abra uma solicitação de suporte por meio do portal do Azure |
| 5001 | Falha na entrega da mensagem devido à indisponibilidade temporária do aplicativo/sistema | |
| 5002 | Transportadora não suporta relatório de entrega | Na maioria das vezes, isso acontece se uma transportadora não oferecer suporte a relatórios de entrega. Nenhuma ação é necessária, pois a mensagem pode já ter sido entregue. |
| 9999 | Falha ao entregar a mensagem devido a um erro/falha desconhecido | Tente enviar a mensagem novamente |
Informações relacionadas
- Acesse os logs de voz e vídeo, chat, email, gravação, SMS e automação de chamadas.
- APIs de nome de arquivo de log para chamar SDK
- Métricas
- Limites de serviço
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de