Menerapkan konektor database

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:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
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:

Langkah 1. Mendownload dan membuat software konektor database

  1. Clone repositori konektor dari GitHub.
    $ git clone https://github.com/google-cloudsearch/database-connector.git
    $ cd database-connector
  2. Lihat versi konektor yang diinginkan:
    $ git checkout tags/v1-0.0.3
  3. Buat konektor.
    $ mvn package
    Untuk melewati pengujian saat membuat konektor, gunakan mvn package -DskipTests.
  4. 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

  1. 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.
  2. 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 database
  • mysql-connector-java-5.1.41-bin.jar adalah driver JDBC yang digunakan untuk mengakses database
  • mysql.config adalah file konfigurasi bernama kustom. Untuk memastikan konektor mengenali file konfigurasi Anda, tentukan jalurnya di command line. Jika tidak, konektor akan menggunakan connector-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 jdbc:mysql://127.0.0.1/dbname.

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:

  • none: tidak menggunakan penomoran
  • offset: menggunakan penomoran dengan offset baris

    Untuk menggunakan penomoran dengan offset, kueri SQL harus memiliki tanda tanya placeholder (?) untuk offset baris, yang dimulai dengan nol. Dalam setiap traversal penuh, kueri dieksekusi berulang kali hingga tidak ada hasil yang ditampilkan.

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 timestamp_column ke pernyataan SQL; jika tidak, gunakan stempel waktu saat ini dari konektor traversal.

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 contentTemplate.db.title) sebagai kolom dengan kualitas penelusuran tinggi, sedang, atau rendah. Kolom yang tidak ditentukan ditetapkan secara default ke rendah.

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.