Exportar conversas para o BigQuery

Com o CX Insights, é possível exportar seus dados de conversas e análises do CX Insights para o BigQuery e realizar suas próprias consultas brutas. O processo de exportação grava um esquema semelhante ao Speech Analysis Framework. Este guia detalha o processo de exportação.

Criar uma tabela e um conjunto de dados do BigQuery

O CX Insights Exporter exige uma tabela do BigQuery para que a operação seja concluída. Se você não tiver uma tabela de destino, use este exemplo para criar uma tabela e um conjunto de dados com a ferramenta de linha de comando bq. Consulte a documentação do esquema do BigQuery para ver o esquema de saída e as definições de coluna.

O BigQuery tem algumas restrições quanto ao local da fonte de dados. Consulte Considerações de localização. As restrições que se aplicam 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 é compatível com a filtragem e a gravação de dados em tabelas protegidas por chaves de criptografia gerenciadas pelo cliente (CMEK). Se não quiser ativar esse recurso, pule para 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 conversa. Por exemplo, a amostra a seguir exporta todas as conversas com 10 ou mais turnos processados por 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)

Conceda à sua conta de serviço do CX Insights a função Criptografador/Descriptografador do Cloud KMS CryptoKey. Consulte a documentação de problemas conhecidos sobre o formato da conta de serviço. Depois de fornecer a função correta à 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>'

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

A exportação do CCAI Insights é compatível com as seguintes opções de descarte de gravação do BigQuery:

  • WRITE_TRUNCATE: se a tabela já existir, o BigQuery vai substituir os dados dela 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, a amostra a seguir vai anexar 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 mais detalhes.

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 as substituições a seguir:

  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • DATASET: o nome do conjunto de dados do BigQuery para onde os dados serão exportados.
  • TABLE: o nome da tabela do BigQuery em que os dados do CX Insights serão gravados.
  • FILTER_QUERY: uma consulta que o CX Insights usa para exportar apenas conversas com propriedades específicas. Por exemplo, inserir o valor "agent_id=\"007\"" resultará na exportação apenas das 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. Para 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. Para 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. Para 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 BigQuery do CX Insights 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 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 destinatário no campo project_id do objeto BigQueryDestination.

Consultar os dados no BigQuery

Execute este comando para consultar os dados no BigQuery. Consulte a documentação do 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"