Unterhaltungen nach BigQuery exportieren

Mit 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 Speech Analysis Framework ähnelt. In diesem Leitfaden wird der Exportvorgang beschrieben.

Neue BigQuery-Tabelle und ‑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 Spaltendefinitionen finden Sie in der BigQuery-Schemadokumentation.

Für den Speicherort der BigQuery-Datenquelle gelten einige Einschränkungen. Weitere Informationen finden Sie unter Überlegungen zum Standort. 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 europe-*-Standorte exportieren.

Warnung: Beim Export von CX Insights-Daten werden alle Daten in der bereitgestellten Tabelle gekürzt, bevor sie geschrieben werden.

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 durch kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, 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 Filterkombinationen kompatibel, die auf Unterhaltungsabfragen angewendet werden können. Im folgenden Beispiel werden alle Unterhaltungen mit mindestens 10 Zügen 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 Cloud KMS CryptoKey Encrypter/Decrypter-Rolle zu. Weitere 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 Schreibweise aus BigQuery:

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

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. Ausführliche Informationen finden Sie in der Referenzdokumentation zum Export.

Beim Export wird ein lang andauerndes Operation-Objekt erstellt. Sie können den Vorgang abfragen, um seinen 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 ist 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 in CX Insights nur Unterhaltungen mit bestimmten Eigenschaften exportiert werden. Wenn Sie beispielsweise den Wert „agent_id=\"007\"“ eingeben, werden nur Unterhaltungen exportiert, die dem Agenten 007 zugeordnet 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 Daten beim CX Insights-BigQuery-Export in dasselbe Projekt geschrieben, in dem sich die CX Insights-Daten befinden. Sie können aber auch in ein anderes Projekt exportieren.

Achten Sie darauf, dass Ihr CX Insights-Dienstkonto BigQuery-Zugriff auf das Empfängerprojekt hat. Verwenden Sie dazu entweder die IAM-Konsole 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 Dienstkonto auch Zugriff auf ein bestimmtes BigQuery-Dataset gewähren.

Wenn Sie Ihre Daten in ein bestimmtes Projekt exportieren möchten, geben Sie die ID-Nummer des Empfängerprojekts in das Feld project_id im Objekt BigQueryDestination 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"