Menerapkan konektor database

Peringatan: Konektor referensi Cloud Search disediakan "sebagaimana adanya" sebagai kode contoh untuk digunakan dalam membuat konektor Anda sendiri. Kode contoh ini memerlukan penyesuaian dan pengujian substansial sebelum digunakan dalam bukti konsep atau lingkungan production. Untuk penggunaan produksi, sebaiknya dapatkan bantuan dari salah satu partner Cloud Search kami. Untuk bantuan lebih lanjut dalam menemukan solusi Cloud Partner Penelusuran, hubungi Account Manager Google Anda.

Anda dapat menyiapkan Google Cloud Search untuk menemukan dan mengindeks data dari database 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 berjalan, asalkan konektor memiliki akses ke keduanya internet dan {i>database<i}.

Persyaratan sistem

Persyaratan sistem
Sistem operasi Windows atau Linux
Database SQL Database SQL apa pun 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)

Men-deploy konektor

Langkah-langkah berikut menjelaskan cara menginstal dan mengonfigurasi konektor untuk mengindeks database yang ditentukan dan menampilkan hasilnya ke pengguna Cloud Search.

Prasyarat

Sebelum men-deploy konektor database Cloud Search, kumpulkan informasi berikut:

Langkah 1. Mendownload dan membangun 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 tersebut:
    $ 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 memberi nama file konfigurasi dengan .properties atau ekstensi .config dan simpan file di direktori yang sama dengan konektor. Jika menggunakan nama atau jalur yang berbeda, Anda harus menentukan jalur tersebut saat menjalankan konektor.
  2. Tambahkan parameter sebagai key-value pair ke konten file. File konfigurasi harus menentukan parameter untuk akses sumber data, akses {i>database<i}, pernyataan SQL traversal penuh {i>database<i}, judul {i>field<i} 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 spesifik per database, buka Referensi parameter konfigurasi di akhir artikel ini.

    Untuk mempelajari parameter yang umum di semua Cloud Search konektor, seperti konfigurasi metadata, format penanggalan, dan opsi ACL, buka Parameter konektor yang disediakan Google.

    Jika berlaku, tentukan properti objek skema dalam SQL traversal parameter kueri. Biasanya Anda dapat menambahkan alias ke SQL pernyataan pribadi Anda. Misalnya, jika Anda memiliki film dalam database dan skema sumber data berisi definisi properti bernama "ActorName", pernyataan SQL dapat memiliki bentuk: 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 sama dengan file .jar konektor database
  • mysql-connector-java-5.1.41-bin.jar adalah driver JDBC yang digunakan untuk mengakses {i>database<i}
  • mysql.config adalah file konfigurasi dengan nama khusus. Untuk memastikan konektor mengenali file konfigurasi khusus, tentukan jalurnya pada baris perintah. Jika tidak, konektor akan menggunakan connector-config.properties di lokal Anda sebagai nama {i>file<i} {i>default<i}.

Konektor akan melaporkan error konfigurasi saat mendeteksinya. Beberapa error dilaporkan saat konektor melakukan inisialisasi, seperti saat kolom database ditentukan sebagai bagian dari konten record (di db.allColumns), tetapi kolom tersebut tidak digunakan dalam kueri SQL traversal dari database (di db.allRecordsSql). Error lainnya hanya terdeteksi dan dilaporkan saat konektor mencoba mengakses {i>database<i} untuk traversal pertama, seperti sintaks pernyataan SQL yang tidak valid.

Referensi parameter konfigurasi

Parameter akses sumber data

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

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

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

Diperlukan untuk menggunakan pengguna dan grup eksternal untuk ACL. Cloud Search ID sumber identitas yang disiapkan administrator Google Workspace.

Akun layanan api.serviceAccountPrivateKeyFile = path-to-private-key

Wajib diisi. Jalur ke Cloud Search file kunci akun layanan yang dibuat administrator Google Workspace.

Parameter akses database

Setelan Parameter
URL database db.url = database-URL

Wajib diisi. Tujuan 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 SQL traversal

Konektor menelusuri record database dengan SQL SELECT kueri dalam 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 membaca dan mengindeks ulang hanya database yang baru diubah {i>record <i}dan entri terbaru ke {i>database<i}. Traversal inkremental bisa lebih efisien daripada traversal penuh. Untuk menggunakan traversal inkremental, database Anda harus berisi kolom stempel waktu untuk menunjukkan {i>record <i}yang dimodifikasi.

Konektor menjalankan 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 berjalan untuk setiap traversal penuh.

Setiap nama kolom yang akan digunakan konektor dalam kapasitas (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 halaman dengan offset, kueri SQL harus memiliki tanda tanya placeholder (?) untuk offset baris, 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 > ?

Wajib ada jika Anda menjadwalkan traversal inkremental.

Tanda "?" dalam kueri adalah placeholder wajib untuk nilai stempel waktu. Tujuan 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 traversal konektor.

Untuk traversal inkremental pertama, konektor menggunakan waktu mulai konektor. Setelah inkremental traversal pertama, Cloud Search menyimpan stempel waktu sehingga konektor mulai ulang dapat mengakses traversal inkremental sebelumnya {i>stempel waktu<i}.

Zona waktu database db.timestamp.timezone = America/Los_Angeles

Menentukan zona waktu yang akan digunakan untuk stempel waktu database. Stempel waktu {i>database<i} yang digunakan untuk mengidentifikasi penambahan {i>record<i} baru atau rekaman database yang dimodifikasi. Setelan defaultnya adalah zona waktu lokal tempat konektor berjalan.

Contoh kueri SQL traversal

  • 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 berdasarkan offset, dan bagi satu traversal penuh menjadi beberapa kueri.

    Untuk SQL Server 2012 atau Oracle 12c (sintaks 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 secara unik mengidentifikasi setiap {i>record<i}.

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 kolom {i>database<i} tunggal 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 pencatatan database dari nilai kolom. Jika Anda menjalankan beberapa konektor pada {i>database<i} terpisah tetapi indeks ke dalam kumpulan data umum, pastikan Anda menetapkan 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 valid, yang ditetapkan nama kolom 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 dengan 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 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 menjadi 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 berkualitas tertinggi contentTemplate.db.title = column-name

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

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

Tentukan kolom konten (kecuali kumpulan kolom untuk contentTemplate.db.title) 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 di database. Tabel pivot 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

Menentukan nama blob tunggal kolom yang digunakan untuk isi 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.