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 menentukaninputTableSpec
, 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 menentukaninputTableSpec
atauquery
. Jika Anda menetapkan kedua parameter, template akan menggunakan parameterquery
. (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 jikauseLegacySql
adalahtrue
. Anda harus menentukaninputTableSpec
atauquery
. Jika Anda menetapkan kedua parameter, template akan menggunakan parameterquery
. (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
ataufalse
. 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
ataufalse
. 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) atauCREATE
(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 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 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
- Buka halaman Create job from template Dataflow. Buka Buat tugas dari template
- Di kolom Nama tugas, masukkan nama tugas yang unik.
- 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.
- Dari menu drop-down Dataflow template, pilih the BigQuery to Elasticsearch template.
- Di kolom parameter yang disediakan, masukkan nilai parameter Anda.
- 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 DataflowJOB_NAME
: nama tugas unik pilihan AndaREGION_NAME
: region tempat Anda ingin men-deploy tugas Dataflow—misalnya,us-central1
VERSION
: versi template yang ingin Anda gunakanAnda dapat menggunakan nilai berikut:
latest
untuk 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 versi template tertentu, yang dapat ditemukan bertingkat dalam folder induk bertanggal masing-masing di bucket—gs://dataflow-templates-REGION_NAME/
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 DataflowJOB_NAME
: nama tugas unik pilihan AndaLOCATION
: region tempat Anda ingin men-deploy tugas Dataflow—misalnya,us-central1
VERSION
: versi template yang ingin Anda gunakanAnda dapat menggunakan nilai berikut:
latest
untuk 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 versi template tertentu, yang dapat ditemukan bertingkat dalam folder induk bertanggal masing-masing di bucket—gs://dataflow-templates-REGION_NAME/
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
- Pelajari template Dataflow.
- Lihat daftar template yang disediakan Google.