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 pratica ti illustra il processo di analisi di 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 progetto Google Cloud .
2. Importa i dati delle conversazioni.

Conversazione in chat

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

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

Il file della trascrizione della chat deve essere fornito come file in formato JSON che corrisponda al formato dei dati della conversazione 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 di una trascrizione dell'API Cloud Speech-to-Text. Nello specifico, devono corrispondere alla risposta restituita dal riconoscimento audio, che è identica per il riconoscimento sincrono e asincrono in tutte le versioni dell'API Speech-to-Text. Gli 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 della conversazione 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 vengano eseguiti 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 esecuzione prolungata. Al termine dell'operazione, l'oggetto Operation contiene il risultato. Puoi eseguire il polling dell'oggetto Operation per verificare il completamento.

Nota: se il languageCode campo 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 dettagliate, consulta l'endpoint API conversations.analyses:create.

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

• PROJECT_ID: il tuo ID progetto Google Cloud .
• 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. Consulta la sezione Regionalizzazione per istruzioni sull'utilizzo delle istanze regionali.

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() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
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 dettagliate, consulta l'endpoint API conversations.analyses:create. Includi gli annotatori che vuoi eseguire nell'oggetto annotatorSelector e impostali su true. Gli annotatori non inclusi verranno impostati su false per impostazione predefinita. 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: il tuo ID progetto Google Cloud .
• PHRASE_MATCHER(s): I nomi delle risorse di corrispondenza a frase completi dei matcher di frasi che vuoi utilizzare per l'annotatore di corrispondenza a frase. Se viene lasciato vuoto, verranno eseguiti tutti i corrispondenze a frase attivi.
• ISSUE_MODEL(s): I nomi completi delle risorse dei modelli di problemi che vuoi utilizzare per l'annotatore di modelli di problemi. Funziona solo se run_issue_model_annotator è true. Se lasciato vuoto, verranno eseguiti tutti i modelli di problemi implementati. Al momento è limitato a un modello di cui è stato eseguito il deployment.

Nota:tutti gli esempi utilizzano l'istanza globale di Customer Experience Insights. Consulta la sezione Regionalizzazione per istruzioni sull'utilizzo delle istanze regionali.

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"
}

Esegui il sondaggio dell'operazione

La creazione di un'analisi restituisce un'operazione a lunga esecuzione. I metodi a esecuzione prolungata 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 delle operazioni di lunga durata.