Analizzare una conversazione utilizzando l'API

Le conversazioni possono essere visualizzate in Customer Experience Insights dopo la creazione di un oggetto conversazione corrispondente. Questa guida illustrativa ti illustra la procedura per analizzare una conversazione utilizzando l'API REST. Se preferisci, puoi eseguire queste azioni anche utilizzando la console CX Insights.

Prerequisiti

1. Abilita le API Cloud Storage e Insights nel tuo Google Cloud progetto.
2. Importa i dati delle conversazioni.

Conversazione in chat

1. Importa la trascrizione della chat della conversazione come un oggetto nel bucket Cloud Storage.

2. Prendi nota del percorso dell'oggetto, con il formato gs://<bucket>/<object>.

Il file di trascrizione della chat deve essere fornito come file in formato JSON che corrisponda al formato dei dati delle conversazioni CCAI.

Conversazione vocale

1. Importa tutti i file da un bucket Cloud Storage. I file audio e di trascrizione devono essere importati come oggetti nel bucket Cloud Storage.

2. Prendi nota dei due percorsi degli oggetti, con il formato gs://<bucket>/<object>.

I file di trascrizione devono essere il risultato restituito da una trascrizione dell'API Cloud Speech-to-Text. In particolare, devono corrispondere alla risposta restituita dal riconoscimento audio, che è identica per il riconoscimento sincrono e il riconoscimento asincrono in tutte le versioni dell'API Speech-to-Text. Altri formati di trascrizione non sono supportati e genereranno un errore durante l'analisi della conversazione.

Nota: è supportato solo l'audio a due canali. In caso contrario, si verifica un errore durante l'analisi della conversazione.

Analizzare una conversazione

Una volta creato un oggetto Conversation in CX Insights, deve essere analizzato per produrre risultati utili. Una singola conversazione può essere analizzata più volte e ogni analisi separata crea un nuovo oggetto Analysis.

Un'analisi esegue una serie di annotatori sui dati delle conversazioni e restituisce i risultati nella risposta. Per impostazione predefinita, l'analisi eseguirà tutti gli annotatori disponibili. Se vuoi, puoi configurare l'analisi in modo che esegua solo gli annotatori specificati.

Un'analisi è un'operazione a lunga esecuzione. La chiamata al metodo CreateAnalysis crea un oggetto Operation che rappresenta il processo a lunga esecuzione. Al termine dell'operazione, l'oggetto Operation contiene il risultato. Puoi eseguire il polling dell'oggetto Operation per verificare il completamento.

Nota: se il campo languageCode non è impostato, CX Insights lo dedurrà automaticamente. Per le analisi è supportata solo la lingua inglese (tutti i dialetti).

Creare una nuova analisi

Autorizzazioni richieste per questa attività

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni:

• contactcenterinsights.analyses.create

REST

Per informazioni complete, consulta l'endpoint API conversations.analyses:create.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: l' Google Cloud ID progetto.
• CONVERSATION_ID: l'ID della conversazione che vuoi analizzare. Questo valore è stato restituito nella risposta `createConversation`.

Nota: tutti gli esempi utilizzano l'istanza globale di Customer Experience Insights. Per istruzioni sull'utilizzo delle istanze regionali, consulta Regionalizzazione.

Metodo HTTP e URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

Per eseguire l'autenticazione in CX Insights, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

Per eseguire l'autenticazione in CX Insights, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

Per eseguire l'autenticazione in CX Insights, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createAnalysis() {
  try {
    const [operation] = await client.createAnalysis({
      parent: conversationName,
    });

    // Wait for the operation to complete.
    const [analysis] = await operation.promise();
    console.info(`Created ${analysis.name}`);
  } catch (err) {
    console.error(`createAnalysis failed: ${JSON.stringify(err, null, 2)}`);
    process.exitCode = 1;
  }
}
createAnalysis();

(Facoltativo) Configurare un'analisi

Autorizzazioni richieste per questa attività

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni:

• contactcenterinsights.analyses.create

REST

Per informazioni complete, consulta l'endpoint API conversations.analyses:create. Includi tutti gli annotatori che vuoi eseguire nell'oggetto annotatorSelector e impostali su true. Per impostazione predefinita, tutti gli annotatori non inclusi saranno impostati su false. Se non specifichi annotatori nell'oggetto annotatorSelector, verranno eseguiti tutti gli annotatori.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: l' Google Cloud ID progetto.
• PHRASE_MATCHER(s): i nomi completi delle risorse di corrispondenza di frasi delle corrispondenze di frasi che vuoi utilizzare per l'annotatore di corrispondenza di frasi. Se viene lasciato vuoto, verranno eseguite tutte le corrispondenze di frasi attive.
• ISSUE_MODEL(s): i nomi completi delle risorse dei modelli di problemi che vuoi utilizzare per l'annotatore del modello di problemi. Funziona solo se run_issue_model_annotator è true. Se viene lasciato vuoto, verranno eseguiti tutti i modelli di problemi di cui è stato eseguito il deployment. Al momento è limitato a 1 modello di cui è stato eseguito il deployment.

Nota: tutti gli esempi utilizzano l'istanza globale di Customer Experience Insights. Per istruzioni sull'utilizzo delle istanze regionali, consulta Regionalizzazione.

Metodo HTTP e URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses

Corpo JSON della richiesta:

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Eseguire il polling dell'operazione

La creazione di un'analisi restituisce un'operazione a lunga esecuzione. I metodi a lunga esecuzione sono asincroni e l'operazione potrebbe non essere completata quando il metodo restituisce una risposta. Puoi eseguire il polling dell'operazione per verificarne lo stato. Per dettagli ed esempi di codice, consulta la pagina Operazioni a lunga esecuzione.