Triển khai trình kết nối cơ sở dữ liệu

Cảnh báo: Các trình kết nối tham chiếu của Cloud Search được cung cấp "nguyên trạng" dưới dạng mã mẫu để tạo các trình kết nối hoạt động của riêng bạn. Mã mẫu này yêu cầu bạn phải tuỳ chỉnh và kiểm thử đáng kể trước khi sử dụng trong môi trường thực tế hoặc môi trường thực tế. Để sử dụng trong hoạt động sản xuất, bạn nên yêu cầu sự trợ giúp của một trong các đối tác Cloud Search của chúng tôi. Để được trợ giúp thêm về cách tìm một đối tác phù hợp trên Cloud Search, hãy liên hệ với Người quản lý tài khoản của Google.

Bạn có thể thiết lập Google Cloud Search để khám phá và lập chỉ mục dữ liệu từ các cơ sở dữ liệu của tổ chức mình bằng cách sử dụng trình kết nối cơ sở dữ liệu của Google Cloud Search.

Điểm quan trọng cần lưu ý

Bạn có thể cài đặt và chạy trình kết nối cơ sở dữ liệu Cloud Search trong hầu hết mọi môi trường mà ứng dụng Java có thể chạy, miễn là trình kết nối có quyền truy cập vào cả Internet và cơ sở dữ liệu.

Yêu cầu hệ thống

Yêu cầu hệ thống
Hệ điều hành Windows hoặc Linux
Cơ sở dữ liệu SQL Mọi cơ sở dữ liệu SQL có trình điều khiển tuân thủ JDBC 4.0 trở lên, bao gồm:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Phần mềm Trình điều khiển JDBC để trình kết nối dùng để truy cập cơ sở dữ liệu (được tải xuống và cài đặt riêng)

Triển khai trình kết nối

Các bước sau đây mô tả cách cài đặt và định cấu hình trình kết nối để lập chỉ mục cơ sở dữ liệu được chỉ định và trả về kết quả cho người dùng Cloud Search.

Điều kiện tiên quyết

Trước khi bạn triển khai trình kết nối cơ sở dữ liệu Cloud Search, hãy thu thập những thông tin sau:

Bước 1. Tải xuống và xây dựng phần mềm trình kết nối cơ sở dữ liệu

  1. Sao chép kho lưu trữ trình kết nối từ GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Kiểm tra phiên bản trình kết nối mong muốn:
    $ git checkout tags/v1-0.0.3
  3. Tạo trình kết nối. 
    $ mvn package
    Để bỏ qua các bài kiểm thử khi tạo trình kết nối, hãy sử dụng mvn package -DskipTests.
  4. Sao chép tệp zip của trình kết nối vào thư mục cài đặt trên máy rồi giải nén: 
    $ 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

Bước 2. Định cấu hình trình kết nối cơ sở dữ liệu

  1. Tạo một tệp văn bản rồi đặt tên tệp đó là connector-config.properties (mặc định) hoặc tương tự. Bạn nên đặt tên cho các tệp cấu hình bằng đuôi .properties hoặc .config và để tệp trong cùng thư mục với trình kết nối. Nếu sử dụng tên hoặc đường dẫn khác, bạn phải chỉ định đường dẫn khi chạy trình kết nối.
  2. Thêm thông số dưới dạng cặp khoá/giá trị vào nội dung tệp. Tệp cấu hình phải chỉ định các tham số truy cập nguồn dữ liệu, truy cập cơ sở dữ liệu, câu lệnh SQL truyền tải đầy đủ cơ sở dữ liệu, tiêu đề trường nội dung và định nghĩa cột. Bạn cũng có thể định cấu hình hành vi khác của trình kết nối bằng các tham số không bắt buộc. Ví dụ: 
    # 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

    Để biết nội dung mô tả chi tiết về các thông số dành riêng cho cơ sở dữ liệu, hãy xem Tài liệu tham khảo về thông số cấu hình ở cuối bài viết này.

    Để tìm hiểu về các tham số phổ biến cho mọi trình kết nối Cloud Search, chẳng hạn như cấu hình siêu dữ liệu, định dạng ngày giờ và tuỳ chọn Danh sách kiểm soát quyền truy cập (ACL), hãy chuyển đến phần Tham số trình kết nối do Google cung cấp.

    Nếu có thể, hãy chỉ định các thuộc tính của đối tượng giản đồ trong tham số truy vấn SQL truyền tải. Thông thường, bạn có thể thêm bí danh vào câu lệnh SQL. Ví dụ: nếu bạn có cơ sở dữ liệu phim và giản đồ nguồn dữ liệu chứa định nghĩa thuộc tính có tên là "ActorName", thì câu lệnh SQL có thể có dạng: SELECT …, last_name AS ActorName, … FROM … .

Bước 3. Chạy trình kết nối cơ sở dữ liệu

Ví dụ sau giả định các thành phần bắt buộc nằm trong thư mục cục bộ trên hệ thống Linux.

Để chạy trình kết nối qua dòng lệnh, hãy nhập lệnh sau: 

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]

Trong trường hợp:

  • google-cloud-search-database-connector-v1-0.0.3.jar là tệp .jar của trình kết nối cơ sở dữ liệu
  • mysql-connector-java-5.1.41-bin.jar là trình điều khiển JDBC đang được dùng để truy cập vào cơ sở dữ liệu
  • mysql.config là tệp cấu hình được đặt tên tuỳ chỉnh. Để đảm bảo trình kết nối nhận ra tệp cấu hình của bạn, hãy chỉ định đường dẫn của tệp trên dòng lệnh. Nếu không, trình kết nối sẽ sử dụng connector-config.properties trong thư mục cục bộ làm tên tệp mặc định.

Trình kết nối báo cáo lỗi cấu hình khi phát hiện thấy lỗi. Một số lỗi được báo cáo khi trình kết nối khởi chạy, chẳng hạn như khi cột cơ sở dữ liệu được xác định là một phần của nội dung bản ghi (trong db.allColumns), nhưng cột này không được dùng trong truy vấn SQL truyền tải của cơ sở dữ liệu (trong db.allRecordsSql). Các lỗi khác chỉ được phát hiện và báo cáo khi trình kết nối cố gắng truy cập cơ sở dữ liệu trong lần truyền tải đầu tiên, chẳng hạn như cú pháp SQL không hợp lệ.

Tài liệu tham khảo về thông số cấu hình

Thông số truy cập vào nguồn dữ liệu

Xem xét Thông số
Mã nguồn dữ liệu api.sourceId = source-ID

Bắt buộc. Mã nguồn trên Cloud Search mà quản trị viên Google Workspace đã thiết lập.
Mã nguồn nhận dạng api.identitySourceId = identity-source-ID

Bắt buộc sử dụng người dùng và nhóm bên ngoài cho các ACL. Mã nhận dạng nguồn nhận dạng trên Cloud Search mà quản trị viên Google Workspace đã thiết lập.
Tài khoản dịch vụ api.serviceAccountPrivateKeyFile = path-to-private-key

Bắt buộc. Đường dẫn đến tệp khoá tài khoản dịch vụ Cloud Search mà quản trị viên Google Workspace đã tạo.

Các tham số truy cập cơ sở dữ liệu

Xem xét Thông số
URL cơ sở dữ liệu db.url = database-URL

Bắt buộc. Đường dẫn đầy đủ của cơ sở dữ liệu cần truy cập, chẳng hạn như jdbc:mysql://127.0.0.1/dbname.
Tên người dùng và mật khẩu cơ sở dữ liệu db.user = username
db.password = password

Bắt buộc. Tên người dùng và mật khẩu hợp lệ mà trình kết nối sử dụng để truy cập cơ sở dữ liệu. Người dùng cơ sở dữ liệu này phải có quyền đọc đối với các bản ghi liên quan của cơ sở dữ liệu đang được đọc.
Trình điều khiển JDBC db.driverClass = oracle.jdbc.OracleDriver

Chỉ bắt buộc nếu trình điều khiển JDBC 4.0 chưa được chỉ định trong đường dẫn lớp.

Tham số truy vấn SQL truyền tải

Trình kết nối truyền tải các bản ghi cơ sở dữ liệu bằng các truy vấn SELECT của SQL trong tệp cấu hình. Bạn phải định cấu hình một truy vấn truyền tải đầy đủ; các truy vấn cho việc truyền tải tăng dần là không bắt buộc.

Truyền tải đầy đủ đọc mọi bản ghi cơ sở dữ liệu được định cấu hình để lập chỉ mục. Bạn cần phải truyền tải toàn bộ để lập chỉ mục các bản ghi mới cho Cloud Search và cũng để lập chỉ mục lại tất cả các bản ghi hiện có.

Phương thức Truyền tải tăng dần đọc và lập chỉ mục lại các bản ghi cơ sở dữ liệu mới được sửa đổi và các mục nhập gần đây vào cơ sở dữ liệu. Truyền tải tăng dần có thể hiệu quả hơn truyền tải toàn bộ. Để sử dụng truyền tải tăng dần, cơ sở dữ liệu của bạn phải chứa các trường dấu thời gian để cho biết các bản ghi đã được sửa đổi.

Trình kết nối thực thi những hoạt động truyền tải này theo lịch biểu mà bạn xác định trong thông số lịch biểu truyền tải.

Xem xét Thông số
Truy vấn truyền tải đầy đủ db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Bắt buộc. Truy vấn sẽ chạy cho mỗi lần truyền tải toàn bộ.

Mọi tên cột mà trình kết nối sẽ sử dụng trong bất kỳ dung lượng nào (nội dung, ID duy nhất, ACL) đều phải có trong truy vấn này. Trình kết nối thực hiện một số quy trình xác minh sơ bộ khi khởi động để phát hiện lỗi và thiếu sót. Vì lý do này, bạn không nên sử dụng cụm từ tìm kiếm "CHỌN * TỪ ..." chung.
Phân trang truyền tải đầy đủ db.allRecordsSql.pagination = {none | offset}

Giá trị có thể là:

  • none (không): không sử dụng tính năng phân trang
  • offset: sử dụng tính năng phân trang theo độ lệch hàng

    Để sử dụng tính năng phân trang theo độ lệch, truy vấn SQL phải có dấu chấm hỏi trong phần giữ chỗ (?) tương ứng với độ lệch hàng, bắt đầu bằng 0. Trong mỗi lần truyền tải đầy đủ, truy vấn sẽ được thực thi nhiều lần cho đến khi không có kết quả nào được trả về.
Truy vấn truyền tải tăng dần db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Bắt buộc nếu bạn lên lịch truyền tải dần.

Dấu "?" trong truy vấn là phần giữ chỗ bắt buộc cho giá trị dấu thời gian. Trình kết nối sử dụng dấu thời gian để theo dõi nội dung sửa đổi giữa các truy vấn SQL truyền tải tăng dần.

Để theo dõi cột dấu thời gian của cơ sở dữ liệu cho lần cập nhật gần đây nhất, hãy thêm bí danh timestamp_column vào câu lệnh SQL; nếu không, hãy sử dụng dấu thời gian hiện tại của quá trình truyền tải trình kết nối.

Đối với truyền tải tăng dần đầu tiên, trình kết nối sử dụng thời gian bắt đầu của trình kết nối. Sau lần truyền tải tăng dần đầu tiên, Cloud Search sẽ lưu trữ dấu thời gian để trình kết nối khởi động lại có thể truy cập dấu thời gian truyền tải tăng dần trước đó.
Múi giờ của cơ sở dữ liệu db.timestamp.timezone = America/Los_Angeles

Chỉ định múi giờ để sử dụng cho dấu thời gian của cơ sở dữ liệu. Dấu thời gian của cơ sở dữ liệu dùng để xác định các bản ghi mới được bổ sung hoặc bản ghi cơ sở dữ liệu mới được sửa đổi. Theo mặc định, múi giờ địa phương nơi trình kết nối đang chạy.

Ví dụ về truy vấn SQL truyền tải

  • Truy vấn truyền tải đầy đủ cơ bản để đọc mọi bản ghi quan tâm trong cơ sở dữ liệu của nhân viên để lập chỉ mục: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Chỉ định phân trang theo độ lệch và chia toàn bộ quá trình truyền tải thành nhiều truy vấn.

    Đối với SQL Server 2012 hoặc Oracle 12c (cú pháp SQL 2008 chuẩn):

    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

    hoặc đối với MySQL hoặc 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
  • Truy vấn truyền tải đầy đủ áp dụng các ACL riêng lẻ với các bí danh: 
    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
  • Truy vấn truyền tải tăng dần cơ bản: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Truy vấn truyền tải tăng dần áp dụng từng ACL riêng lẻ với các bí danh: 
    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 > ?
  • Truy vấn truyền tải tăng dần sử dụng dấu thời gian của cơ sở dữ liệu thay vì thời gian hiện tại: 
    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 > ?

Tham số định nghĩa cột

Các tham số sau đây chỉ định cột mà bạn sử dụng trong câu lệnh truyền tải và xác định riêng từng bản ghi.

Xem xét Thông số
Tất cả các cột db.allColumns = column-1, column-2, ...column-N

Bắt buộc. Xác định mọi cột bắt buộc trong một truy vấn SQL khi truy cập vào cơ sở dữ liệu. Các cột được xác định bằng tham số này phải được tham chiếu rõ ràng trong các truy vấn. Mọi thông số định nghĩa cột khác sẽ được so sánh với tập hợp cột này.

Ví dụ:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Cột khoá duy nhất db.uniqueKeyColumns = column-1[, column-2]

Bắt buộc. Liệt kê một cột cơ sở dữ liệu chứa giá trị duy nhất hoặc bằng một tổ hợp các cột mà giá trị của các cột đó cùng xác định một mã nhận dạng duy nhất.

Cloud Search yêu cầu mỗi tài liệu có thể tìm kiếm phải có một giá trị nhận dạng duy nhất trong một nguồn dữ liệu. Bạn phải xác định được một mã nhận dạng duy nhất cho mỗi bản ghi cơ sở dữ liệu từ các giá trị trong cột. Nếu bạn chạy nhiều trình kết nối trên các cơ sở dữ liệu riêng biệt nhưng lập chỉ mục vào một tập dữ liệu chung, hãy đảm bảo rằng bạn chỉ định một mã nhận dạng duy nhất trên tất cả tài liệu.

Ví dụ:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Cột liên kết URL url.columns = column-1[, column-2]

Bắt buộc. Chỉ định ít nhất một tên đã xác định và hợp lệ của các cột dùng cho URL dùng cho kết quả tìm kiếm có thể nhấp. Đối với các cơ sở dữ liệu không có URL liên kết với từng bản ghi cơ sở dữ liệu, bạn có thể dùng một đường liên kết tĩnh cho mọi bản ghi.

Tuy nhiên, nếu giá trị cột xác định một đường liên kết hợp lệ cho mỗi bản ghi, thì bạn phải chỉ định cột URL xem và giá trị cấu hình định dạng.
Định dạng URL url.format = https://www.example.com/{0}

Xác định định dạng của URL chế độ xem. Tham số được đánh số là các cột được chỉ định theo thứ tự trong db.columns, bắt đầu bằng số 0.

Nếu không được chỉ định, giá trị mặc định sẽ là "{0}."

Các ví dụ nằm trong bảng này.
Cột được mã hóa phần trăm cho URL url.columnsToEscape = column-1[, column-2]

Chỉ định các cột từ db.columns có giá trị sẽ được mã hoá theo phần trăm trước khi đưa các cột này vào chuỗi URL được định dạng.

Ví dụ về cột URL

Để chỉ định các cột được dùng trong truy vấn truyền tải và định dạng của URL chế độ xem:

  • Cách dùng một URL tĩnh không dùng giá trị bản ghi cơ sở dữ liệu: 
    url.format = https://www.example.com
  • Cách sử dụng một giá trị cột duy nhất là URL chế độ xem: 
    url.format = {0}
url.columns = customer_id
  • Cách sử dụng một giá trị cột duy nhất được thay thế vào URL chế độ xem tại vị trí {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Cách sử dụng nhiều giá trị cột nhằm tạo URL chế độ xem (các cột phụ thuộc vào thứ tự): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Trường nội dung

Sử dụng các lựa chọn nội dung để xác định những giá trị bản ghi cần được đưa vào nội dung có thể tìm kiếm.

Xem xét Thông số
Cột tìm kiếm chất lượng cao nhất contentTemplate.db.title = column-name

Bắt buộc. Cột chất lượng cao nhất cho việc lập chỉ mục tìm kiếm và mức độ ưu tiên kết quả.
Ưu tiên cột cho tìm kiếm contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Chỉ định các cột nội dung (ngoại trừ nhóm cột cho contentTemplate.db.title) thành các trường chất lượng tìm kiếm cao, trung bình hoặc thấp. Các cột chưa được chỉ định sẽ được đặt mặc định thành thấp.
Cột dữ liệu nội dung db.contentColumns = column-1[, column-2...]

Chỉ định cột nội dung trong cơ sở dữ liệu. Các tài liệu này được định dạng và tải lên Cloud Search dưới dạng nội dung tài liệu có thể tìm kiếm được.

Nếu bạn không chỉ định một giá trị, giá trị mặc định sẽ là "*" cho biết rằng tất cả các cột phải được dùng cho nội dung.
Cột Blob db.blobColumn = column-name

Chỉ định tên của một cột blob duy nhất để sử dụng cho nội dung tài liệu thay vì kết hợp các cột nội dung.

Nếu bạn chỉ định cột blob, thì cột này sẽ bị coi là lỗi nếu bạn cũng xác định các cột nội dung. Tuy nhiên, bạn vẫn được phép định nghĩa cột siêu dữ liệu và cột dữ liệu có cấu trúc cùng với các cột blob.