Risoluzione dei problemi in Servizi di comunicazione di Azure

Articolo
08/12/2024

Questo documento consente di risolvere i problemi che potrebbero 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 altre informazioni, vedere la pagina sul supporto dedicato e sulle opzioni della Guida.

Per risolvere determinati problemi, potrebbe essere necessario disporre di una o più delle informazioni seguenti:

IDMS-CV: risolvere i problemi relativi a chiamate e messaggi.
ID chiamata: identificare le chiamate di Servizi di comunicazione.
ID messaggio SMS: identificare i messaggi SMS.
ID brief di programma di codice breve: identificare un'applicazione brief di programma di codice breve.
ID brief della campagna di verifica con numero verde: identificare un'applicazione brief della campagna di verifica con numero verde.
ID messaggio e-mail: identificare le richieste di e-mail di invio.
ID correlazione: identificare le richieste effettuate tramite Automazione chiamate.
Registri chiamate: 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 Limiti del servizio.

Accedere all'ID MS-CV

È possibile accedere all'ID MS-CV configurando la diagnostica nell'istanza dell'oggetto clientOptions durante l'inizializzazione degli SDK. È possibile configurare la diagnostica 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 si abilita la diagnostica per gli SDK, i dettagli di diagnostica possono essere generati nel listener di eventi configurato:

C#
Python

// 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) });

from azure.communication.chat import ChatClient, CommunicationUserCredential
endpoint = "https://communication-services-sdk-live-tests-for-python.communication.azure.com"
chat_client = ChatClient(
    endpoint,
    CommunicationUserCredential(token),
    http_logging_policy=your_logging_policy)

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 seguenti.

Dall'intestazione della risposta API individuare il campo X-Ms-Skype-Chain-Id.
Dagli eventi di callback, l'applicazione riceve dopo l'esecuzione di un'azione. Ad esempio CallConnected o PlayFailed, individuare il valore correlationID.

Oltre a uno di questi ID, è necessario fornire informazioni dettagliate sul caso d'uso con errori e sul timestamp in cui si è verificato l'errore.

Accedere all'ID chiamata client

Durante la risoluzione dei problemi relativi alle chiamate vocali o video, potrebbe essere necessario fornire un call ID. Accedere a questo valore tramite la proprietà id dell'oggetto call:

// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)

// The `call id` property can be retrieved by calling the `call.getCallId()` method on a call object after a call ends
// todo: the code snippet suggests it's a property while the comment suggests it's a method call
print(call.callId)

// The `call id` property can be retrieved by calling the `call.getCallId()` method on a call object after a call ends
// `call` is an instance of a call created by `callAgent.startCall(…)` or `callAgent.join(…)` methods
Log.d(call.getCallId())

Accedere all'ID del messaggio SMS

Per i problemi relativi agli SMS, è possibile ottenere l'ID del messaggio dall'oggetto risposta.

.NET

// 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

Trovare l'ID breve del programma nel portale di Azure nella sezione Codici brevi.

Screenshot che mostra un breve ID programma di codice.

Accedere all'ID breve della campagna di verifica gratuita

Trovare l'ID breve del programma nel portale di Azure nella sezione Documenti normativi.

Screenshot che mostra un ID breve della campagna di verifica gratuita.

Accedere all'ID operazione di e-mail

Durante la risoluzione dei problemi relativi all'invio di richieste di stato di messaggi di e-mail o di e-mail, potrebbe essere necessario fornire un operation ID. È possibile accedere a questo valore nella risposta:

.NET

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 accedere ai file di log. Questi file possono essere utili per gli specialisti e i tecnici del supporto Microsoft. È consigliabile raccogliere questi log quando si rileva un problema.

Abilitare e accedere ai registri chiamate

[JavaScript]

Azure Communication Services Calling SDK si basa internamente sulla libreria di @azure/logger per controllare la registrazione.

Usare il metodo setLogLevel del pacchetto @azure/logger per configurare il livello di output del log. Creare un logger e passarlo al costruttore CallClient come indicato di seguito:

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 metodo AzureLogger.log:

È 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ò influisce negativamente 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); 
};

SDK nativo (Android/iOS)

Per Android, iOS e Windows, l'SDK per chiamate di Servizi di comunicazione di Azure offre l'accesso ai file di log.

Per le chiamate agli SDK nativi, 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 sulle funzioni di supporto del modulo supporto dell'interfaccia utente chiamante, vedere l'esercitazione 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 descrive il percorso per l'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 ai clienti è 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:

Andare al portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro a sinistra 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:

Andare al portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro a sinistra selezionare Microsoft Entra ID.
In 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:

Andare al portale di Azure e accedere al portale di Azure usando le credenziali.
Nel riquadro a sinistra 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:

Andare al portale di Azure e accedere al portale di Azure usando le credenziali.
Aprire la risorsa del Servizio di comunicazione.
Nel riquadro sinistro selezionare Panoramicae andare a una vista JSON
Nella pagina JSON risorsa copiare il valore immutableResourceId e specificarlo al team di supporto.

Verifica dell'idoneità delle licenze di Teams per l'uso del supporto di Servizi di comunicazione di Azure per gli utenti di Teams

Esistono due modi per verificare l'idoneità della licenza di Teams per usare il supporto di Servizi di comunicazione di Azure 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 andare 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 dominio https://teams.microsoft.com/, la licenza di Teams è idonea. Se l'autenticazione non riesce o si viene reindirizzati al dominio https://teams.live.com/v2/, la licenza di Teams non è idonea per l'uso del supporto di Servizi di comunicazione di Azure 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 andare 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}/licenseDetails
```

Il riquadro Anteprima risposta visualizza l'output come indicato di seguito:

L'oggetto risposta illustrato di seguito 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à servicePlanName ha uno dei valori nella tabella Licenze di Teams idonee

Condividi tramite

Risoluzione dei problemi in Servizi di comunicazione di Azure

Visualizzazione delle informazioni della Guida

Accedere all'ID MS-CV

Esempio di opzioni client

ID di accesso necessari per l'automazione delle chiamate

Accedere all'ID chiamata client

Accedere all'ID del messaggio SMS

Accedere all'ID breve del programma di codice breve

Accedere all'ID breve della campagna di verifica gratuita

Accedere all'ID operazione di e-mail

Accesso ai file di supporto in Calling SDK

Abilitare e accedere ai registri chiamate

[JavaScript]

SDK nativo (Android/iOS)

Librerie dell'interfaccia utente (Android, iOS)

Compilazione di flussi di supporto end-to-end nelle integrazioni ACS

Ricerca di informazioni su Microsoft Entra

Recupero dell'ID directory

Recupero dell'ID applicazione

Recupero dell'ID utente

Recupero dell'ID risorsa non modificabile

Verifica dell'idoneità delle licenze di Teams per l'uso del supporto di Servizi di comunicazione di Azure per gli utenti di Teams

Verifica tramite il client Web di Teams

Verifica della licenza corrente di Teams tramite l'API Microsoft Graph

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Risoluzione dei problemi in Servizi di comunicazione di Azure

Visualizzazione delle informazioni della Guida

Accedere all'ID MS-CV

Esempio di opzioni client

ID di accesso necessari per l'automazione delle chiamate

Accedere all'ID chiamata client

Accedere all'ID del messaggio SMS

Accedere all'ID breve del programma di codice breve

Accedere all'ID breve della campagna di verifica gratuita

Accedere all'ID operazione di e-mail

Accesso ai file di supporto in Calling SDK

Abilitare e accedere ai registri chiamate

[JavaScript]

SDK nativo (Android/iOS)

Librerie dell'interfaccia utente (Android, iOS)

Compilazione di flussi di supporto end-to-end nelle integrazioni ACS

Ricerca di informazioni su Microsoft Entra

Recupero dell'ID directory

Recupero dell'ID applicazione

Recupero dell'ID utente

Recupero dell'ID risorsa non modificabile

Verifica dell'idoneità delle licenze di Teams per l'uso del supporto di Servizi di comunicazione di Azure per gli utenti di Teams

Verifica tramite il client Web di Teams

Verifica della licenza corrente di Teams tramite l'API Microsoft Graph

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive