Exporter des conversations vers BigQuery

CX Insights vous permet d'exporter vos données de conversation et d'analyse CX Insights vers BigQuery afin de pouvoir effectuer vos propres requêtes brutes. Le processus d'exportation écrit un schéma semblable au Speech Analysis Framework. Ce guide décrit en détail le processus d'exportation.

Créer une table et un ensemble de données BigQuery

Pour que l'opération réussisse, l'outil d'exportation CX Insights nécessite une table BigQuery. Si vous n'avez pas de table cible, utilisez cet exemple pour créer une table et un ensemble de données à l'aide de l'outil de ligne de commande bq. Consultez la documentation sur le schéma BigQuery pour connaître le schéma de sortie et les définitions des colonnes.

BigQuery impose certaines restrictions concernant l'emplacement de sa source de données. Consultez Considérations relatives aux zones. Les restrictions qui s'appliquent aux buckets Cloud Storage s'appliquent également à CX Insights. Par exemple, si votre ensemble de données BigQuery se trouve dans la zone multirégionale EU, vous ne pouvez exporter les données CX Insights que depuis l'un des emplacements europe-*.

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

bq mk --table PROJECT:DATASET.TABLE

Exporter les données de conversation vers BigQuery

L'outil d'exportation permet de filtrer et d'écrire des données dans des tables protégées par des clés de chiffrement gérées par le client (CMEK). Si vous ne souhaitez pas activer cette fonctionnalité, vous pouvez passer à la section Exporter vos données vers BigQuery.

Ajouter un filtrage à la requête (facultatif)

L'exportation vers BigQuery est compatible avec toutes les combinaisons de filtres pouvant être appliquées aux requêtes sur les conversations. Par exemple, l'exemple suivant exporte toutes les conversations comportant 10 tours ou plus traitées par l'agent agent_id "007" entre le 1er janvier 2021 et le 2 janvier 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"'

Exporter des données vers une table protégée par une clé CMEK (facultatif)

Attribuez le rôle Chiffreur/Déchiffreur de CryptoKey Cloud KMS à votre compte de service CX Insights. Consultez la documentation sur les problèmes connus concernant le format des comptes de service. Une fois que vous avez attribué le rôle approprié à votre compte de service, ajoutez le nom complet de la clé KMS protégeant la table à la demande d'exportation :

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

Spécifier l'option de disposition en écriture dans la requête (facultatif)

L'exportation CCAI Insights est compatible avec les options de disposition d'écriture de BigQuery suivantes :

  • WRITE_TRUNCATE : si la table existe déjà, BigQuery écrase les données de la table et utilise le schéma du résultat de la requête. Il s'agit de l'option par défaut.
  • WRITE_APPEND : si la table existe déjà, BigQuery ajoute les données à la table.

Par exemple, l'exemple suivant ajoute les données exportées à une table de destination existante :

WRITE_DISPOSITION='WRITE_APPEND'

Exporter vos données vers BigQuery

L'exemple de code suivant montre comment exporter vos données. Pour en savoir plus, consultez la documentation de référence sur l'exportation.

L'exportation crée un objet Operation de longue durée. Vous pouvez interroger l'opération pour vérifier son état.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud.
  • DATASET : nom de l'ensemble de données BigQuery vers lequel les données doivent être exportées.
  • TABLE : nom de la table BigQuery dans laquelle vos données CX Insights doivent être écrites.
  • FILTER_QUERY : requête utilisée par CX Insights pour n'exporter que les conversations présentant des propriétés spécifiques. Par exemple, si vous saisissez la valeur "agent_id=\"007\"", seules les conversations associées à l'agent 007 seront exportées.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Python

Pour vous authentifier auprès de CX Insights, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour vous authentifier auprès de CX Insights, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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

Pour vous authentifier auprès de CX Insights, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement 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();

Exporter des données vers un autre projet (facultatif)

Par défaut, l'exportation BigQuery de CX Insights écrit les données dans le même projet que celui qui possède les données CX Insights. Toutefois, vous pouvez également exporter les données vers BigQuery dans un autre projet.

Assurez-vous que votre compte de service CX Insights a accès à BigQuery dans le projet destinataire à l'aide de la console IAM ou de gcloud :

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

Pour exporter vos données vers un projet spécifique, saisissez le numéro d'ID du projet destinataire dans le champ project_id de l'objet BigQueryDestination.

Interroger les données dans BigQuery

Exécutez cette commande pour interroger les données dans BigQuery. Consultez la documentation Démarrage rapide BigQuery pour découvrir d'autres options de requête :

gcloud config set project PROJECT
bq show DATASET.TABLE

Interroger les conversations exportées :

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