Exportar conversaciones a BigQuery

CX Insights te permite exportar tus datos de conversación y análisis de CX Insights a BigQuery para que puedas realizar tus propias consultas sin procesar. El proceso de exportación escribe un esquema similar al marco de trabajo de Speech Analysis. En esta guía, se detalla el proceso de exportación.

Crea una tabla y un conjunto de datos nuevos de BigQuery

El exportador de CX Insights requiere una tabla de BigQuery para que la operación se realice correctamente. Si no tienes una tabla de destino, usa este ejemplo para crear una tabla y un conjunto de datos nuevos con la herramienta de línea de comandos de bq. Consulta la documentación del esquema de BigQuery para obtener información sobre el esquema de salida y las definiciones de las columnas.

BigQuery tiene algunas restricciones sobre la ubicación de su fuente de datos. Consulta Consideraciones sobre la ubicación. Las restricciones que se aplican a los buckets de Cloud Storage también se aplican a CX Insights. Por ejemplo, si tu conjunto de datos de BigQuery se encuentra en la ubicación multirregional EU, solo puedes exportar datos de CX Insights desde una de las ubicaciones europe-*.

Advertencia: La exportación de CX Insights truncará los datos de la tabla proporcionada antes de escribir.

bq mk --dataset --location=LOCATION PROJECT:DATASET

bq mk --table PROJECT:DATASET.TABLE

Exporta datos de conversaciones a BigQuery

La herramienta de exportación admite el filtrado y la escritura de datos en tablas protegidas por claves de encriptación administradas por el cliente (CMEK). Si no quieres habilitar esta función, puedes avanzar y exportar tus datos a BigQuery.

Agrega filtrado a la solicitud (opcional)

La exportación a BigQuery es compatible con todas las combinaciones de filtros que se pueden aplicar a las consultas de conversaciones. Por ejemplo, la siguiente muestra exportará todas las conversaciones con 10 o más turnos que manejó agent_id "007" entre el 1 y el 2 de enero de 2021 (PST):

FILTER='create_time>"2021-01-01T00:00:00-08:00" create_time<"2021-01-02T00:00:00-08:00" agent_id="007" turn_count>="10"'

Exporta datos a una tabla protegida por CMEK (opcional)

Proporciona a tu cuenta de servicio de CX Insights el rol de encriptador/desencriptador de CryptoKey de Cloud KMS. Consulta la documentación sobre problemas conocidos acerca del formato de las cuentas de servicio. Una vez que hayas proporcionado el rol correcto a tu cuenta de servicio, agrega el nombre completo de la clave de KMS que protege la tabla a la solicitud de exportación:

KMS_KEY='projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<key_name>'

Especifica la opción de disposición de escritura en la solicitud (opcional)

La exportación de CCAI Insights admite las siguientes opciones de disposición de escritura de BigQuery:

• WRITE_TRUNCATE: Si la tabla ya existe, BigQuery reemplaza sus datos y usa el esquema del resultado de la consulta. Esta es la opción predeterminada.
• WRITE_APPEND: Si la tabla ya existe, BigQuery adjunta los datos a ella.

Por ejemplo, la siguiente muestra adjuntará los datos exportados a una tabla de destino existente:

WRITE_DISPOSITION='WRITE_APPEND'

Exportar tus datos a BigQuery

En el siguiente muestra de código, se muestra cómo exportar tus datos. Consulta la documentación de referencia sobre la exportación para obtener todos los detalles.

La exportación crea un objeto Operation de larga duración. Puedes sondear la operación para verificar su estado.

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos:

• contactcenterinsights.conversations.list en el recurso principal

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID de tu proyecto de Google Cloud.
• DATASET: Es el nombre del conjunto de datos de BigQuery al que se deben exportar los datos.
• TABLE: Es el nombre de la tabla de BigQuery en la que se deben escribir tus datos de CX Insights.
• FILTER_QUERY: Es una consulta que CX Insights usa para exportar solo las conversaciones que tienen propiedades específicas. Por ejemplo, si ingresas el valor "agent_id=\"007\"", solo se exportarán las conversaciones asociadas con el agente 007.

Nota: Todos los ejemplos usan la instancia global de Customer Experience Insights. Consulta Regionalización para obtener instrucciones sobre el uso de instancias regionales.

Método HTTP y URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/insightsdata:export

Cuerpo JSON de la solicitud:

{
  "bigQueryDestination": {
    "projectId": "PROJECT_ID",
    "dataset": "DATASET",
    "table": "TABLE",
  },
  "filter": "FILTER_QUERY"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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/insightsdata:export"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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/insightsdata:export" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Python

Para autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

from google.cloud import contact_center_insights_v1


def export_to_bigquery(
    project_id: str,
    bigquery_project_id: str,
    bigquery_dataset_id: str,
    bigquery_table_id: str,
) -> None:
    """Exports data to BigQuery.

    Args:
        project_id:
            The project identifier that owns the data source to be exported.
            For example, 'my-project'.
        bigquery_project_id:
            The project identifier that owns the BigQuery sink to export data to.
            For example, 'my-project'.
        bigquery_dataset_id:
            The BigQuery dataset identifier. For example, 'my-dataset'.
        bigquery_table_id:
            The BigQuery table identifier. For example, 'my-table'.

    Returns:
        None.
    """
    # Construct an export request.
    request = contact_center_insights_v1.ExportInsightsDataRequest()
    request.parent = (
        contact_center_insights_v1.ContactCenterInsightsClient.common_location_path(
            project_id, "us-central1"
        )
    )
    request.big_query_destination.project_id = bigquery_project_id
    request.big_query_destination.dataset = bigquery_dataset_id
    request.big_query_destination.table = bigquery_table_id
    request.filter = 'agent_id="007"'

    # Call the Insights client to export data to BigQuery.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    export_operation = insights_client.export_insights_data(request=request)
    export_operation.result(timeout=600000)
    print("Exported data to BigQuery")

Java

Para autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

import com.google.api.gax.longrunning.OperationTimedPollAlgorithm;
import com.google.api.gax.retrying.RetrySettings;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsSettings;
import com.google.cloud.contactcenterinsights.v1.ExportInsightsDataRequest;
import com.google.cloud.contactcenterinsights.v1.ExportInsightsDataResponse;
import com.google.cloud.contactcenterinsights.v1.LocationName;
import java.io.IOException;
import org.threeten.bp.Duration;

public class ExportToBigquery {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my_project_id";
    String bigqueryProjectId = "my_bigquery_project_id";
    String bigqueryDataset = "my_bigquery_dataset";
    String bigqueryTable = "my_bigquery_table";

    exportToBigquery(projectId, bigqueryProjectId, bigqueryDataset, bigqueryTable);
  }

  public static void exportToBigquery(
      String projectId, String bigqueryProjectId, String bigqueryDataset, String bigqueryTable)
      throws Exception, IOException {
    // Set the operation total polling timeout to 24 hours instead of the 5-minute default.
    // Other values are copied from the default values of {@link ContactCenterInsightsStubSettings}.
    ContactCenterInsightsSettings.Builder clientSettings =
        ContactCenterInsightsSettings.newBuilder();
    clientSettings
        .exportInsightsDataOperationSettings()
        .setPollingAlgorithm(
            OperationTimedPollAlgorithm.create(
                RetrySettings.newBuilder()
                    .setInitialRetryDelay(Duration.ofMillis(5000L))
                    .setRetryDelayMultiplier(1.5)
                    .setMaxRetryDelay(Duration.ofMillis(45000L))
                    .setInitialRpcTimeout(Duration.ZERO)
                    .setRpcTimeoutMultiplier(1.0)
                    .setMaxRpcTimeout(Duration.ZERO)
                    .setTotalTimeout(Duration.ofHours(24L))
                    .build()));

    // 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(clientSettings.build())) {
      // Construct an export request.
      LocationName parent = LocationName.of(projectId, "us-central1");
      ExportInsightsDataRequest request =
          ExportInsightsDataRequest.newBuilder()
              .setParent(parent.toString())
              .setBigQueryDestination(
                  ExportInsightsDataRequest.BigQueryDestination.newBuilder()
                      .setProjectId(bigqueryProjectId)
                      .setDataset(bigqueryDataset)
                      .setTable(bigqueryTable)
                      .build())
              .setFilter("agent_id=\"007\"")
              .build();

      // Call the Insights client to export data to BigQuery.
      ExportInsightsDataResponse response = client.exportInsightsDataAsync(request).get();
      System.out.printf("Exported data to BigQuery");
    }
  }
}

Node.js

Para autenticarte en CX Insights, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my_project_id';
// const bigqueryProjectId = 'my_bigquery_project_id';
// const bigqueryDataset = 'my_bigquery_dataset';
// const bigqueryTable = 'my_bigquery_table';

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

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

async function exportToBigquery() {
  const [operation] = await client.exportInsightsData({
    parent: client.locationPath(projectId, 'us-central1'),
    bigQueryDestination: {
      projectId: bigqueryProjectId,
      dataset: bigqueryDataset,
      table: bigqueryTable,
    },
    filter: 'agent_id="007"',
  });

  // Wait for the operation to complete.
  await operation.promise();
  console.info('Exported data to BigQuery');
}
exportToBigquery();

Exporta datos a otro proyecto (opcional)

De forma predeterminada, la exportación de CX Insights a BigQuery escribe los datos en el mismo proyecto que posee los datos de CX Insights. Sin embargo, también puedes exportar a BigQuery en otro proyecto.

Asegúrate de que tu cuenta de servicio de CX Insights tenga acceso a BigQuery en el proyecto del destinatario a través de la consola de IAM o con gcloud:

gcloud projects add-iam-policy-binding RECEIVER_PROJECT \
    --member=serviceAccount:[e-mail] \
    --role=roles/bigquery.admin

Nota: Si deseas restringir aún más el acceso, también puedes otorgar acceso a la cuenta de servicio a un conjunto de datos específico de BigQuery.

Para exportar tus datos a un proyecto específico, ingresa el número de ID del proyecto destinatario en el campo project_id del objeto BigQueryDestination.

Consulta los datos en BigQuery

Ejecuta este comando para consultar los datos en BigQuery. Consulta la documentación de la Guía de inicio rápido de BigQuery para obtener más opciones de consultas:

gcloud config set project PROJECT
bq show DATASET.TABLE

Consulta de conversaciones exportadas:

bq query --use_legacy_sql=false \
   "SELECT conversationName FROM DATASET.TABLE"