Peringatan: Konektor referensi Cloud Search disediakan "sebagaimana adanya" sebagai kode contoh untuk digunakan dalam membuat konektor yang berfungsi. Kode contoh ini memerlukan penyesuaian dan pengujian yang substansial sebelum digunakan dalam lingkungan bukti konsep atau produksi. Untuk penggunaan produksi, sebaiknya dapatkan bantuan dari salah satu partner Cloud Search kami. Untuk mendapatkan bantuan lebih lanjut dalam menemukan partner Cloud Search yang sesuai, hubungi Account Manager Google Anda. |
Anda dapat menyiapkan Google Cloud Search untuk menemukan dan mengindeks data dari database organisasi Anda menggunakan konektor database Google Cloud Search.
Pertimbangan penting
Anda dapat menginstal dan menjalankan konektor database Cloud Search di hampir semua lingkungan tempat aplikasi Java dapat dijalankan, selama konektor tersebut memiliki akses ke internet dan database.
Persyaratan sistem
Persyaratan sistem | |
---|---|
Sistem operasi | Windows atau Linux |
Database SQL | Semua database SQL dengan driver yang sesuai dengan JDBC 4.0 atau yang lebih baru, termasuk yang berikut ini:
|
Software | Driver JDBC untuk konektor yang akan digunakan untuk mengakses database (didownload dan diinstal secara terpisah) |
Men-deploy konektor
Langkah-langkah berikut menjelaskan cara menginstal konektor dan mengonfigurasinya untuk mengindeks database yang ditentukan dan menampilkan hasilnya kepada pengguna Cloud Search.
Prasyarat
Sebelum Anda menerapkan konektor database Cloud Search, kumpulkan informasi berikut:
- Kunci pribadi Google Workspace, yang juga berisi ID akun layanan. Untuk mempelajari cara mendapatkan kunci pribadi, buka Mengonfigurasi akses ke REST API Google Cloud Search.
- ID sumber data Google Workspace. Untuk mempelajari cara mendapatkan ID sumber data, buka Menambahkan sumber data untuk penelusuran.
Langkah 1. Mendownload dan membuat software konektor database
- Clone repositori konektor dari GitHub.
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- Lihat versi konektor yang diinginkan:
$ git checkout tags/v1-0.0.3
- Buat konektor.
$ mvn package
Untuk melewati pengujian saat membuat konektor, gunakanmvn package -DskipTests
. - Salin file ZIP konektor ke direktori penginstalan lokal Anda dan ekstrak file zip:
$ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir $ cd installation-dir $ unzip google-cloudsearch-database-connector-v1-0.0.3.zip $ cd google-cloudsearch-database-connector-v1-0.0.3
Langkah 2: Konfigurasikan konektor database
- Buat file teks dan beri nama
connector-config.properties
(default) atau yang serupa. Google merekomendasikan agar Anda memberi nama file konfigurasi dengan ekstensi.properties
atau.config
dan menyimpan file dalam direktori yang sama dengan konektor. Jika menggunakan nama atau jalur yang berbeda, Anda harus menentukan jalur saat menjalankan konektor. - Tambahkan parameter sebagai key-value pair ke konten file. File konfigurasi harus menentukan parameter untuk akses sumber data, akses database, pernyataan SQL traversal lengkap database, judul kolom konten, dan definisi kolom. Anda juga dapat mengonfigurasi perilaku konektor lainnya dengan parameter opsional. Contoh:
# Required parameters for data source access api.sourceId=1234567890abcdef api.identitySourceId=0987654321lmnopq api.serviceAccountPrivateKeyFile=./PrivateKey.json # # Required parameters for database access db.url=jdbc:mysql://localhost:3306/mysql_test db.user=root db.password=passw0rd # # Required full traversal SQL statement parameter db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book # # Required parameters for column definitions and URL format db.allColumns=customer_id, first_name, last_name, phone, change_timestamp db.uniqueKeyColumns=customer_id url.columns=customer_id # # Required content field parameter contentTemplate.db.title=customer_id # # Optional parameters to set ACLs to "entire domain" access defaultAcl.mode=fallback defaultAcl.public=true # # Optional parameters for schedule traversals schedule.traversalIntervalSecs=36000 schedule.performTraversalOnStart=true schedule.incrementalTraversalIntervalSecs=3600
Untuk deskripsi mendetail tentang parameter khusus database, buka Referensi parameter konfigurasi di akhir artikel ini.
Untuk mempelajari parameter umum pada semua konektor Cloud Search, seperti konfigurasi metadata, format datetime, dan opsi ACL, buka parameter konektor yang disediakan Google.
Jika berlaku, tentukan properti objek skema dalam parameter kueri SQL traversal. Biasanya Anda dapat menambahkan alias ke pernyataan SQL. Misalnya, jika Anda memiliki database film dan skema sumber data berisi definisi properti bernama "ActorName", pernyataan SQL dapat berbentuk:
SELECT …, last_name AS ActorName, … FROM …
.
Langkah 3. Jalankan konektor database
Contoh berikut mengasumsikan bahwa komponen yang diperlukan berada di direktori lokal pada sistem Linux.
Untuk menjalankan konektor dari command line, masukkan perintah berikut:
java \ -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \ com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \ [-Dconfig=mysql.config]
Dengan keterangan:
google-cloud-search-database-connector-v1-0.0.3.jar
adalah file .jar konektor databasemysql-connector-java-5.1.41-bin.jar
adalah driver JDBC yang digunakan untuk mengakses databasemysql.config
adalah file konfigurasi bernama kustom. Untuk memastikan konektor mengenali file konfigurasi Anda, tentukan jalurnya di command line. Jika tidak, konektor akan menggunakanconnector-config.properties
di direktori lokal Anda sebagai nama file default.
Konektor melaporkan error konfigurasi saat mendeteksinya. Beberapa error dilaporkan saat konektor melakukan inisialisasi, seperti ketika kolom database ditentukan sebagai bagian dari konten record (dalam db.allColumns
), tetapi kolom tersebut tidak digunakan dalam kueri SQL traversal database (dalam db.allRecordsSql
). Error lainnya hanya terdeteksi dan dilaporkan saat konektor mencoba mengakses database untuk traversal pertama, seperti sintaksis pernyataan SQL yang tidak valid.
Referensi parameter konfigurasi
Parameter akses sumber data
Pembahasan | Parameter |
---|---|
ID sumber data | api.sourceId = source-ID
Wajib. ID sumber Cloud Search yang disiapkan administrator Google Workspace. |
ID sumber identitas | api.identitySourceId = identity-source-ID
Diperlukan untuk menggunakan pengguna dan grup eksternal untuk ACL. ID sumber identitas Cloud Search yang disiapkan administrator Google Workspace. |
Akun layanan | api.serviceAccountPrivateKeyFile = path-to-private-key
Wajib. Jalur ke file kunci akun layanan Cloud Search yang dibuat oleh administrator Google Workspace. |
Parameter akses database
Pembahasan | Parameter |
---|---|
URL database | db.url = database-URL
Wajib. Jalur lengkap database yang akan diakses, seperti |
Nama pengguna dan sandi database | db.user = username db.password = password
Wajib ada. Nama pengguna dan sandi yang valid yang digunakan konektor untuk mengakses database. Pengguna database ini harus memiliki akses baca ke record yang relevan dari database yang sedang dibaca. |
Driver JDBC | db.driverClass = oracle.jdbc.OracleDriver
Wajib ada hanya jika driver JDBC 4.0 belum ditentukan di lokasi kelas. |
Parameter kueri Traversal SQL
Konektor ini melintasi record database dengan kueri SELECT SQL pada file konfigurasi. Anda harus mengonfigurasi kueri traversal penuh; kueri untuk traversal inkremental bersifat opsional.
Traversal penuh membaca setiap record database yang dikonfigurasi untuk pengindeksan. Diperlukan traversal penuh untuk mengindeks record baru untuk Cloud Search dan juga untuk mengindeks ulang semua record yang ada.
inkremental traversal hanya membaca dan mengindeks ulang record database yang baru dimodifikasi dan entri terbaru ke database. Traversal inkremental bisa lebih efisien daripada traversal penuh. Untuk menggunakan traversal inkremental, database Anda harus berisi kolom stempel waktu untuk menunjukkan record yang diubah.
Konektor menjalankan traversal ini sesuai dengan jadwal yang Anda tentukan dalam parameter jadwal traversal.
Pembahasan | Parameter |
---|---|
Kueri traversal penuh | db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name
Wajib. Kueri berjalan untuk setiap traversal penuh. Setiap nama kolom yang akan digunakan konektor dalam kapasitas apa pun (konten, ID unik, ACL) harus ada dalam kueri ini. Konektor melakukan beberapa verifikasi awal saat startup untuk mendeteksi error dan kelalaian. Karena alasan ini, jangan gunakan kueri "SELECT * FROM…" umum. |
Penomoran halaman traversal penuh | db.allRecordsSql.pagination = {none | offset}
Nilai dapat berupa:
|
Kueri traversal inkremental | db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?
Diperlukan jika Anda menjadwalkan traversal inkremental. Huruf "?" dalam kueri adalah placeholder wajib untuk nilai stempel waktu. Konektor menggunakan stempel waktu untuk melacak modifikasi di antara kueri SQL traversal inkremental. Untuk melacak kolom stempel waktu database untuk waktu pembaruan terakhir, tambahkan alias Untuk traversal inkremental pertama, konektor menggunakan waktu mulai konektor. Setelah traversal inkremental pertama, Cloud Search menyimpan stempel waktu sehingga konektor yang dimulai ulang dapat mengakses stempel waktu traversal inkremental sebelumnya. |
Zona waktu database | db.timestamp.timezone = America/Los_Angeles
Menentukan zona waktu yang akan digunakan untuk stempel waktu database. Stempel waktu database yang digunakan untuk mengidentifikasi penambahan record baru atau record database yang baru diubah. Defaultnya adalah zona waktu lokal tempat konektor berjalan. |
Contoh kueri traversal SQL
- Kueri traversal penuh dasar yang membaca setiap catatan minat dalam database karyawan untuk pengindeksan:
db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \ FROM employee
- Tentukan penomoran halaman dengan offset, lalu bagi traversal penuh menjadi beberapa kueri.
Untuk SQL Server 2012 atau Oracle 12c (sintaksis SQL 2008 standar):
db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \ FROM employee \ ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY db.allRecordsSql.pagination = offset
atau, untuk MySQL atau Google Cloud SQL:
db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \ FROM employee \ ORDER BY customer_id LIMIT 1000 OFFSET ? db.allRecordsSql.pagination = offset
- Kueri traversal penuh yang menerapkan ACL individual dengan alias:
db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \ permitted_readers AS readers_users, \ denied_readers AS denied_users, \ permitted_groups AS readers_groups, \ denied_groups AS denied_groups \ FROM employee
- Kueri traversal inkremental dasar:
db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \ FROM employee \ WHERE last_update_time > ?
- Kueri traversal inkremental yang menerapkan ACL individual dengan alias:
db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \ permitted_readers AS readers_users, \ denied_readers AS denied_users, \ permitted_groups AS readers_groups, \ denied_groups AS denied_groups \ FROM employee \ WHERE last_update_time > ?
- Kueri traversal inkremental yang menggunakan stempel waktu database, bukan waktu saat ini:
db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \ last_update_time AS timestamp_column \ FROM employee \ WHERE last_update_time > ?
Parameter definisi kolom
Parameter berikut menentukan kolom yang Anda gunakan dalam pernyataan traversal dan untuk mengidentifikasi setiap catatan secara unik.
Pembahasan | Parameter |
---|---|
Semua kolom | db.allColumns = column-1, column-2, ...column-N
Wajib. Mengidentifikasi semua kolom yang diperlukan dalam kueri SQL saat mengakses database. Kolom yang ditentukan dengan parameter ini harus direferensikan secara eksplisit dalam kueri. Setiap parameter definisi kolom lainnya dibandingkan dengan kumpulan kolom ini. Contoh: db.allColumns = customer_id, first_name, last_name, phone, change_timestamp |
Kolom kunci unik | db.uniqueKeyColumns = column-1[, column-2]
Wajib. Mencantumkan satu kolom database yang berisi nilai-nilai unik atau dengan kombinasi kolom yang nilainya bersama-sama menentukan ID unik. Cloud Search mengharuskan setiap dokumen yang dapat dicari untuk memiliki ID unik dalam sumber data. Anda harus dapat menentukan ID unik untuk setiap record database dari nilai kolom. Jika Anda menjalankan beberapa konektor pada database terpisah tetapi mengindeks ke dalam set data yang sama, pastikan Anda menentukan ID unik di semua dokumen. Contoh: db.uniqueKeyColumns = customer_id # or db.uniqueKeyColumns = last_name, first_name |
Kolom link URL | url.columns = column-1[, column-2]
Wajib. Menentukan satu atau beberapa nama kolom yang valid dan ditentukan yang digunakan untuk URL yang digunakan untuk hasil penelusuran yang dapat diklik. Untuk database yang tidak memiliki URL relevan yang terkait dengan setiap record database, link statis dapat digunakan untuk setiap record. Namun, jika nilai kolom menentukan link yang valid untuk setiap record, kolom URL tampilan dan nilai konfigurasi format harus ditentukan. |
Format URL | url.format = https://www.example.com/{0}
Menentukan format URL tampilan. Parameter bernomor mengacu pada kolom yang ditentukan dalam db.columns, secara berurutan, dimulai dengan nol. Jika tidak ditentukan, defaultnya adalah "{0}." Contohnya seperti pada tabel ini. |
Kolom yang dienkode persentase untuk URL | url.columnsToEscape = column-1[, column-2]
Menentukan kolom dari db.columns yang nilainya akan dienkode dengan persen sebelum memasukkannya ke dalam string URL yang diformat. |
Contoh kolom URL
Untuk menentukan kolom yang digunakan dalam kueri traversal dan format URL tampilan:
- Untuk menggunakan URL statis yang tidak menggunakan nilai record database apa pun:
url.format = https://www.example.com
- Untuk menggunakan nilai kolom tunggal yang merupakan URL tampilan:
url.format = {0} url.columns = customer_id
- Untuk menggunakan nilai kolom tunggal yang diganti ke dalam URL tampilan di posisi {0}:
url.format = https://www.example.com/customer/id={0} url.columns = customer_id url.columnsToEscape = customer_id
- Untuk menggunakan beberapa nilai kolom guna membuat URL tampilan (kolom bergantung pada urutan):
url.format = {1}/customer={0} url.columns = customer_id, linked_url url.columnsToEscape = customer_id
Kolom konten
Gunakan opsi konten untuk menentukan nilai record mana yang harus dijadikan bagian dari konten yang dapat ditelusuri.
Pembahasan | Parameter |
---|---|
Kolom penelusuran berkualitas tertinggi | contentTemplate.db.title = column-name
Wajib. Kolom berkualitas tertinggi untuk pengindeksan penelusuran dan prioritas hasil. |
Prioritas kolom untuk penelusuran | contentTemplate.db.quality.high = column-1[, column-2...] contentTemplate.db.quality.medium = column-1[, column-2...] contentTemplate.db.quality.low = column-1[, column-2...]
Tetapkan kolom konten (kecuali kolom yang ditetapkan untuk |
Kolom data konten | db.contentColumns = column-1[, column-2...]
Menentukan kolom konten dalam database. Dokumen ini diformat dan diupload ke Cloud Search sebagai konten dokumen yang dapat ditelusuri. Jika Anda tidak menentukan nilai, defaultnya adalah "*" yang menunjukkan bahwa semua kolom harus digunakan untuk konten. |
Kolom Blob | db.blobColumn = column-name
Tentukan nama kolom blob tunggal yang akan digunakan untuk konten dokumen, bukan kombinasi kolom konten. Jika kolom blob ditentukan, akan dianggap error jika kolom konten juga ditentukan. Namun, definisi metadata dan kolom data terstruktur masih diizinkan bersama dengan kolom blob. |