部署資料庫連接器

警告：Cloud Search 參考連接器是依「現狀」提供做為範例程式碼 建立專屬於您的工作連接器這段程式碼規定 進行重要自訂和測試後，再用於概念驗證 實際工作環境針對實際工作環境，強烈建議您取得相關協助 。想進一步協助您尋找合適的雲端 搜尋夥伴，請與您的 Google 客戶經理聯絡。

您可以設定 Google Cloud Search 探索貴機構的資料，並建立索引 與 Google Cloud Search 資料庫連結

重要事項

您幾乎能在所有可以執行 Java 應用程式的環境中，安裝及執行 Cloud Search 資料庫連接器，只要連接器能夠存取 網際網路和資料庫

系統需求

系統需求
作業系統 Windows 或 Linux
SQL 資料庫 使用符合 JDBC 4.0 以上驅動程式且符合 JDBC 4.0 以上驅動程式的 SQL 資料庫，包括：
  • MS SQL Server (2008、2012、2014、2016)
  • Oracle (11g、12c)
  • Google Cloud SQL
  • MySQL
軟體 供連接器用來存取資料庫的 JDBC 驅動程式 (需另外下載和安裝)

部署連接器

下列步驟說明如何安裝及設定連接器 建立指定資料庫的索引，並將結果傳回 Cloud Search 使用者。

必要條件

部署 Cloud Search 資料庫連接器之前，請收集以下資訊：

步驟 1：下載並建立資料庫連接器軟體

  1. 從 GitHub 複製連接器存放區。 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. 查看所需版本的連接器：
    $ git checkout tags/v1-0.0.3
  3. 建構連接器。 
    $ mvn package
    敬上 如要在建構連接器時略過測試，請使用 mvn package -DskipTests。
  4. 將連接器 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

步驟 2：設定資料庫連接器

  1. 建立文字檔案，並將其命名為 connector-config.properties (預設) 或類似名稱。Google 推薦 請使用 .properties 為設定檔命名 或 .config 副檔名，將檔案存放在與連接器相同的目錄中。 如果您使用其他名稱或路徑，必須在執行連接器時指定路徑。
  2. 將參數做為鍵/值組合新增至檔案內容。設定檔必須指定 資料來源存取的參數、資料庫存取參數、資料庫完整週遊 SQL 陳述式 內容欄位標題和欄定義您也可以設定其他連接器行為 搭配自選參數例如： 
    # 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

    如需資料庫特定參數的詳細說明，請參閱 設定參數參考資料。

    瞭解所有 Cloud Search 通用的參數 連接器 (例如中繼資料設定、日期時間格式和 ACL 選項)，請前往 Google 提供的連接器參數

    視情況指定遍歷 SQL 中結構定義物件的屬性 查詢參數。通常您可以為 SQL 新增別名 聲明。比方說 資料庫，而資料來源結構定義包含名為 SQL 陳述式格式為「ActorName」：SELECT …, last_name AS ActorName, … FROM … 。

步驟 3：執行資料庫連接器

以下範例假設必要元件位於 位於 Linux 系統上的目錄

如要透過指令列執行連接器，請輸入下列指令：

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]

在此情況下：

  • google-cloud-search-database-connector-v1-0.0.3.jar 是 資料庫連接器 .jar 檔案
  • mysql-connector-java-5.1.41-bin.jar 是目前使用的 JDBC 驅動程式 存取資料庫
  • mysql.config 是自訂命名的設定檔。為了確保連接器能辨識 設定檔，請在指令列中指定路徑。否則，連接器會使用 當地有 connector-config.properties 設為預設檔案名稱

連接器偵測到設定錯誤時就會回報。如果發生以下情況，系統就會回報部分錯誤 連接器會初始化，例如當記錄內容定義了資料庫欄時 (位於 db.allColumns)，但該資料欄不會用於 資料庫 (位於 db.allRecordsSql 中)。只有在發生以下情況時，系統才會偵測並回報其他錯誤： 連接器會嘗試存取資料庫以進行第一次週遊，例如無效的 SQL 陳述式語法。

設定參數參考資料

資料來源存取參數

設定 參數
資料來源 ID api.sourceId = source-ID

必要欄位。Cloud Search Google Workspace 管理員設定的來源 ID。
識別資訊來源 ID api.identitySourceId = identity-source-ID

必須啟用 ACL，才能將外部使用者和群組用於 ACL。Cloud Search 識別資訊來源 ID。
服務帳戶 api.serviceAccountPrivateKeyFile = path-to-private-key

必要欄位。Cloud Search 路徑 Google Workspace 管理員建立的服務帳戶金鑰檔案。

資料庫存取參數

設定 參數
資料庫網址 db.url = database-URL

必要欄位。 要存取的資料庫完整路徑，例如 jdbc:mysql://127.0.0.1/dbname。
資料庫使用者名稱和密碼 db.user = username
db.password = password

必要欄位。有效的使用者名稱和 連接器存取資料庫時所用的密碼。這位資料庫使用者必須 具備讀取中資料庫相關記錄的讀取權限。
JDBC 驅動程式 db.driverClass = oracle.jdbc.OracleDriver

只有在類別路徑未指定 JDBC 4.0 驅動程式時，才需要使用這個屬性。

遍歷 SQL 查詢參數

連接器會使用 SQL SELECT 週遊資料庫記錄 查詢設定檔您必須設定完整的遍歷查詢；查詢 漸進式週遊是選用功能

「完整週遊」會讀取設定建立索引的所有資料庫記錄。滿載 必須執行週遊程序，才能為 Cloud Search 建立新記錄並重新建立索引 。

「漸進式週遊」只會讀取新修改的資料庫，以及重新建立索引 和最近的項目寫入資料庫漸進式週遊發現的效率比 完整的周遊。如要使用漸進式週遊功能，資料庫必須包含時間戳記欄位 以表示修改的記錄。

連接器會依據您在 週遊排程參數。

設定 參數
完整遍歷查詢 db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

必要欄位。會針對每個完整週遊執行查詢。

連接器會在 資源 (內容、專屬 ID、ACL) 都必須存在於這項查詢中。 連接器會在啟動時執行初步驗證以偵測錯誤 和疏忽因此，請勿使用一般的「SELECT * FROM ...」 。
完整週遊分頁 db.allRecordsSql.pagination = {none | offset}

可能的值包括：

  • none：不使用分頁
  • offset：使用依據資料列偏移的分頁

    如要依偏移量使用分頁，SQL 查詢必須有預留位置問號 (?) 的值，從 0 開始。在每個完整週遊中，查詢會重複執行 直到沒有傳回任何結果
漸進式週遊查詢 db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

如果您安排漸進式週遊時間，就必須進行這項設定。

「?」查詢中為時間戳記值的必要預留位置。 連接器會使用時間戳記來追蹤漸進式 SQL 查詢之間的修改。

如要追蹤上次更新時間的資料庫時間戳記欄，請將 SQL 陳述式的 timestamp_column 別名；否則，請使用目前的時間戳記 連接器週遊

如果是第一次漸進式週遊，連接器會使用連接器的開始時間。在 Cloud Search 會儲存時間戳記， 重新啟動連接器，即可存取先前的漸進式週遊 時間戳記。
資料庫時區 db.timestamp.timezone = America/Los_Angeles

指定資料庫時間戳記所用的時區。資料庫時間戳記，用於識別新增或新記錄 資料庫記錄。預設值為連接器執行所在的當地時區。

週遊 SQL 查詢範例

  • 基本的完整週遊查詢，會讀取員工資料庫中的每筆所需記錄，以便建立索引： 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • 根據偏移值指定分頁，並將整個週遊拆分為多項查詢。

    適用於 SQL Server 2012 或 Oracle 12c (標準 SQL 2008 語法)：

    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

    或者，如為 MySQL 或 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
  • 完整遍歷查詢，套用具有別名的個別 ACL： 
    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
  • 基本漸進式週遊查詢： 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • 漸進式週遊查詢會套用具有別名的個別 ACL： 
    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 > ?
  • 使用資料庫時間戳記，而非目前時間的漸進式週遊查詢： 
    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 > ?

資料欄定義參數

下列參數會指定您在周遊陳述式中使用的欄，以及 明確識別每筆記錄。

設定 參數
所有欄 db.allColumns = column-1, column-2, ...column-N

必要欄位。識別所有資料欄 您存取資料庫時所需的 SQL 查詢所需資源資料欄 必須以這個參數在查詢中明確參照。每次 系統會將其他資料欄定義參數與這組資料欄進行比較。

範例：

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
不重複的鍵欄 db.uniqueKeyColumns = column-1[, column-2]

必要欄位。清單 單一資料庫資料欄，且該資料欄包含不重複的值或 這些資料欄中的值會共同定義專屬 ID。

Cloud Search 要求所有可搜尋的文件都必須具備專屬 ID 同一個資料來源您必須為每筆資料庫記錄定義專屬 ID 。如果您在不同的資料庫上執行多個連接器， 編入通用資料集索引，請務必指定不重複的 ID 範圍涵蓋所有文件。

範例：

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
網址連結欄 url.columns = column-1[, column-2]

必要欄位。指定一或多個已定義的有效值 可供點擊的搜尋結果所使用的網址欄名稱。 如果資料庫沒有與每筆資料庫記錄連結的相關網址，則 靜態連結則可用於每筆記錄。

不過，如果資料欄值確實為每筆記錄定義了有效的連結，則檢視畫面 應指定網址欄和格式設定值。
網址格式 url.format = https://www.example.com/{0}

定義檢視網址的格式。加上編號的參數是指 db.columns (從 0 開始依序對應)。

如未指定，則預設值為「{0}.」。

請參考下表的範例。
網址百分比編碼欄 url.columnsToEscape = column-1[, column-2]

指定 db.columns 中要進行百分比編碼的資料欄 ，然後將值加入格式化網址字串中。

網址欄範例

如何指定遍歷查詢中使用的欄以及檢視網址的格式：

  • 如何使用未使用任何資料庫記錄值的靜態網址： 
    url.format = https://www.example.com
  • 如何使用檢視網址的單一資料欄值： 
    url.format = {0}
url.columns = customer_id
  • 如何使用在 {0} 位置替代檢視網址的單一欄值： 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • 如要使用多個資料欄值建立檢視網址 (欄依順序排列)： 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

內容欄位

使用內容選項定義哪些記錄值 都屬於可搜尋內容的一部分。

設定 參數
關鍵字品質最高的搜尋資料欄 contentTemplate.db.title = column-name

必要欄位。用於搜尋索引和結果優先順序的最高品質欄。
搜尋的資料欄優先順序 contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

指定內容欄 (contentTemplate.db.title 的資料欄組合除外) 例如「高」、「中」或「低」搜尋品質欄位未指定的資料欄預設為「低」。
內容資料欄 db.contentColumns = column-1[, column-2...]

指定資料庫中的內容欄。這些資料的格式和 上傳至 Cloud Search 做為可搜尋的文件內容。

如未指定值，預設值為「*」。表示所有 欄，請使用這兩欄的內容。
Blob 資料欄 db.blobColumn = column-name

指定單一 blob 的名稱 資料欄，用於文件內容，而非內容欄的組合。

如果指定 blob 資料欄，則如果指定內容欄，就會視為錯誤 也可以定義兩者。不過，中繼資料和結構化資料欄的定義 與 blob 資料欄一起仍允許