Menerapkan konektor database

Peringatan: Konektor referensi Cloud Search disediakan "apa adanya" sebagai kode contoh untuk digunakan dalam membuat konektor kerja Anda sendiri. Kode contoh ini memerlukan penyesuaian dan pengujian yang substansial sebelum digunakan di lingkungan bukti konsep atau produksi. Untuk penggunaan produksi, kami sangat menyarankan Anda untuk mendapatkan bantuan dari salah satu partner Cloud Search kami. Untuk 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 yang dapat menjalankan aplikasi Java, asalkan konektor tersebut memiliki akses ke internet dan database.

Persyaratan sistem

Persyaratan sistem
Sistem operasi Windows atau Linux
Database SQL Setiap database SQL dengan driver yang sesuai dengan JDBC 4.0 atau yang lebih baru, termasuk yang berikut:
  • 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)

Menerapkan 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:
    $ 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 tersebut di 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 database penuh, 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 mengetahui deskripsi mendetail tentang parameter khusus database, buka Referensi parameter konfigurasi di akhir artikel ini.

    Untuk mempelajari parameter yang umum untuk 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 berupa: 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]

Dalam hal ini:

  • 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 saat kolom database ditetapkan 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

Setelan Parameter
ID sumber data api.sourceId = source-ID

Wajib diisi. ID sumber Cloud Search yang disiapkan administrator Google Workspace.

ID sumber identitas api.identitySourceId = identity-source-ID

Diperlukan untuk 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 diisi. Jalur ke file kunci akun layanan Cloud Search yang dibuat administrator Google Workspace.

Parameter akses database

Setelan Parameter
URL database db.url = database-URL

Wajib diisi. 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 melewati data database dengan kueri SQL SELECT dalam file konfigurasi. Anda harus mengonfigurasi kueri traversal penuh; kueri untuk traversal inkremental bersifat opsional.

Traversal penuh membaca setiap data database yang dikonfigurasi untuk pengindeksan. Diperlukan traversal penuh untuk mengindeks record baru untuk Cloud Search dan juga untuk mengindeks ulang semua record yang ada.

Traversal inkremental membaca dan mengindeks ulang hanya data database yang baru dimodifikasi dan entri terbaru ke database. Traversal inkremental dapat lebih efisien daripada traversal penuh. Untuk menggunakan traversal inkremental, database Anda harus berisi kolom stempel waktu untuk menunjukkan record yang dimodifikasi.

Konektor mengeksekusi traversal ini sesuai dengan jadwal yang Anda tentukan di parameter jadwal traversal.

Setelan Parameter
Kueri traversal penuh db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Wajib diisi. Kueri dijalankan untuk setiap traversal penuh.

Setiap nama kolom yang akan digunakan konektor dalam kapasitas apa pun (konten, ID unik, ACL) harus ada di 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 halaman dengan offset, kueri SQL harus memiliki tanda tanya placeholder (?) untuk offset baris, dimulai dengan nol. Di setiap traversal penuh, kueri dijalankan 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 > ?

Wajib jika Anda menjadwalkan traversal inkremental.

Tanda "?" dalam kueri adalah placeholder wajib untuk nilai stempel waktu. Konektor menggunakan stempel waktu untuk melacak modifikasi 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 konektor saat ini.

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 dimodifikasi. Defaultnya adalah zona waktu lokal tempat konektor dijalankan.

Contoh kueri SQL Traversal

  • Kueri traversal penuh dasar yang membaca setiap catatan minat pada database karyawan untuk pengindeksan:
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
        FROM employee
  • Tentukan penomoran halaman dengan offset dan 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 record secara unik.

Setelan Parameter
Semua kolom db.allColumns = column-1, column-2, ...column-N

Wajib ada. 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 diisi. Mencantumkan satu kolom database yang berisi nilai unik atau 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 catatan database dari nilai kolom. Jika Anda menjalankan beberapa konektor pada database terpisah tetapi mengindeks ke dalam set data umum, 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 diisi. Menentukan satu atau beberapa nama kolom valid yang 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 merujuk ke kolom yang ditentukan dalam db.columns, secara berurutan, dimulai dengan nol.

Jika tidak ditentukan, defaultnya adalah "{0}. ?

Contohnya mengikuti tabel ini.

Kolom yang dienkode persen 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 data 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 menggantikan 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.

Setelan Parameter
Kolom penelusuran dengan kualitas tertinggi contentTemplate.db.title = column-name

Wajib diisi. Kolom dengan kualitas tertinggi untuk pengindeksan penelusuran dan prioritas hasil.

Pemrioritasan 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...]

Tentukan kolom konten (kecuali kolom yang ditetapkan untuk contentTemplate.db.title) sebagai kolom dengan kualitas penelusuran tinggi, sedang, atau rendah. Kolom yang tidak ditentukan ditetapkan ke default rendah.

Kolom data konten db.contentColumns = column-1[, column-2...]

Tentukan kolom konten di database. Iklan 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 untuk digunakan sebagai konten dokumen dan 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.