Exportar conversas para o BigQuery

O Customer Experience Insights (CX Insights) permite exportar seus dados de conversas e análises do CX Insights para o BigQuery para que você possa realizar suas próprias consultas brutas. O processo de exportação grava um esquema semelhante à estrutura de análise de fala. Este guia detalha o processo de exportação.

Criar uma nova tabela e conjunto de dados do BigQuery

O exportador do CX Insights exige uma tabela do BigQuery para que a operação seja bem-sucedida. Se você não tiver uma tabela de destino, use este exemplo para criar uma nova tabela e um conjunto de dados usando a ferramenta de linha de comando bq.

Não é necessário especificar um esquema para a tabela porque o processo de exportação grava um. No entanto, se você especificar um esquema, será necessário definir explicitamente a versão. O comando EXPORT_VERSION_LATEST_AVAILABLE não fornece de maneira confiável a versão mais recente e pode remover colunas da tabela. O envio de uma consulta com um esquema, mas sem versão, fornece uma versão inicial por padrão. Consulte a documentação do esquema do BigQuery para conferir o esquema de saída e as definições de coluna.

O BigQuery tem algumas restrições sobre o local da origem de dados. Consulte Considerações de localização. As restrições aplicadas aos buckets do Cloud Storage também se aplicam ao CX Insights. Por exemplo, se o conjunto de dados do BigQuery estiver no local multirregional EU, só será possível exportar dados do CX Insights de um dos locais europe-*.

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

bq mk --table PROJECT:DATASET.TABLE

Exportar dados de conversas para o BigQuery

A ferramenta de exportação oferece suporte à filtragem e à gravação de dados em tabelas protegidas por chaves de criptografia gerenciadas pelo cliente (CMEK). Se você não quiser ativar esse recurso, pule para a frente e exporte seus dados para o BigQuery.

Adicionar filtragem à solicitação (opcional)

A exportação para o BigQuery é compatível com todas as combinações de filtros que podem ser aplicadas a consultas de conversas. Por exemplo, o exemplo a seguir exportará todas as conversas com 10 ou mais turnos processados pelo agent_id "007" entre 1º de janeiro de 2021 e 2 de janeiro 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"'

Exportar dados para uma tabela protegida por CMEK (opcional)

Forneça à sua conta de serviço do CX Insights o papel de Criptografador/Descriptografador do Cloud KMS CryptoKey. Consulte a documentação de problemas conhecidos sobre o formato da conta de serviço. Depois de fornecer o papel correto à sua conta de serviço, adicione o nome totalmente qualificado da chave do KMS que protege a tabela à solicitação de exportação:

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

Especificar a opção de disposição de gravação na solicitação (opcional)

A exportação do CCAI Insights oferece suporte às seguintes opções de disposição de gravação do BigQuery:

  • WRITE_TRUNCATE: se a tabela já existir, o BigQuery vai substituir os dados da tabela e usar o esquema do resultado da consulta. Essa é a opção padrão.
  • WRITE_APPEND: se houver uma tabela, os dados serão anexados a ela no BigQuery.

Por exemplo, o exemplo a seguir vai adicionar ao final os dados exportados a uma tabela de destino existente:

WRITE_DISPOSITION='WRITE_APPEND'

Exporte seus dados para o BigQuery

O exemplo de código a seguir demonstra como exportar seus dados. Consulte a documentação de referência de exportação para conferir detalhes completos.

A exportação cria um objeto Operation de longa duração. É possível consultar a operação para verificar o status dela.

REST

Antes de usar os dados da solicitação abaixo, faça estas substituições:

  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • DATASET: o nome do conjunto de dados do BigQuery para o qual os dados precisam ser exportados.
  • TABLE: o nome da tabela do BigQuery em que os dados do CX Insights precisam ser gravados.
  • FILTER_QUERY: uma consulta que o CX Insights usa para exportar apenas conversas que têm propriedades específicas. Por exemplo, inserir o valor "agent_id=\"007\"" resultará na exportação apenas de conversas associadas ao agente 007.

Método HTTP e URL: 

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

Corpo JSON da solicitação: 

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Python

Para autenticar no CX Insights, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 autenticar no CX Insights, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 autenticar no CX Insights, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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();

Exportar dados para outro projeto (opcional)

Por padrão, a exportação do CX Insights para o BigQuery grava dados no mesmo projeto que possui os dados do CX Insights. No entanto, também é possível exportar para o BigQuery em outro projeto.

Verifique se a conta de serviço do CX Insights tem acesso ao BigQuery no projeto do destinatário usando o console do Identity and Access Management (IAM) ou com gcloud:

gcloud projects add-iam-policy-binding RECEIVER_PROJECT \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-contactcenterinsights.iam.gserviceaccount.com \
    --role=roles/bigquery.admin

Para exportar seus dados para um projeto específico, insira o número de ID do projeto do destinatário no campo project_id no BigQueryDestination objeto.

Consultar os dados no BigQuery

Execute este comando para consultar os dados no BigQuery. Consulte a documentação do Guia de início rápido do BigQuery para mais opções de consulta:

gcloud config set project PROJECT
bq show DATASET.TABLE

Como consultar conversas exportadas:

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