Template BigQuery ke Elasticsearch

Template BigQuery ke Elasticsearch adalah pipeline batch yang menyerap data dari tabel BigQuery ke Elasticsearch sebagai dokumen. Template dapat membaca seluruh tabel atau membaca data tertentu menggunakan kueri yang disediakan.

Persyaratan pipeline

  • Tabel BigQuery sumber harus ada.
  • Host Elasticsearch di instance Google Cloud atau di Elastic Cloud dengan Elasticsearch versi 7.0 atau yang lebih baru. Harus dapat diakses dari mesin pekerja Dataflow.

Parameter template

Parameter yang diperlukan

  • connectionUrl : URL Elasticsearch dalam format https://hostname:[port]. Jika menggunakan Elastic Cloud, tentukan CloudID. (Contoh: https://elasticsearch-host:9200).
  • apiKey : Kunci API yang dienkode Base64 untuk digunakan dalam autentikasi.
  • index : Indeks Elasticsearch tempat permintaan dikeluarkan, seperti my-index. (Contoh: my-index).

Parameter opsional

  • inputTableSpec : Tabel BigQuery yang akan dibaca. Format: projectId:datasetId.tablename. Jika Anda menentukan inputTableSpec, template akan membaca data langsung dari penyimpanan BigQuery menggunakan BigQuery Storage Read API (https://cloud.google.com/bigquery/docs/reference/storage). Untuk mengetahui informasi tentang batasan di Storage Read API, lihat https://cloud.google.com/bigquery/docs/reference/storage#limitations. Anda harus menentukan inputTableSpec atau query. Jika Anda menetapkan kedua parameter, template akan menggunakan parameter query. (Contoh: bigquery-project:dataset.input_table).
  • outputDeadletterTable : Tabel BigQuery untuk pesan yang gagal mencapai tabel output, dalam format <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>. Jika tabel tidak ada, tabel akan dibuat selama eksekusi pipeline. Jika tidak ditentukan, <outputTableSpec>_error_records akan digunakan. (Contoh: project-id-Anda:set-data-Anda.nama-tabel-Anda).
  • kueri : Kueri SQL yang akan digunakan untuk membaca data dari BigQuery. Jika set data BigQuery berada dalam project yang berbeda dengan tugas Dataflow, tentukan nama set data lengkap dalam kueri SQL, misalnya: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. Secara default, parameter query menggunakan GoogleSQL (https://cloud.google.com/bigquery/docs/introduction-sql), kecuali jika useLegacySql adalah true. Anda harus menentukan inputTableSpec atau query. Jika Anda menetapkan kedua parameter, template akan menggunakan parameter query. (Contoh: select * from sampledb.sample_table).
  • useLegacySql : Tetapkan ke true untuk menggunakan SQL lama. Parameter ini hanya berlaku saat menggunakan parameter query. Defaultnya adalah: false.
  • queryLocation : Diperlukan saat membaca dari tampilan yang diotorisasi tanpa izin tabel yang mendasarinya. (Contoh: AS).
  • queryTempDataset : Dengan opsi ini, Anda dapat menetapkan set data yang ada untuk membuat tabel sementara guna menyimpan hasil kueri. (Contoh: temp_dataset).
  • elasticsearchUsername : Nama pengguna Elasticsearch yang akan digunakan untuk mengautentikasi. Jika ditentukan, nilai 'apiKey' akan diabaikan.
  • elasticsearchPassword : Sandi Elasticsearch yang akan digunakan untuk melakukan autentikasi. Jika ditentukan, nilai 'apiKey' akan diabaikan.
  • batchSize : Ukuran batch dalam jumlah dokumen. Default-nya adalah: 1.000.
  • batchSizeBytes : Ukuran batch dalam jumlah byte. Default-nya adalah: 5242880 (5 mb).
  • maxRetryAttempts : Jumlah maksimum percobaan ulang. Harus lebih besar dari nol. Setelan default: tidak ada percobaan ulang.
  • maxRetryDuration : Durasi percobaan ulang maksimum dalam milidetik. Harus lebih besar dari nol. Setelan default: tidak ada percobaan ulang.
  • propertyAsIndex : Properti dalam dokumen yang diindeks yang nilainya menentukan metadata _index yang akan disertakan dengan dokumen dalam permintaan massal. Lebih diutamakan daripada UDF _index. Setelan defaultnya adalah: none.
  • javaScriptIndexFnGcsPath : Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata _index yang akan disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalah: none.
  • javaScriptIndexFnName : Nama fungsi JavaScript UDF yang menentukan metadata _index untuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalah: none.
  • propertyAsId : Properti dalam dokumen yang diindeks yang nilainya menentukan metadata _id yang akan disertakan dengan dokumen dalam permintaan massal. Lebih diutamakan daripada UDF _id. Setelan defaultnya adalah: none.
  • javaScriptIdFnGcsPath : Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata _id yang akan disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalah: none.
  • javaScriptIdFnName : Nama fungsi JavaScript UDF yang menentukan metadata _id yang akan disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalah: none.
  • javaScriptTypeFnGcsPath : Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata _type yang akan disertakan dengan dokumen dalam permintaan massal. Default: none.
  • javaScriptTypeFnName : Nama fungsi JavaScript UDF yang menentukan metadata _type yang akan disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalah: none.
  • javaScriptIsDeleteFnGcsPath : Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan apakah akan menghapus dokumen, bukan menyisipkan atau memperbaruinya. Fungsi ini menampilkan nilai string true atau false. Setelan defaultnya adalah: none.
  • javaScriptIsDeleteFnName : Nama fungsi JavaScript UDF yang menentukan apakah akan menghapus dokumen, bukan menyisipkan atau memperbaruinya. Fungsi ini menampilkan nilai string true atau false. Setelan defaultnya adalah: none.
  • usePartialUpdate : Apakah akan menggunakan pembaruan sebagian (memperbarui, bukan membuat atau mengindeks, yang memungkinkan dokumen sebagian) dengan permintaan Elasticsearch. Defaultnya adalah: false.
  • bulkInsertMethod : Apakah akan menggunakan INDEX (indeks, memungkinkan upsert) atau CREATE (buat, error pada _id duplikat) dengan permintaan massal Elasticsearch. Defaultnya adalah: CREATE.
  • trustSelfSignedCerts : Apakah akan memercayai sertifikat yang ditandatangani sendiri atau tidak. Instance Elasticsearch yang diinstal mungkin memiliki sertifikat yang ditandatangani sendiri. Aktifkan ini ke Benar untuk mengabaikan validasi pada sertifikat SSL. (defaultnya adalah False).
  • disableCertificateValidation : Jika 'true', percayai sertifikat SSL yang ditandatangani sendiri. Instance Elasticsearch mungkin memiliki sertifikat yang ditandatangani sendiri. Untuk mengabaikan validasi sertifikat, tetapkan parameter ini ke 'true'. Default: false.
  • apiKeyKMSEncryptionKey : Kunci Cloud KMS untuk mendekripsi kunci API. Parameter ini harus diberikan jika apiKeySource ditetapkan ke KMS. Jika parameter ini diberikan, string apiKey harus diteruskan dalam terenkripsi. Mengenkripsi parameter menggunakan endpoint enkripsi KMS API. Kunci harus dalam format projects/{gcp_project}/locations/{key_region}/keyRings/{key_ring}/cryptoKeys/{kms_key_name}. Lihat: https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/encrypt (Contoh: projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name).
  • apiKeySecretId : ID secret Secret Manager untuk apiKey. Parameter ini harus diberikan jika apiKeySource ditetapkan ke SECRET_MANAGER. Harus dalam format projects/{project}/secrets/{secret}/versions/{secret_version}. (Contoh: projects/your-project-id/secrets/your-secret/versions/your-secret-version).
  • apiKeySource : Sumber kunci API. Salah satu dari PLAINTEXT, KMS, atau SECRET_MANAGER. Parameter ini harus diberikan jika pengelola rahasia atau KMS digunakan. Jika apiKeySource ditetapkan ke KMS, apiKeyKMSEncryptionKey dan apiKey terenkripsi harus diberikan. Jika apiKeySource ditetapkan ke SECRET_MANAGER, apiKeySecretId harus diberikan. Jika apiKeySource ditetapkan ke PLAINTEXT, apiKey harus diberikan. Setelan defaultnya adalah: PLAINTEXT.
  • socketTimeout : Jika ditetapkan, akan menimpa waktu tunggu percobaan ulang maksimum default dan waktu tunggu soket default (30.000 md) di Elastic RestClient.
  • javascriptTextTransformGcsPath : URI Cloud Storage file .js yang menentukan fungsi yang ditentukan pengguna (UDF) JavaScript yang akan digunakan. (Contoh: gs://my-bucket/my-udfs/my_file.js).
  • javascriptTextTransformFunctionName : Nama fungsi yang ditentukan pengguna (UDF) JavaScript yang akan digunakan. Misalnya, jika kode fungsi JavaScript Anda adalah myTransform(inJson) { /*...do stuff...*/ }, nama fungsinya adalah myTransform. Untuk contoh UDF JavaScript, lihat Contoh UDF (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).

Fungsi yang ditentukan pengguna (UDF)

Template ini mendukung fungsi yang ditentukan pengguna (UDF) di beberapa titik dalam pipeline, yang dijelaskan di bawah. Untuk informasi selengkapnya, lihat Membuat fungsi yang ditentukan pengguna untuk template Dataflow.

Fungsi indeks

Menampilkan indeks tempat dokumen berada.

Parameter template:

  • javaScriptIndexFnGcsPath: URI Cloud Storage dari file JavaScript.
  • javaScriptIndexFnName: nama fungsi JavaScript.

Spesifikasi fungsi:

  • Input: dokumen Elasticsearch, yang diserialisasi sebagai string JSON.
  • Output: nilai kolom metadata _index dokumen.

Fungsi ID dokumen

Menampilkan ID dokumen.

Parameter template:

  • javaScriptIdFnGcsPath: URI Cloud Storage dari file JavaScript.
  • javaScriptIdFnName: nama fungsi JavaScript.

Spesifikasi fungsi:

  • Input: dokumen Elasticsearch, yang diserialisasi sebagai string JSON.
  • Output: nilai kolom metadata _id dokumen.

Fungsi penghapusan dokumen

Menentukan apakah akan menghapus dokumen atau tidak. Untuk menggunakan fungsi ini, tetapkan mode penyisipan massal ke INDEX dan berikan fungsi ID dokumen.

Parameter template:

  • javaScriptIsDeleteFnGcsPath: URI Cloud Storage dari file JavaScript.
  • javaScriptIsDeleteFnName: nama fungsi JavaScript.

Spesifikasi fungsi:

  • Input: dokumen Elasticsearch, yang diserialisasi sebagai string JSON.
  • Output: menampilkan string "true" untuk menghapus dokumen, atau "false" untuk memperbarui dan menyisipkan dokumen.

Fungsi jenis pemetaan

Menampilkan jenis pemetaan dokumen.

Parameter template:

  • javaScriptTypeFnGcsPath: URI Cloud Storage dari file JavaScript.
  • javaScriptTypeFnName: nama fungsi JavaScript.

Spesifikasi fungsi:

  • Input: dokumen Elasticsearch, yang diserialisasi sebagai string JSON.
  • Output: nilai kolom metadata _type dokumen.

Menjalankan template

Konsol

  1. Buka halaman Create job from template Dataflow.
  2. Buka Buat tugas dari template
  3. Di kolom Nama tugas, masukkan nama tugas yang unik.
  4. Opsional: Untuk Endpoint regional, pilih nilai dari menu drop-down. Region defaultnya adalah us-central1.

    Untuk mengetahui daftar region tempat Anda dapat menjalankan tugas Dataflow, lihat Lokasi Dataflow.

  5. Dari menu drop-down Dataflow template, pilih the BigQuery to Elasticsearch template.
  6. Di kolom parameter yang disediakan, masukkan nilai parameter Anda.
  7. Klik Run job.

gcloud

Di shell atau terminal, jalankan template:

gcloud dataflow flex-template run JOB_NAME \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/BigQuery_to_Elasticsearch \
    --parameters \
inputTableSpec=INPUT_TABLE_SPEC,\
connectionUrl=CONNECTION_URL,\
apiKey=APIKEY,\
index=INDEX

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud tempat Anda ingin menjalankan tugas Dataflow
  • JOB_NAME: nama tugas unik pilihan Anda
  • REGION_NAME: region tempat Anda ingin men-deploy tugas Dataflow—misalnya, us-central1
  • VERSION: versi template yang ingin Anda gunakan

    Anda dapat menggunakan nilai berikut:

  • INPUT_TABLE_SPEC: nama tabel BigQuery Anda.
  • CONNECTION_URL: URL Elasticsearch Anda.
  • APIKEY: kunci API Anda yang dienkode base64 untuk autentikasi.
  • INDEX: indeks Elasticsearch Anda.

API

Untuk menjalankan template menggunakan REST API, kirim permintaan POST HTTP. Untuk mengetahui informasi selengkapnya tentang API dan cakupan otorisasinya, lihat projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launch_parameter": {
      "jobName": "JOB_NAME",
      "parameters": {
          "inputTableSpec": "INPUT_TABLE_SPEC",
          "connectionUrl": "CONNECTION_URL",
          "apiKey": "APIKEY",
          "index": "INDEX"
      },
      "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/BigQuery_to_Elasticsearch",
   }
}

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud tempat Anda ingin menjalankan tugas Dataflow
  • JOB_NAME: nama tugas unik pilihan Anda
  • LOCATION: region tempat Anda ingin men-deploy tugas Dataflow—misalnya, us-central1
  • VERSION: versi template yang ingin Anda gunakan

    Anda dapat menggunakan nilai berikut:

  • INPUT_TABLE_SPEC: nama tabel BigQuery Anda.
  • CONNECTION_URL: URL Elasticsearch Anda.
  • APIKEY: kunci API Anda yang dienkode base64 untuk autentikasi.
  • INDEX: indeks Elasticsearch Anda.

Langkah selanjutnya