Risoluzione dei problemi in Servizi di comunicazione di Azure
Questo documento consente di risolvere i problemi che possono verificarsi all'interno della soluzione servizi di comunicazione. Per la risoluzione dei problemi del servizio SMS, è possibile abilitare la creazione di report di recapito con Griglia di eventi per acquisire i dettagli di recapito SMS.
Visualizzazione delle informazioni della Guida
Invitiamo gli sviluppatori a inviare domande, suggerire funzionalità e segnalare problemi come problemi. Per facilitare l'assistenza, abbiamo una pagina dedicata di supporto e opzioni della Guida che elenca le opzioni per il supporto.
Per poter risolvere determinati tipi di problemi, è possibile che vengano richieste le informazioni seguenti:
- ID MS-CV: questo ID viene usato per risolvere i problemi relativi alle chiamate e ai messaggi.
- ID chiamata: questo ID viene usato per identificare le chiamate di Servizi di comunicazione.
- ID messaggio SMS: questo ID viene usato per identificare i messaggi SMS.
- Short Code Program Brief ID (BREVE ID programma di codice breve): questo ID viene usato per identificare un breve programma di codice breve applicazione.
- ID breve della campagna di verifica gratuita: questo ID viene usato per identificare una breve applicazione per la campagna di verifica a pagamento.
- ID messaggio di posta elettronica: questo ID viene usato per identificare le richieste di posta elettronica di invio.
- ID correlazione: questo ID viene usato per identificare le richieste effettuate tramite Automazione chiamate.
- Log delle chiamate: questi log contengono informazioni dettagliate che possono essere usate per risolvere i problemi di chiamata e di rete.
Per altre informazioni sulla limitazione e sulle limitazioni, vedere anche la documentazione relativa ai limiti del servizio.
Accedere all'ID MS-CV
È possibile accedere all'ID MS-CV configurando la diagnostica nell'istanza dell'oggetto durante l'inizializzazione clientOptions degli SDK. La diagnostica può essere configurata per qualsiasi SDK di Azure, tra cui chat, identità e chiamate VoIP.
Esempio di opzioni client
I frammenti di codice seguenti illustrano la configurazione della diagnostica. Quando gli SDK vengono usati con la diagnostica abilitata, i dettagli di diagnostica possono essere generati nel listener di eventi configurato:
// 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) });
ID di accesso necessari per l'automazione delle chiamate
Quando si risovono problemi con Call Automation SDK, ad esempio la gestione delle chiamate o i problemi di registrazione, è necessario raccogliere gli ID che consentono di identificare la chiamata o l'operazione non riuscita. È possibile specificare uno dei due ID indicati qui.
Dall'intestazione della risposta API individuare il campo
X-Ms-Skype-Chain-Id.
Dagli eventi di callback ricevuti dall'applicazione dopo l'esecuzione di un'azione. Ad esempio
CallConnectedoPlayFailed, individuare il valore correlationID.
Oltre a uno di questi ID, specificare i dettagli sul caso d'uso con errori e il timestamp per il momento in cui è stato osservato l'errore.
Accedere all'ID chiamata client
Durante la risoluzione dei problemi relativi alle chiamate vocali o video, potrebbe essere richiesto di fornire un oggetto call ID. È possibile accedere a questo valore tramite la id proprietà dell'oggetto call :
// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)
Accedere all'ID del messaggio SMS
Per i problemi relativi agli SMS, è possibile ottenere l'ID del messaggio dall'oggetto risposta.
// 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
}
Accedere all'ID breve del programma di codice breve
L'ID breve del programma è disponibile nella portale di Azure nel pannello Codici brevi.
Accedere all'ID breve della campagna di verifica gratuita
L'ID breve del programma è disponibile nella portale di Azure nel pannello Documenti normativi.
Accedere all'ID operazione di posta elettronica
Durante la risoluzione dei problemi relativi all'invio di richieste di stato di messaggi di posta elettronica o messaggi di posta elettronica, potrebbe essere richiesto di fornire un oggetto operation ID. È possibile accedere a questo valore nella risposta:
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}");
Accesso ai file di supporto in Calling SDK
La chiamata all'SDK fornisce metodi pratici per ottenere l'accesso ai file di log. Questi file possono essere utili per gli specialisti e i tecnici del supporto Microsoft. È consigliabile raccogliere attivamente questi log quando vengono rilevati problemi.
Abilitare e accedere ai log delle chiamate
[JavaScript]
Servizi di comunicazione di Azure Calling SDK si basa internamente sulla libreria @azure/logger per controllare la registrazione.
Usare il setLogLevel metodo del @azure/logger pacchetto per configurare il livello di output del log. Creare un logger e passarlo al costruttore CallClient:
import { setLogLevel, createClientLogger, AzureLogger } from '@azure/logger';
setLogLevel('verbose');
let logger = createClientLogger('ACS');
const callClient = new CallClient({ logger });
È possibile usare AzureLogger per reindirizzare l'output di registrazione dagli SDK di Azure eseguendo l'override del AzureLogger.log metodo : è possibile accedere alla console del browser, un file, un buffer, inviare al proprio servizio e così via. Se si intende inviare log in rete al proprio servizio, non inviare una richiesta per riga di log perché ciò influirà sulle prestazioni del browser. Accumulare invece le righe dei log e inviarle in batch.
// Redirect log output
AzureLogger.log = (...args) => {
// To console, file, buffer, REST API, etc...
console.log(...args);
};
Native SDK (Android/iOS)
Per Android, iOS e Windows, Servizi di comunicazione di Azure Calling SDK offre l'accesso ai file di log.
Per chiamare Native SDK, vedere le esercitazioni sull'accesso ai file di log
Librerie dell'interfaccia utente (Android, iOS)
Se si usano le librerie dell'interfaccia utente di Servizi di comunicazione di Azure per Android o iOS, è possibile richiedere commenti e suggerimenti degli utenti tramite il modulo di supporto predefinito.
Per altre informazioni su come usare la funzionalità di supporto del modulo Di supporto dell'interfaccia utente chiamante, vedere l'esercitazione sull'integrazione del modulo di supporto. Questo documento illustra come aggiungere il gestore eventi necessario e creare un'implementazione client/server di base per l'archiviazione centralizzata delle informazioni di supporto. Questa guida è progettata per guidare l'utente nel percorso verso un'integrazione con i servizi di supporto usati dall'organizzazione.
Compilazione di flussi di supporto end-to-end nelle integrazioni ACS
Sia che si usi l'SDK per chiamate o l'SDK dell'interfaccia utente chiamante, fornire supporto agli utenti finali è un componente chiave di qualsiasi integrazione affidabile. Nel documento seguente vengono evidenziate le considerazioni chiave in ogni punto del ciclo di feedback del supporto e vengono forniti punti di partenza per altre informazioni.
Fornire supporto per gli utenti
Ricerca di informazioni su Microsoft Entra
- Recupero dell'ID directory
- Recupero dell'ID applicazione
- Recupero dell'ID utente
Recupero dell'ID directory
Per trovare l'ID directory (tenant), seguire questa procedura:
Passare a portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro sinistro selezionare Microsoft Entra ID.
Nella pagina Panoramica in Microsoft Entra ID copiare l'ID directory (tenant) e archiviarlo nel codice dell'applicazione.
Recupero dell'ID applicazione
Per trovare l'ID applicazione, seguire questa procedura:
Passare a portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro sinistro selezionare Microsoft Entra ID.
Da Registrazioni app in Microsoft Entra ID selezionare l'applicazione.
Copiare l'ID applicazione e archiviarlo nel codice dell'applicazione.
L'ID directory (tenant) è disponibile anche nella pagina di panoramica dell'applicazione.
Recupero dell'ID utente
Per trovare l'ID utente, seguire questa procedura:
Passare a portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro sinistro selezionare Microsoft Entra ID.
In Utenti in Microsoft Entra ID selezionare l'utente.
Nella pagina Profilo degli utenti di Microsoft Entra copiare l'ID oggetto e archiviarlo nel codice dell'applicazione.
Recupero dell'ID risorsa non modificabile
In alcuni casi è anche necessario specificare l'ID risorsa non modificabile della risorsa del servizio di comunicazione. Per trovarla, seguire questa procedura:
- Passare a portale di Azure e accedere al portale di Azure usando le credenziali.
- Aprire la risorsa del servizio di comunicazione.
- Nel riquadro sinistro selezionare Panoramica e passare a una visualizzazione JSON
- Nella pagina Resource JSON copiare il
immutableResourceIdvalore e specificarlo al team di supporto.
Verifica dell'idoneità alla licenza di Teams per l'uso di Servizi di comunicazione di Azure supporto per gli utenti di Teams
Esistono due modi per verificare l'idoneità alla licenza di Teams per usare Servizi di comunicazione di Azure supporto per gli utenti di Teams:
- Verifica tramite il client Web di Teams
- Verifica della licenza corrente di Teams tramite l'API Microsoft Graph
Verifica tramite il client Web di Teams
Per verificare l'idoneità della licenza di Teams tramite il client Web di Teams, seguire questa procedura:
- Aprire il browser e passare al client Web di Teams.
- Accedere con le credenziali con una licenza di Teams valida.
- Se l'autenticazione ha esito positivo e si rimane nel https://teams.microsoft.com/ dominio, la licenza di Teams è idonea. Se l'autenticazione non riesce o si viene reindirizzati al https://teams.live.com/v2/ dominio, la licenza di Teams non è idonea per l'uso Servizi di comunicazione di Azure supporto per gli utenti di Teams.
Verifica della licenza corrente di Teams tramite l'API Microsoft Graph
È possibile trovare la licenza corrente di Teams usando l'API Microsoft Graph licenseDetails che restituisce le licenze assegnate a un utente. Seguire questa procedura per usare lo strumento Graph Explorer per visualizzare le licenze assegnate a un utente:
Aprire il browser e passare a Graph Explorer
Accedere a Graph Explorer usando le credenziali.
Nella casella query immettere l'API seguente e fare clic su Esegui query :
https://graph.microsoft.com/v1.0/me/licenseDetails
In alternativa, è possibile eseguire una query per un determinato utente specificando l'ID utente usando l'API seguente:
https://graph.microsoft.com/v1.0/users/{id}/licenseDetailsIl riquadro Anteprima risposta visualizza l'output come indicato di seguito:
Si noti che l'oggetto risposta illustrato qui potrebbe essere abbreviato per la leggibilità.
{ "@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" } ] } ] }Trovare i dettagli delle licenze in cui la proprietà
servicePlanNameha uno dei valori nella tabella Licenze di Teams idonee
Codici di errore dell'SDK per chiamate
Il Servizi di comunicazione di Azure Calling SDK usa i codici di errore seguenti per risolvere i problemi di chiamata. Questi codici di errore vengono esposti tramite la proprietà call.callEndReason al termine di una chiamata.
| Codice errore | Descrizione | Azione da eseguire |
|---|---|---|
| 403 | Accesso negato/Errore di autenticazione. | Verificare che il token di Servizi di comunicazione sia valido e non scaduto. |
| 404 | Chiamata non trovata. | Verificare che il numero che si sta chiamando (o la chiamata a cui ci si sta aggiungendo) esista. |
| 408 | Timeout del controller di chiamata. | Si è verificato il timeout del controller di chiamata durante l'attesa dei messaggi di protocollo dagli endpoint utente. Verificare che i client siano connessi e disponibili. |
| 410 | Errore dello stack multimediale locale o dell'infrastruttura multimediale. | Assicurarsi di usare l'SDK più recente in un ambiente supportato. |
| 430 | Non è possibile recapitare messaggi all'applicazione client. | Verificare che l'applicazione client sia in esecuzione e disponibile. |
| 480 | Endpoint client remoto non registrato. | Assicurarsi che l'endpoint remoto sia disponibile. |
| 481 | Non è stato possibile gestire la chiamata in ingresso. | Inviare una richiesta di supporto tramite il portale di Azure. |
| 487 | Chiamata annullata, rifiutata a livello locale, terminata a causa di un problema di corrispondenza dell'endpoint oppure generazione dell'offerta multimediale non riuscita. | Comportamento previsto. |
| 490, 491, 496, 497, 498 | Problemi di rete dell'endpoint locale. | Controllare la rete. |
| 500, 503, 504 | Errore dell'infrastruttura di Servizi di comunicazione. | Inviare una richiesta di supporto tramite il portale di Azure. |
| 603 | Chiamata rifiutata a livello globale dal partecipante di Servizi di comunicazione remota | Comportamento previsto. |
Codici di errore di Automation SDK
I codici di errore seguenti vengono esposti da Call Automation SDK.
| Codice di errore | Descrizione | Azioni da intraprendere |
|---|---|---|
| 400 | Richiesta non valida | La richiesta di input non è valida. Esaminare il messaggio di errore per determinare quale input non è corretto. |
| 400 | Riproduzione non riuscita | Assicurarsi che il file audio sia WAV, 16KHz, Mono e assicurarsi che l'URL del file sia accessibile pubblicamente. |
| 400 | Riconoscimento non riuscito | Controllare il messaggio di errore. Il messaggio evidenzia se l'errore è dovuto al timeout raggiunto o se l'operazione è stata annullata. Per altre informazioni sui codici di errore e i messaggi, vedere la guida pratica per raccogliere l'input dell'utente. |
| 401 | Non autorizzata | Autenticazione HMAC non riuscita. Verificare se il stringa di connessione usato per creare CallAutomationClient è corretto. |
| 403 | Non consentito | La richiesta è vietata. Assicurarsi di avere accesso alla risorsa a cui si sta tentando di accedere. |
| 404 | Resource not found | La chiamata su cui si sta tentando di agire non esiste. Ad esempio, il trasferimento di una chiamata già disconnessa. |
| 429 | Numero eccessivo di richieste | Riprovare dopo un ritardo suggerito nell'intestazione Retry-After, quindi eseguire il backoff in modo esponenziale. |
| 500 | Errore interno del server | Riprovare dopo un ritardo. Se persiste, generare un ticket di supporto. |
| 500 | Riproduzione non riuscita | Inviare una richiesta di supporto tramite il portale di Azure. |
| 500 | Riconoscimento non riuscito | Controllare il messaggio di errore e verificare che il formato del file audio sia valido (WAV, 16KHz, Mono), se il formato di file è valido, inviare una richiesta di supporto tramite portale di Azure. |
| 502 | Gateway non valido | Riprovare dopo un ritardo con un nuovo client HTTP. |
Prendere in considerazione i suggerimenti seguenti per la risoluzione di determinati problemi.
- L'applicazione non riceve l'evento Griglia di eventi IncomingCall: assicurarsi che l'endpoint dell'applicazione sia stato convalidato con Griglia di eventi al momento della creazione della sottoscrizione di eventi. Lo stato del provisioning per la sottoscrizione di eventi viene contrassegnato come completato se la convalida ha avuto esito positivo.
- Recupero dell'errore 'The field CallbackUri is invalid': Call Automation does not support HTTP endpoints. Assicurarsi che l'URL di callback fornito supporti HTTPS.
- L'azione PlayAudio non riproduce nulla: attualmente è supportato solo il formato di file Wave (.wav) per i file audio. Il contenuto audio nel file wave deve essere mono (canale singolo), campioni a 16 bit con una frequenza di campionamento di 16.000 (16 KHz).
- Le azioni sugli endpoint PSTN non funzionano: CreateCall, Transfer, AddParticipant e Redirect to phone numbers richiedono di impostare SourceCallerId nella richiesta di azione. A meno che non si usi l'instradamento diretto, l'ID chiamante di origine deve essere un numero di telefono di proprietà della risorsa di Servizi di comunicazione affinché l'azione abbia esito positivo.
Fare riferimento a questo articolo per informazioni su eventuali problemi noti rilevati dal team del prodotto.
Codici di errore di Chat SDK
Servizi di comunicazione di Azure Chat SDK usa i codici di errore seguenti per risolvere i problemi di chat. I codici di errore vengono esposti tramite la error.code proprietà nella risposta di errore.
| Codice errore | Descrizione | Azione da eseguire |
|---|---|---|
| 401 | Non autorizzata | Verificare che il token di Servizi di comunicazione sia valido e non scaduto. |
| 403 | Non consentito | Assicurarsi che l'iniziatore della richiesta abbia accesso alla risorsa. |
| 429 | Numero eccessivo di richieste | Assicurarsi che l'applicazione lato client gestisca questo scenario in modo intuitivo. Se l'errore persiste, inviare una richiesta di supporto. |
| 503 | Servizio non disponibile | Inviare una richiesta di supporto tramite il portale di Azure. |
Codici di errore SMS
L Servizi di comunicazione di Azure SMS SDK usa i codici di errore seguenti per risolvere i problemi relativi agli SMS. I codici di errore vengono esposti tramite il campo "DeliveryStatusDetails" nel report di recapito SMS.
| Codice errore | Descrizione | Azione da eseguire |
|---|---|---|
| 2000 | Messaggio recapitato correttamente | |
| 4000 | Il messaggio viene rifiutato a causa del rilevamento delle frodi | Assicurarsi di non superare il numero massimo di messaggi consentiti per il numero |
| 4001 | Il messaggio viene rifiutato a causa di un formato di origine/da numero non valido | Verificare che il formato A numero sia in formato E.164 e Da formato numerico sia in formato E.164 o Codice breve |
| 4002 | Il messaggio viene rifiutato a causa di un formato di destinazione/numero non valido | Verificare che il numero A sia in formato E.164 |
| 4003 | Messaggio non recapitabile a causa di una destinazione non supportata | Controllare se la destinazione a cui si sta tentando di inviare è supportata |
| 4004 | Impossibile recapitare il messaggio perché il numero di destinazione/a non esiste | Verificare che il numero a cui si sta inviando sia valido |
| 4005 | Il messaggio è bloccato dal gestore telefonico di destinazione | |
| 4006 | Il numero Destinazione/A non è raggiungibile | Provare a inviare nuovamente il messaggio in un secondo momento |
| 4007 | Il numero Destinazione/A ha rifiutato esplicitamente di ricevere messaggi dall'utente | Contrassegnare il numero destinazione/a come rifiutare esplicitamente in modo che non vengano eseguiti ulteriori tentativi di messaggio al numero |
| 4008 | È stato superato il numero massimo di messaggi consentiti per il profilo | Assicurarsi di non superare il numero massimo di messaggi consentiti per il numero o usare le code per inviare in batch i messaggi |
| 4009 | Il messaggio viene rifiutato dal sistema di diritti Microsoft | Spesso ciò si verifica se viene rilevata un'attività fraudolenta. Per altre informazioni, contattare il supporto tecnico |
| 4010 | Il messaggio è stato bloccato a causa del numero verde non verificato | Esaminare i limiti di invio non verificati e inviare la verifica senza pedaggio il prima possibile |
| 5000 | Impossibile recapitare il messaggio. Per altri dettagli, contattare il team di supporto Microsoft | Inviare una richiesta di supporto tramite il portale di Azure |
| 5001 | Messaggio non recapitabile a causa dell'indisponibilità temporanea dell'applicazione/del sistema | |
| 5002 | Il vettore non supporta il rapporto di recapito | Spesso ciò si verifica se un vettore non supporta i report di recapito. Nessuna azione necessaria perché il messaggio potrebbe essere già stato recapitato. |
| 9999 | Impossibile recapitare il messaggio a causa di un errore o un errore sconosciuto | Provare a inviare nuovamente il messaggio |
Informazioni correlate
- Accedere ai log per voce e video, chat, posta elettronica, registrazione, SMS e automazione delle chiamate.
- API del nome file di log per l'SDK per chiamate
- Metriche
- Limiti del servizio