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 Cloud Search được cung cấp "nguyên trạng" làm mã mẫu để sử dụng trong việc tạo trình kết nối hoạt động của riêng bạn. Mã mẫu này yêu cầu tuỳ chỉnh và thử nghiệm đáng kể trước khi được sử dụng làm bằng chứng về khái niệm hoặc môi trường thực tế. Để sử dụng phiên bản phát hành công khai, bạn nên nhờ trợ giúp từ một trong những đối tác Cloud Search của chúng tôi. Để được trợ giúp thêm trong việc tìm một nền tảng đám mây phù hợp Đối tác tìm kiếm, 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ừ bằng cách sử dụng trình kết nối cơ sở dữ liệu 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à các ứ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ả hai 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:
  • Máy chủ MS SQL (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Phần mềm Trình điều khiển JDBC cho trình kết nối sử 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á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 triển khai trình kết nối cơ sở dữ liệu Cloud Search, hãy thu thập các 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 trên 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. Xây dựng trình kết nối.
    $ mvn package
    Để bỏ qua các 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 và giải nén tệp đó:
    $ 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 và đặt tên tệp đó là connector-config.properties (mặc định) hoặc tương tự. Google đề xuất mà bạn đặt tên cho các tệp cấu hình bằng .properties hoặc .config và giữ tệp trong cùng thư mục với trình kết nối. Nếu bạn 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 toàn bộ 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 với 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 tham số dành riêng cho cơ sở dữ liệu, hãy truy cập 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 thông số chung cho tất cả Cloud Search trình kết nối, ví dụ như cấu hình siêu dữ liệu, định dạng ngày giờ và tuỳ chọn ACL, truy cập Các thông số của 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 SQL truyền tải tham số truy vấn. Thông thường, bạn có thể thêm bí danh vào SQL tuyên bố. Ví dụ: nếu bạn có một bộ phim cơ sở dữ liệu và giản đồ nguồn dữ liệu chứa định nghĩa thuộc tính có tên là "ActorName", 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 đây giả định các thành phần bắt buộc được đặt trong thư mục trên hệ thống Linux.

Để chạy trình kết nối từ 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 sử dụng để truy cập cơ sở dữ liệu
  • mysql.config là một tệp cấu hình có tên tuỳ chỉnh. Để đảm bảo trình kết nối nhận ra tệp cấu hình, 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 tại địa phương của bạn làm tên tệp mặc định.

Trình kết nối báo cáo các 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 một 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 (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 cho lần truyền tải đầu tiên, chẳng hạn như cú pháp câu lệnh SQL không hợp lệ.

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

Tham số quyền 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. Cloud Search mã nguồn 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 ACL. Cloud Search mã nguồn nhận dạng 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 Cloud Search tệp khoá tài khoản dịch vụ mà quản trị viên Google Workspace đã tạo.

Tham số truy cập cơ sở dữ liệu

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

Bắt buộc. Chiến lược phát hành đĩa đơn đườ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ủa cơ sở dữ liệu db.user = username
db.password = password

Bắt buộc. Tên người dùng hợp lệ và mật khẩu 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 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 SQL SELECT 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 đủ; truy vấn cho truyền tải gia tăng là không bắt buộc.

Truyền tải đầy đủ sẽ đọc mọi bản ghi cơ sở dữ liệu được định cấu hình để lập chỉ mục. Đầy truyền tải là bắt buộc để 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ả bản ghi hiện có.

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

Trình kết nối thực thi những lần truyền tải này theo lịch biểu mà bạn xác định trong tham 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 chạy cho mọi lần truyền tải đầy đủ.

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ội dung, ID duy nhất, ACL) phải có trong truy vấn này. Chiến lược phát hành đĩa đơn trình kết nối thực hiện một số xác minh sơ bộ khi khởi động để phát hiện lỗi thiếu sót. Vì lý do này, không sử dụng "CHỌN * TỪ ..." chung chung truy vấn.

Phân trang truyền tải đầy đủ db.allRecordsSql.pagination = {none | offset}

Giá trị có thể là:

  • none: không sử dụng tính năng phân trang
  • offset: sử dụng tính năng phân trang theo mức chênh lệch hàng

    Để sử dụng tính năng phân trang theo mức chênh lệch, truy vấn SQL phải có một dấu chấm hỏi phần giữ chỗ (?) cho độ 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 > ?

Đây là trường bắt buộc nếu bạn lên lịch truyền tải dần dần.

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

Để theo dõi cột dấu thời gian của cơ sở dữ liệu cho thời gian cập nhật gần nhất, hãy thêm Bí danh timestamp_column cho 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 truyền tải trình kết nối.

Đối với lần truyền tải gia tăng đầ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 truyền tải gia tăng đầu tiên, Cloud Search lưu trữ dấu thời gian để khởi động lại trình kết nối có thể truy cập truyền tải gia tăng trước đó .

Múi giờ của cơ sở dữ liệu db.timestamp.timezone = America/Los_Angeles

Chỉ định múi giờ để 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 được dùng để xác định những bản ghi mới được thêm vào hoặc bản ghi mới bản ghi cơ sở dữ liệu đã sửa đổi. Mặc định là 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 nhằm 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ộ 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 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 gia tăng 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 gia tăng áp dụng các ACL riêng lẻ với 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 gia tăng 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

Những tham số sau đây chỉ định các cột mà bạn sử dụng trong câu lệnh truyền tải và để xác định duy nhất 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 tất cả các cột được yêu cầu trong truy vấn SQL khi truy cập cơ sở dữ liệu. 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 tham số định nghĩa cột khác đượ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ác cột khoá duy nhất db.uniqueKeyColumns = column-1[, column-2]

Bắt buộc. Liệt kê một trong hai một cột cơ sở dữ liệu chứa các giá trị duy nhất hoặc bằng tổ hợp các giá trị các cột mà các giá trị của nhau 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 có khả năng xác định 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ị 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 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 một hoặc nhiều hợp lệ, được xác định tên của các cột dùng cho URL dùng trong kết quả tìm kiếm có thể nhấp vào. Đối với cơ sở dữ liệu không có URL liên quan nào được liên kết với từng bản ghi cơ sở dữ liệu, đường liên kết tĩnh cho mỗi bản ghi.

Tuy nhiên, nếu các giá trị trong cột xác định một đường liên kết hợp lệ cho mỗi bản ghi, thì khung hiển thị Bạn phải chỉ định các giá trị cấu hình định dạng và cột URL.

Định dạng URL url.format = https://www.example.com/{0}

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

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

Các ví dụ sau bảng này.

Cột được mã hoá 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á phần trăm trước khi đưa chúng 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 URL tĩnh không dùng giá trị của bản ghi cơ sở dữ liệu:
    url.format = https://www.example.com
  • Cách sử dụng giá trị cột duy nhất là URL chế độ xem:
    url.format = {0}
    url.columns = customer_id
  • Để 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
  • Để 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

Dùng lựa chọn nội dung để xác định giá trị bản ghi nên nằm trong 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 có chất lượng cao nhất để ưu tiên kết quả và lập chỉ mục tìm kiếm.

Mức độ ưu tiên của 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ột nội dung (ngoại trừ nhóm cột cho contentTemplate.db.title) các trường có chất lượng tìm kiếm cao, trung bình hoặc thấp. Các cột không xác định được đặt mặc định là 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 báo cáo 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.

Nếu bạn không chỉ định giá trị, giá trị mặc định sẽ là "*" điều này cho thấy tất cả nội dung.

Cột Blob db.blobColumn = column-name

Chỉ định tên của một blob để 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 được xem là lỗi nếu cột nội dung cũng được xác định. Tuy nhiên, siêu dữ liệu và cột dữ liệu có cấu trúc có định nghĩa vẫn được phép cùng với các cột blob.