Mengekspor percakapan ke BigQuery

CX Insights memungkinkan Anda mengekspor data analisis dan percakapan CX Insights ke BigQuery sehingga Anda dapat menjalankan kueri raw milik Anda sendiri. Proses ekspor menulis skema yang mirip dengan Speech Analysis Framework. Panduan ini menjelaskan proses ekspor secara mendetail.

Membuat tabel dan set data BigQuery baru

CX Insights Exporter memerlukan tabel BigQuery agar operasi berhasil. Jika Anda tidak memiliki tabel target, gunakan sampel ini untuk membuat tabel dan set data baru menggunakan alat command line bq. Lihat dokumentasi skema BigQuery untuk skema output dan definisi kolom.

BigQuery memiliki beberapa batasan pada lokasi sumber datanya. Lihat Pertimbangan lokasi. Batasan yang berlaku untuk bucket Cloud Storage juga berlaku untuk CX Insights. Misalnya, jika set data BigQuery Anda berada di lokasi multi-region EU, Anda hanya dapat mengekspor data CX Insights dari salah satu lokasi europe-*.

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

bq mk --table PROJECT:DATASET.TABLE

Mengekspor data percakapan ke BigQuery

Alat ekspor mendukung pemfilteran dan penulisan data ke tabel yang dilindungi kunci enkripsi yang dikelola pelanggan (CMEK). Jika tidak ingin mengaktifkan fitur ini, Anda dapat melanjutkan dan mengekspor data ke BigQuery.

Menambahkan pemfilteran ke permintaan (Opsional)

Ekspor ke BigQuery kompatibel dengan semua kombinasi filter yang dapat diterapkan ke kueri percakapan. Misalnya, contoh berikut akan mengekspor semua percakapan dengan 10 atau lebih giliran yang ditangani oleh agent_id "007" antara 1 Januari 2021 dan 2 Januari 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"'

Mengekspor data ke tabel yang dilindungi CMEK (Opsional)

Berikan peran Cloud KMS CryptoKey Encrypter/Decrypter kepada akun layanan CX Insights Anda. Lihat dokumentasi masalah umum tentang format akun layanan. Setelah Anda memberikan peran yang benar ke akun layanan, tambahkan nama lengkap kunci KMS yang melindungi tabel ke permintaan ekspor:

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

Tentukan opsi disposisi tulis dalam permintaan (Opsional)

Ekspor Insight CCAI mendukung opsi disposisi penulisan berikut dari BigQuery:

  • WRITE_TRUNCATE: Jika tabel sudah ada, BigQuery akan menimpa data tabel dan menggunakan skema dari hasil kueri. Opsi ini adalah opsi default.
  • WRITE_APPEND: Jika tabel sudah ada, BigQuery akan menambahkan data ke tabel tersebut.

Misalnya, contoh berikut akan menambahkan data yang diekspor ke tabel tujuan yang ada:

WRITE_DISPOSITION='WRITE_APPEND'

Mengekspor data Anda ke BigQuery

Contoh kode berikut menunjukkan cara mengekspor data Anda. Lihat dokumentasi referensi ekspor untuk mengetahui detail selengkapnya.

Ekspor membuat objek Operation yang berjalan lama. Anda dapat melakukan polling operasi untuk memeriksa statusnya.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • DATASET: nama set data BigQuery tempat data harus diekspor.
  • TABLE: nama tabel BigQuery tempat data CX Insights Anda harus ditulis.
  • FILTER_QUERY: kueri yang digunakan CX Insights untuk mengekspor hanya percakapan yang memiliki properti tertentu. Misalnya, memasukkan nilai "agent_id=\"007\"" hanya akan mengekspor percakapan yang terkait dengan agen 007.

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Python

Untuk melakukan autentikasi ke CX Insights, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk melakukan autentikasi ke CX Insights, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Untuk melakukan autentikasi ke CX Insights, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Mengekspor data ke project lain (Opsional)

Secara default, ekspor BigQuery CX Insights menulis data ke project yang sama dengan yang memiliki data CX Insights. Namun, Anda juga dapat mengekspor ke BigQuery di project lain.

Pastikan akun layanan CX Insights Anda memiliki akses BigQuery ke project penerima menggunakan konsol IAM atau dengan gcloud:

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

Untuk mengekspor data ke project tertentu, masukkan nomor ID project penerima di kolom project_id dalam objek BigQueryDestination.

Membuat kueri data di BigQuery

Jalankan perintah ini untuk membuat kueri data di BigQuery. Lihat dokumentasi Mulai Cepat BigQuery untuk mengetahui opsi kueri lainnya:

gcloud config set project PROJECT
bq show DATASET.TABLE

Mengirimkan kueri percakapan yang diekspor:

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