Solução de problemas nos Serviços de Comunicação do Azure
Este documento ajuda você a solucionar problemas que podem ocorrer em sua solução de Serviços de Comunicação. Se você estiver solucionando problemas de SMS, poderá habilitar o relatório de entrega com a Grade de Eventos para capturar detalhes de entrega de SMS.
Obter ajuda
Incentivamos os desenvolvedores a enviar perguntas, sugerir recursos e relatar problemas como problemas. Para ajudar a obter ajuda, temos uma página dedicada de suporte e opções de ajuda que lista as suas opções de suporte.
Para ajudá-lo a solucionar certos tipos de problemas, você pode ser solicitado a fornecer qualquer uma das seguintes informações:
- MS-CV ID: Este ID é usado para solucionar problemas de chamadas e mensagens.
- ID da chamada: essa ID é usada para identificar chamadas dos Serviços de Comunicação.
- ID da mensagem SMS: este ID é usado para identificar mensagens SMS.
- Short Code Program Brief ID: Este ID é usado para identificar um aplicativo breve do programa de código curto.
- ID breve da campanha de verificação gratuita: este ID é usado para identificar um aplicativo breve da campanha de verificação gratuita.
- ID da mensagem de e-mail: esta ID é usada para identificar solicitações de envio de e-mail.
- ID de correlação: essa ID é usada para identificar solicitações feitas usando a automação de chamadas.
- Registros de chamadas: esses logs contêm informações detalhadas que podem ser usadas para solucionar problemas de chamadas e de rede.
Consulte também a nossa documentação de limites de serviço para obter mais informações sobre limitação e limitações.
Aceda ao seu ID MS-CV
O ID MS-CV pode ser acessado configurando diagnósticos na instância do clientOptions objeto ao inicializar seus SDKs. O diagnóstico pode ser configurado para qualquer um dos SDKs do Azure, incluindo Chat, Identidade e chamadas VoIP.
Exemplo de 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 o diagnóstico habilitado, 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ários para automação de chamadas
Ao solucionar problemas com o SDK de automação de chamadas, como gerenciamento de chamadas ou problemas de gravação, você precisa coletar as IDs que ajudam a identificar a chamada ou operação com falha. Você pode fornecer qualquer um dos dois IDs mencionados aqui.
No cabeçalho da resposta da API, localize o campo
X-Ms-Skype-Chain-Id.
A partir dos eventos de retorno de chamada que seu aplicativo recebe depois de executar uma ação. Por exemplo
CallConnected, ouPlayFailed, localize o correlationID.
Além de um desses IDs, forneça os detalhes sobre o caso de uso com falha e o carimbo de data/hora de quando a falha foi observada.
Aceda ao seu ID de chamada de cliente
Ao solucionar problemas de chamadas de voz ou vídeo, você pode ser solicitado a fornecer um call IDarquivo . Este valor pode ser acessado através da id propriedade do call objeto:
// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)
Aceda ao seu ID de mensagem SMS
Para problemas de SMS, você pode coletar o 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
}
Aceda ao seu breve ID do programa de código curto
A ID breve do programa pode ser encontrada no portal do Azure na folha Short Codes.
Aceda ao ID breve da sua campanha de verificação gratuita
A ID breve do programa pode ser encontrada no portal do Azure na folha Documentos regulamentares.
Aceda ao seu ID de operação de e-mail
Ao solucionar problemas de solicitações de status de envio de e-mail ou mensagem de e-mail, você pode ser solicitado a fornecer um operation IDarquivo . Este 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 coletar proativamente esses logs quando problemas forem detetados.
Habilitar e acessar registros de chamadas
[JavaScript]
O SDK de Chamada dos Serviços de Comunicação do Azure depende internamente da biblioteca @azure/logger para controlar o log.
Use o setLogLevel@azure/logger método do pacote para configurar o nível de saída do log. Crie um logger 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 AzureLogger.log método: Você pode fazer logon no console do navegador, um arquivo, buffer, enviar para nosso próprio serviço, etc. Se você vai enviar logs pela rede para seu próprio serviço, não envie uma solicitação por linha de log porque isso afetará o desempenho do navegador. Em vez disso, acumule linhas de logs 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 interface do usuário (Android, iOS)
Se você estiver usando as Bibliotecas de Interface do Usuário dos Serviços de Comunicação do Azure para Android ou iOS, os comentários dos usuários poderão ser solicitados por meio do formulário de suporte interno.
Para obter mais informações sobre como usar a funcionalidade de suporte do formulário Chamando suporte da interface do usuário, consulte o tutorial de integração do formulário de suporte. Este documento orienta você através da adição do manipulador de eventos necessário e da criação de uma implementação básica cliente/servidor para armazenamento centralizado de informações de suporte. Este guia foi projetado para guiá-lo em seu caminho para uma integração com os serviços de suporte que sua organização usa.
Criando fluxos de suporte de ponta a ponta em suas integrações ACS
Quer esteja a utilizar o SDK de Chamada ou o SDK da IU de Chamada, fornecer suporte aos utilizadores finais é um componente fundamental de qualquer integração robusta. O documento a seguir destaca as principais considerações em cada ponto do ciclo de feedback do Suporte e fornece pontos de partida para saber mais.
Localizando informações do Microsoft Entra
- Obtendo ID de diretório
- Obtendo a ID do aplicativo
- Obter ID de utilizador
Obtendo ID de diretório
Para localizar o ID do diretório (locatário), siga estas etapas:
Navegue até o portal do Azure e entre no portal do Azure usando as credenciais.
No painel esquerdo, selecione Microsoft Entra ID.
Na página Visão geral na ID do Microsoft Entra, copie a ID do diretório (locatário) e armazene-a no código do aplicativo.
Obtendo a ID do aplicativo
Para encontrar o ID do aplicativo, siga estas etapas:
Navegue até o portal do Azure e entre no portal do Azure usando as credenciais.
No painel esquerdo, selecione Microsoft Entra ID.
Em Registos de aplicações no Microsoft Entra ID, selecione a sua aplicação.
Copie o ID da Aplicação e armazene-o no código da aplicação.
O ID do diretório (locatário) também pode ser encontrado na página de visão geral do aplicativo.
Obter ID de utilizador
Para encontrar o seu ID de utilizador, siga estes passos:
Navegue até o portal do Azure e entre no portal do Azure 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 nos usuários do Microsoft Entra, copie a ID do objeto e armazene-a no código do aplicativo.
Obtendo ID de recurso imutável
Às vezes, você também precisa fornecer ID de recurso imutável do seu recurso do Serviço de Comunicação. Para encontrá-lo, siga estas etapas:
- Navegue até o portal do Azure e entre no portal do Azure usando as credenciais.
- Abra o recurso do Serviço de Comunicação.
- No painel esquerdo, selecione Visão geral e alterne para um modo de exibição JSON
- Na página JSON de recursos, copie o
immutableResourceIdvalor e forneça-o à sua equipe de suporte.
Verificação da elegibilidade 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 sua elegibilidade de Licença do Teams para usar o suporte dos Serviços de Comunicação do Azure para usuários do Teams:
- Verificação via web client do Teams
- Verificar a sua licença atual do Teams através da API do Microsoft Graph
Verificação via web client do Teams
Para verificar a elegibilidade da sua Licença do Teams através do web client do Teams, siga estes passos:
- Abra o navegador e navegue até o cliente da Web do Teams.
- Inicie sessão com credenciais que tenham uma licença válida do Teams.
- Se a autenticação for bem-sucedida e você permanecer no domínio, sua Licença do https://teams.microsoft.com/ Teams será elegível. Se a autenticação falhar ou você for redirecionado para o domínio, sua Licença do Teams não estará qualificada para usar o https://teams.live.com/v2/ suporte dos Serviços de Comunicação do Azure para usuários do Teams.
Verificar a sua licença atual do Teams através 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 estas etapas para usar a ferramenta Graph Explorer para exibir licenças atribuídas a um usuário:
Abra o navegador e navegue até o Graph Explorer
Entre no Graph Explorer usando as credenciais.
Na caixa de consulta, digite 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 o ID do usuário usando a seguinte API:
https://graph.microsoft.com/v1.0/users/{id}/licenseDetailsO painel de visualização de resposta exibe a saída da seguinte maneira:
Observe que o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
{ "@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" } ] } ] }Encontre detalhes da licença onde a propriedade
servicePlanNametem um dos valores na tabela Licenças de equipes qualificadas
Chamando códigos de erro do SDK
O SDK de Chamada dos Serviços de Comunicação do Azure usa os seguintes códigos de erro para ajudá-lo a solucionar problemas de chamada. Esses códigos de erro são expostos através da propriedade depois que call.callEndReason uma chamada termina.
| Código de erro | Description | Ação a executar |
|---|---|---|
| 403 | Proibido / Falha de autenticação. | Verifique se o token dos Serviços de Comunicação é válido e não expirou. |
| 404 | Chamada não encontrada. | Certifique-se de que o número para o qual está a ligar (ou a ligar para o qual está a aderir) existe. |
| 408 | O controlador de chamadas atingiu o tempo limite. | O Controlador de Chamadas atingiu o tempo limite aguardando mensagens de protocolo dos pontos de extremidade do usuário. Certifique-se de que os clientes estão conectados e disponíveis. |
| 410 | Pilha de mídia local ou erro de infraestrutura de mídia. | Certifique-se de que está a utilizar o SDK mais recente num ambiente suportado. |
| 430 | Não é possível entregar a mensagem para o 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 ao lidar com a chamada de entrada. | Envie 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 final ou falha ao gerar oferta de mídia. | Comportamento esperado. |
| 490, 491, 496, 497, 498 | Problemas de rede de ponto de extremidade local. | Verifique a sua rede. |
| 500, 503, 504 | Erro de infraestrutura dos Serviços de Comunicação. | Envie uma solicitação de suporte por meio do portal do Azure. |
| 603 | Chamada globalmente recusada por participante dos Serviços de Comunicação Remotos | Comportamento esperado. |
Códigos de erro do SDK de automação de chamadas
Os códigos de erro abaixo são expostos pelo Call Automation SDK.
| Código de Erro | Description | Ações a realizar |
|---|---|---|
| 400 | Mau pedido | A solicitação de entrada é inválida. Observe a mensagem de erro para determinar qual entrada está incorreta. |
| 400 | Falha na reprodução | Certifique-se de que o seu ficheiro de áudio é WAV, 16KHz, Mono e certifique-se de que o URL do ficheiro está acessível publicamente. |
| 400 | Reconhecer falha | Verifique a mensagem de erro. A mensagem destaca se esta falha se deve ao tempo limite atingido ou se a operação foi cancelada. Para obter mais informações sobre os códigos de erro e mensagens, você pode verificar nosso guia de instruções para coletar a entrada do usuário. |
| 401 | Não autorizado | Falha na autenticação HMAC. Verifique se a cadeia de conexão usada para criar CallAutomationClient está correta. |
| 403 | Proibido | O pedido é proibido. Certifique-se de que pode ter acesso ao recurso a que está a tentar aceder. |
| 404 | Recurso não encontrado | A chamada na qual você está tentando agir não existe. Por exemplo, transferir uma chamada que já foi desconectada. |
| 429 | Demasiados pedidos | Tente novamente após um atraso sugerido no cabeçalho Retry-After e, em seguida, recue exponencialmente. |
| 500 | Erro interno do servidor | Tente novamente após um atraso. Se persistir, levante um tíquete de suporte. |
| 500 | Falha na reprodução | Envie uma solicitação de suporte por meio do portal do Azure. |
| 500 | Reconhecer falha | Verifique a mensagem de erro e confirme se o formato de arquivo de áudio é válido (WAV, 16KHz, Mono), se o formato de arquivo for válido, envie uma solicitação de suporte por meio do portal do Azure. |
| 502 | Gateway ruim | Tente novamente após um atraso com um novo cliente http. |
Considere as dicas abaixo ao solucionar determinados problemas.
- Seu aplicativo não está recebendo o evento IncomingCall Event Grid: verifique se o ponto de extremidade do aplicativo foi validado com Event Grid no momento da criação da assinatura do evento. O status de provisionamento para sua assinatura de evento será marcado como bem-sucedido se a validação tiver sido bem-sucedida.
- Obtendo o erro 'O campo CallbackUri é inválido': A automação de chamadas não suporta pontos de extremidade HTTP. Certifique-se de que o URL de retorno de chamada fornecido suporta HTTPS.
- A ação PlayAudio não reproduz nada: Atualmente, apenas o formato de arquivo Wave (.wav) é suportado para arquivos de áudio. O conteúdo de áudio no arquivo wave deve ser mono (canal único), amostras de 16 bits com uma taxa de amostragem de 16.000 (16KHz).
- As ações nos pontos de extremidade PSTN não estão funcionando: CreateCall, Transfer, AddParticipant e Redirect to phone numbers exigem que você defina SourceCallerId na solicitação de ação. A menos que você esteja usando o Roteamento Direto, o ID do chamador de origem deve ser um número de telefone de propriedade do recurso dos Serviços de Comunicação para que a ação seja bem-sucedida.
Consulte este artigo para saber mais sobre quaisquer problemas conhecidos que estão sendo rastreados pela equipe do produto.
Códigos de erro do SDK do chat
O SDK de Chat dos Serviços de Comunicação do Azure usa os seguintes códigos de erro para ajudá-lo a solucionar problemas de chat. Os códigos de erro são expostos através da error.code propriedade na resposta de erro.
| Código de erro | Description | Ação a executar |
|---|---|---|
| 401 | Não autorizado | Verifique se o token dos Serviços de Comunicação é válido e não expirou. |
| 403 | Proibido | Certifique-se de que o iniciador da solicitação tenha acesso ao recurso. |
| 429 | Demasiados pedidos | Certifique-se de que seu aplicativo do lado do cliente lide com esse cenário de maneira amigável. Se o erro persistir, envie um pedido de suporte. |
| 503 | Serviço Indisponível | Envie uma solicitação de suporte por meio do portal do Azure. |
Códigos de erro SMS
O SDK do SMS dos Serviços de Comunicação do Azure usa os seguintes códigos de erro para ajudá-lo a solucionar problemas de SMS. Os códigos de erro são expostos através do campo "DeliveryStatusDetails" no relatório de entrega por SMS.
| Código de erro | Description | Ação a executar |
|---|---|---|
| 2000 | Mensagem entregue com sucesso | |
| 4000 | A mensagem é rejeitada devido à deteção de fraude | Certifique-se de que não está a exceder o número máximo de mensagens permitido para o seu número |
| 4001 | A mensagem é rejeitada devido ao formato de número de origem/de origem inválido | Verifique se o número Para está no formato E.164 e se o formato de número De está no formato E.164 ou no formato de código curto |
| 4002 | A mensagem é rejeitada devido ao formato de número Destino/Para inválido | Verifique se o número Para está no formato E.164 |
| 4003 | Falha na entrega da mensagem devido ao destino não suportado | Verifique se o destino para o qual está a tentar enviar é suportado |
| 4004 | Falha na entrega da mensagem porque o número de destino/para não existe | Verifique se o número Para para o qual você está enviando é válido |
| 4005 | A mensagem está bloqueada pela operadora de destino | |
| 4006 | O número Destino/Para não está acessível | Tente reenviar a mensagem mais tarde |
| 4007 | O número de destino/para optou por não receber mensagens suas | Marque o número Destino/Para como excluído para que nenhuma outra tentativa de mensagem seja feita para o número |
| 4008 | Excedeu o número máximo de mensagens permitido para o seu perfil | Certifique-se de que não está a exceder o número máximo de mensagens permitido para o seu número ou utilize filas para agrupar as mensagens |
| 4009 | A mensagem é rejeitada pelo Microsoft Entitlement System | Na maioria das vezes, isso acontece se a atividade fraudulenta for detetada. Entre em contato com o suporte para obter mais detalhes |
| 4010 | A mensagem foi bloqueada devido ao número gratuito não estar a ser verificado | Revise os limites de envio não verificados e envie a verificação gratuita o mais rápido possível |
| 5000 | Falha na entrega da mensagem. Entre em contato com a equipe de suporte da Microsoft para obter mais detalhes | Apresentar um pedido de suporte através do portal do Azure |
| 5001 | Falha na entrega da mensagem devido à indisponibilidade temporária do aplicativo/sistema | |
| 5002 | A transportadora não suporta o relatório de entrega | Na maioria das vezes, isso acontece se uma transportadora não oferece suporte a relatórios de entrega. Nenhuma ação necessária, pois a mensagem pode já ter sido entregue. |
| 9999 | Falha na entrega da mensagem devido a erro/falha desconhecido | Tente reenviar a mensagem |
Informações relacionadas
- Logs de acesso para voz e vídeo, chat, e-mail, travessia de rede, gravação, SMS e automação de chamadas.
- APIs de nome de arquivo de log para chamar o SDK
- Métricas
- Limites do serviço