Unterhaltungen nach BigQuery exportieren

Mit Customer Experience Insights (CX Insights) können Sie Ihre CX Insights-Unterhaltungen und ‑Analysedaten nach BigQuery exportieren, um Ihre eigenen Direktabfragen auszuführen. Beim Exportvorgang wird ein Schema geschrieben, das dem Framework für die Sprachanalyse ähnelt. In diesem Leitfaden wird der Exportvorgang im Detail beschrieben.

Neue BigQuery-Tabelle und neues BigQuery-Dataset erstellen

Für den CX Insights Exporter ist eine BigQuery-Tabelle erforderlich, damit der Vorgang erfolgreich ausgeführt werden kann. Wenn Sie keine Zieltabelle haben, können Sie mit diesem Beispiel eine neue Tabelle und ein neues Dataset mit dem bq-Befehlszeilentool erstellen. Informationen zum Ausgabeschema und zu den Spaltendefinitionen finden Sie in der BigQuery-Schemadokumentation.

Für BigQuery gelten einige Einschränkungen hinsichtlich des Speicherorts der Datenquelle. Weitere Informationen finden Sie unter Überlegungen zum Standort. Die Einschränkungen, die für Cloud Storage-Buckets gelten, gelten auch für CX Insights. Wenn sich Ihr BigQuery-Dataset beispielsweise am Multiregionalen Standort EU befindet, können Sie CX Insights-Daten nur von einem der Standorte europe-* exportieren.

Warnung: Beim CX Insights-Export werden alle Daten in der angegebenen Tabelle vor dem Schreiben abgeschnitten.

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

bq mk --table PROJECT:DATASET.TABLE

Unterhaltungsdaten nach BigQuery exportieren

Das Exporttool unterstützt sowohl das Filtern als auch das Schreiben von Daten in Tabellen, die mit einem kundenverwalteten Verschlüsselungsschlüssel (CMEK)geschützt sind. Wenn Sie diese Funktion nicht aktivieren möchten, können Sie diesen Schritt überspringen und Ihre Daten nach BigQuery exportieren.

Der Anfrage Filter hinzufügen (optional)

Der Export nach BigQuery ist mit allen Kombinationen von Filtern kompatibel, die auf Unterhaltungsabfragen angewendet werden können. Im folgenden Beispiel werden alle Unterhaltungen mit mindestens 10 Runden exportiert, die zwischen dem 1. Januar 2021 und dem 2. Januar 2021 (PST) von agent_id „007“ bearbeitet wurden:

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

Daten in eine CMEK-geschützte Tabelle exportieren (optional)

Weisen Sie Ihrem CX Insights-Dienstkonto die Rolle _Cloud KMS CryptoKey Encrypter/Decrypter_ zu. Informationen zum Format von Dienstkonten finden Sie in der Dokumentation zu bekannten Problemen. Nachdem Sie Ihrem Dienstkonto die richtige Rolle zugewiesen haben, fügen Sie der Exportanfrage den vollständig qualifizierten Namen des KMS-Schlüssels hinzu, mit dem die Tabelle geschützt wird:

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

Option für die Schreibanordnung in der Anfrage angeben (optional)

Der CCAI Insights-Export unterstützt die folgenden Optionen für die Schreibanordnung aus BigQuery:

• WRITE_TRUNCATE: Wenn die Tabelle bereits vorhanden ist, überschreibt BigQuery die Tabellendaten und verwendet das Schema aus dem Abfrageergebnis. Dies ist die Standardoption.
• WRITE_APPEND: Wenn die Tabelle bereits vorhanden ist, hängt BigQuery die Daten an die Tabelle an.

Im folgenden Beispiel werden die exportierten Daten an eine vorhandene Zieltabelle angehängt:

WRITE_DISPOSITION='WRITE_APPEND'

Daten nach BigQuery exportieren

Im folgenden Codebeispiel wird gezeigt, wie Sie Ihre Daten exportieren. Vollständige Informationen finden Sie in der Exportreferenzdokumentation.

Beim Export wird ein Operation-Objekt mit langer Ausführungszeit erstellt. Sie können den Vorgang abfragen , um den Status zu prüfen.

Erforderliche Berechtigungen für diese Aufgabe

Zum Ausführen dieser Aufgabe benötigen Sie folgende Berechtigungen:

• contactcenterinsights.conversations.list für die übergeordnete Ressource

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: Ihre Google Cloud-Projekt-ID.
• DATASET: Der Name des BigQuery-Datasets, in das die Daten exportiert werden sollen.
• TABLE: Der Name der BigQuery-Tabelle, in die Ihre CX Insights-Daten geschrieben werden sollen.
• FILTER_QUERY: Eine Abfrage, mit der CX Insights nur Unterhaltungen mit bestimmten Eigenschaften exportiert. Wenn Sie beispielsweise den Wert „agent_id=\"007\"“ eingeben, werden nur Unterhaltungen exportiert, die mit Agent 007 verknüpft sind.

Hinweis:In allen Beispielen wird die globale Customer Experience Insights-Instanz verwendet. Eine Anleitung zur Verwendung regionaler Instanzen finden Sie unter Regionalisierung.

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Python

Richten Sie zur Authentifizierung bei CX Insights die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Richten Sie zur Authentifizierung bei CX Insights die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Richten Sie zur Authentifizierung bei CX Insights die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

/**
 * 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();

Daten in ein anderes Projekt exportieren (optional)

Standardmäßig werden beim CX Insights-BigQuery-Export Daten in dasselbe Projekt geschrieben, in dem sich die CX Insights-Daten befinden. Sie können aber auch in BigQuery in einem anderen Projekt exportieren.

Prüfen Sie, ob Ihr CX Insights-Dienstkonto Zugriff auf das Empfängerprojekt hat. Verwenden Sie dazu entweder die IAM-Konsole (Identity and Access Management) oder gcloud:

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

Hinweis: Wenn Sie den Zugriff weiter einschränken möchten, können Sie dem Dienst konto auch Zugriff auf ein bestimmtes BigQuery-Dataset gewähren.

Wenn Sie Ihre Daten in ein bestimmtes Projekt exportieren möchten, geben Sie die ID des Empfängerprojekts im project_id Feld im BigQueryDestination Objekt ein.

Daten in BigQuery abfragen

Führen Sie diesen Befehl aus, um die Daten in BigQuery abzufragen. Weitere Abfrageoptionen finden Sie in der BigQuery-Schnellstartanleitung:

gcloud config set project PROJECT
bq show DATASET.TABLE

Exportierte Unterhaltungen abfragen:

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