Template BigQuery ke Elasticsearch adalah pipeline batch yang menyerap data dari tabel BigQuery ke Elasticsearch sebagai dokumen. Template ini dapat membaca seluruh tabel atau membaca rekaman tertentu menggunakan kueri yang disediakan.
Persyaratan pipeline
- Tabel BigQuery sumber harus ada.
- Host Elasticsearch di Google Cloud instance 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. Misalnya,https://elasticsearch-host:9200. - apiKey: Kunci API yang dienkode Base64 untuk digunakan dalam autentikasi.
- index: Indeks Elasticsearch tempat permintaan dikeluarkan. Misalnya,
my-index.
Parameter opsional
- inputTableSpec: Tabel BigQuery yang akan dibaca. 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 menentukaninputTableSpecatauquery. Jika Anda menetapkan kedua parameter, template akan menggunakan parameterquery. Misalnya,<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>. - outputDeadletterTable: Tabel BigQuery untuk pesan yang gagal mencapai tabel output. Jika tidak ada, tabel akan dibuat selama eksekusi pipeline. Jika tidak ditentukan,
<outputTableSpec>_error_recordsakan digunakan. Misalnya,<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>. - query: Kueri SQL yang akan digunakan untuk membaca data dari BigQuery. Jika set data BigQuery berada di project yang berbeda dengan tugas Dataflow, tentukan nama set data lengkap dalam kueri SQL, misalnya: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. Secara default, parameter
querymenggunakan GoogleSQL (https://cloud.google.com/bigquery/docs/introduction-sql), kecuali jikauseLegacySqladalahtrue. Anda harus menentukaninputTableSpecatauquery. Jika Anda menetapkan kedua parameter, template akan menggunakan parameterquery. Misalnya,select * from sampledb.sample_table. - useLegacySql: Tetapkan ke
trueuntuk menggunakan legacy SQL. Parameter ini hanya berlaku saat menggunakan parameterquery. Setelan defaultnya adalahfalse. - queryLocation: Diperlukan saat membaca dari tabel virtual yang diizinkan tanpa izin tabel yang mendasarinya. Misalnya,
US. - queryTempDataset: Dengan opsi ini, Anda dapat menetapkan set data yang ada untuk membuat tabel sementara guna menyimpan hasil kueri. Misalnya,
temp_dataset. - KMSEncryptionKey: Jika membaca dari BigQuery menggunakan sumber kueri, gunakan kunci Cloud KMS ini untuk mengenkripsi tabel sementara yang dibuat. Misalnya,
projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key. - elasticsearchUsername: Nama pengguna Elasticsearch untuk autentikasi. Jika ditentukan, nilai
apiKeyakan diabaikan. - elasticsearchPassword: Sandi Elasticsearch untuk autentikasi. Jika ditentukan, nilai
apiKeyakan diabaikan. - batchSize: Ukuran batch dalam jumlah dokumen. Setelan defaultnya adalah
1000. - batchSizeBytes: Ukuran batch dalam jumlah byte. Setelan defaultnya adalah
5242880(5 MB). - maxRetryAttempts: Jumlah maksimum percobaan ulang. Harus lebih besar dari nol. Setelan defaultnya adalah
5. - maxRetryDuration: Durasi percobaan ulang maksimum dalam milidetik. Harus lebih besar dari nol. Setelan defaultnya adalah
60000(1 menit). - propertyAsIndex: Properti dalam dokumen yang diindeks yang nilainya menentukan metadata
_indexuntuk disertakan dengan dokumen dalam permintaan massal. Diprioritaskan daripada UDF_index. Setelan defaultnya adalahnone. - javaScriptIndexFnGcsPath: Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata
_indexuntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - javaScriptIndexFnName: Nama fungsi JavaScript UDF yang menentukan metadata
_indexuntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - propertyAsId: Properti dalam dokumen yang diindeks yang nilainya menentukan metadata
_iduntuk disertakan dengan dokumen dalam permintaan massal. Diprioritaskan daripada UDF_id. Setelan defaultnya adalahnone. - javaScriptIdFnGcsPath: Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata
_iduntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - javaScriptIdFnName: Nama fungsi JavaScript UDF yang menentukan metadata
_iduntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - javaScriptTypeFnGcsPath: Jalur Cloud Storage ke sumber UDF JavaScript untuk fungsi yang menentukan metadata
_typeuntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - javaScriptTypeFnName: Nama fungsi JavaScript UDF yang menentukan metadata
_typeuntuk disertakan dengan dokumen dalam permintaan massal. Setelan defaultnya adalahnone. - 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
trueataufalse. Setelan defaultnya adalahnone. - javaScriptIsDeleteFnName: Nama fungsi JavaScript UDF yang menentukan apakah akan menghapus dokumen, bukan menyisipkan atau memperbaruinya. Fungsi ini menampilkan nilai string
trueataufalse. Setelan defaultnya adalahnone. - usePartialUpdate: Apakah akan menggunakan update sebagian (memperbarui, bukan membuat atau mengindeks, yang memungkinkan dokumen sebagian) dengan permintaan Elasticsearch. Setelan defaultnya adalah
false. - bulkInsertMethod: Apakah akan menggunakan
INDEX(indeks, memungkinkan upsert) atauCREATE(membuat, error pada _id duplikat) dengan permintaan massal Elasticsearch. Setelan defaultnya adalahCREATE. - trustSelfSignedCerts: Apakah akan mempercayai sertifikat yang ditandatangani sendiri atau tidak. Instance Elasticsearch yang diinstal mungkin memiliki sertifikat yang ditandatangani sendiri. Aktifkan parameter ini ke true untuk melewati validasi pada sertifikat SSL. (Setelan defaultnya adalah:
false). - disableCertificateValidation: Jika
true, percayai sertifikat SSL yang ditandatangani sendiri. Instance Elasticsearch mungkin memiliki sertifikat yang ditandatangani sendiri. Untuk melewati validasi sertifikat, tetapkan parameter ini ketrue. Setelan defaultnya adalahfalse. - apiKeyKMSEncryptionKey: Kunci Cloud KMS untuk mendekripsi kunci API. Parameter ini diperlukan jika
apiKeySourceditetapkan keKMS. Jika parameter ini disediakan, teruskan stringapiKeyyang dienkripsi. Enkripsi parameter menggunakan endpoint enkripsi KMS API. Untuk kunci, gunakan formatprojects/<PROJECT_ID>/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 Misalnya,projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name. - apiKeySecretId: ID secret Secret Manager untuk apiKey. Jika
apiKeySourceditetapkan keSECRET_MANAGER, berikan parameter ini. Gunakan formatprojects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. For example,projects/your-project-id/secrets/your-secret/versions/your-secret-version`. - apiKeySource: Sumber kunci API. Nilai yang diizinkan adalah
PLAINTEXT,KMS, atauSECRET_MANAGER. Parameter ini diperlukan saat Anda menggunakan Secret Manager atau KMS. JikaapiKeySourceditetapkan keKMS,apiKeyKMSEncryptionKeydan apiKey yang dienkripsi harus disediakan. JikaapiKeySourceditetapkan keSECRET_MANAGER,apiKeySecretIdharus disediakan. JikaapiKeySourceditetapkan kePLAINTEXT,apiKeyharus disediakan. Setelan defaultnya adalah: PLAINTEXT. - socketTimeout: Jika ditetapkan, akan menimpa waktu tunggu percobaan ulang maksimum default dan waktu tunggu soket default (30000 md) di Elastic RestClient.
- javascriptTextTransformGcsPath: Cloud Storage URI dari 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...*/ }, maka nama fungsinya adalahmyTransform. 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 mengetahui informasi selengkapnya, lihat Membuat fungsi yang ditentukan pengguna (UDF) untuk template Dataflow.
Fungsi indeks
Menampilkan indeks tempat dokumen berada.
Parameter template:
javaScriptIndexFnGcsPath: Cloud Storage URI dari the file JavaScript.javaScriptIndexFnName: nama fungsi JavaScript.
Spesifikasi fungsi:
- Input: dokumen Elasticsearch, diserialisasi sebagai string JSON.
- Output: nilai kolom metadata
_indexdokumen.
Fungsi ID dokumen
Menampilkan ID dokumen.
Parameter template:
javaScriptIdFnGcsPath: Cloud Storage URI dari file JavaScript.javaScriptIdFnName: nama fungsi JavaScript.
Spesifikasi fungsi:
- Input: dokumen Elasticsearch, diserialisasi sebagai string JSON.
- Output: nilai kolom metadata
_iddokumen.
Fungsi penghapusan dokumen
Menentukan apakah akan menghapus dokumen. Untuk menggunakan fungsi ini, tetapkan mode penyisipan massal ke INDEX dan berikan fungsi ID dokumen.
Parameter template:
javaScriptIsDeleteFnGcsPath: Cloud Storage URI dari file JavaScript.javaScriptIsDeleteFnName: nama fungsi JavaScript.
Spesifikasi fungsi:
- Input: dokumen Elasticsearch, diserialisasi sebagai string JSON.
- Output: menampilkan string
"true"untuk menghapus dokumen, atau"false"untuk melakukan upsert dokumen.
Fungsi jenis pemetaan
Menampilkan jenis pemetaan dokumen.
Parameter template:
javaScriptTypeFnGcsPath: Cloud Storage URI dari file JavaScript.javaScriptTypeFnName: nama fungsi JavaScript.
Spesifikasi fungsi:
- Input: dokumen Elasticsearch, diserialisasi sebagai string JSON.
- Output: nilai kolom metadata
_typedokumen.
Menjalankan template
Konsol
- Buka halaman Dataflow Membuat tugas dari template. Buka Membuat tugas dari template
- Di kolom Nama tugas, masukkan nama tugas yang unik.
- Opsional: Untuk Endpoint regional, pilih nilai dari menu drop-down. Region default-nya adalah
us-central1.Untuk mengetahui daftar region tempat Anda dapat menjalankan tugas Dataflow, lihat Lokasi Dataflow.
- Dari menu drop-down Template Dataflow, pilih template BigQuery ke Elasticsearch.
- Di kolom parameter yang disediakan, masukkan nilai parameter Anda.
- Klik Jalankan tugas.
gcloud
Di shell atau terminal Anda, 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/ \ --parameters \ inputTableSpec=INPUT_TABLE_SPEC,\ connectionUrl=CONNECTION_URL,\ apiKey=APIKEY,\ index=INDEX
Ganti kode berikut:
PROJECT_ID: Google Cloud Project ID tempat Anda ingin menjalankan tugas DataflowJOB_NAME: nama tugas unik pilihan AndaREGION_NAME: region tempat Anda ingin men-deploy tugas Dataflow—misalnya,us-central1VERSION: versi template yang ingin Anda gunakanAnda dapat menggunakan nilai berikut:
latestuntuk menggunakan template versi terbaru, yang tersedia di folder induk tanpa tanggal di bucket—gs://dataflow-templates-REGION_NAME/latest/- nama versi, seperti
2023-09-12-00_RC00, untuk menggunakan template versi tertentu, yang dapat ditemukan bertingkat di masing-masing folder induk yang diberi tanggal dalam bucket—gs://dataflow-templates-REGION_NAME/
INPUT_TABLE_SPEC: nama tabel BigQuery Anda.CONNECTION_URL: URL Elasticsearch Anda.APIKEY: kunci API 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/", } }
Ganti kode berikut:
PROJECT_ID: Google Cloud Project ID tempat Anda ingin menjalankan tugas DataflowJOB_NAME: nama tugas unik pilihan AndaLOCATION: region tempat Anda ingin men-deploy tugas Dataflow—misalnya,us-central1VERSION: versi template yang ingin Anda gunakanAnda dapat menggunakan nilai berikut:
latestuntuk menggunakan template versi terbaru, yang tersedia di folder induk tanpa tanggal di bucket—gs://dataflow-templates-REGION_NAME/latest/- nama versi, seperti
2023-09-12-00_RC00, untuk menggunakan template versi tertentu, yang dapat ditemukan bertingkat di masing-masing folder induk yang diberi tanggal dalam bucket—gs://dataflow-templates-REGION_NAME/
INPUT_TABLE_SPEC: nama tabel BigQuery Anda.CONNECTION_URL: URL Elasticsearch Anda.APIKEY: kunci API yang dienkode base64 untuk autentikasi.INDEX: indeks Elasticsearch Anda.
Langkah berikutnya
- Pelajari template Dataflow.
- Lihat daftar template yang disediakan Google.