部署資料庫連接器

警告：Cloud Search 參考連接器是以「現狀」提供，做為建立您自己的有效連接器的程式碼範例。這個程式碼範例需要大量自訂和測試，才能用於概念驗證或實際工作環境。如要在實際工作環境中使用，強烈建議您向我們的 Cloud Search 合作夥伴尋求協助。如需尋找合適的 Cloud Search 合作夥伴的相關說明，請與您的 Google 客戶經理聯絡。

您可以使用 Google Cloud Search 資料庫連接器，讓 Google Cloud Search 探索貴機構資料庫中的資料，並為其建立索引。

重要事項

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

系統需求

系統需求
作業系統	Windows 或 Linux
SQL 資料庫	任何具備 JDBC 4.0 以上版本驅動程式的 SQL 資料庫，包括： MS SQL Server (2008、2012、2014、2016) Oracle (11g、12c) Google Cloud SQL MySQL
軟體	可讓連接器存取資料庫的 JDBC 驅動程式 (需另外下載並安裝)

部署連接器

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

必要條件

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

• Google Workspace 私密金鑰，當中包含服務帳戶 ID。如要瞭解如何取得私密金鑰，請參閱「 設定 Google Cloud Search REST API 的存取權」。
• Google Workspace 資料來源 ID。如要瞭解如何取得資料來源 ID，請參閱「在搜尋中新增資料來源」。

步驟 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 陳述式中新增別名。例如，假設您有一個電影資料庫，且資料來源結構定義包含名為「ActorName」的屬性定義，SQL 陳述式形式可能為：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)，但該資料欄並未用於資料庫的周遊 SQL 查詢 (位於 db.allRecordsSql)。只有在連接器嘗試存取第一個週遊資料庫時 (例如無效的 SQL 陳述式語法)，才會偵測到並回報其他錯誤。

設定參數參考資料

資料來源存取參數

擺設	參數
資料來源 ID	api.sourceId = source-ID 必要欄位。Google Workspace 管理員設定的 Cloud Search 來源 ID。
識別資訊來源 ID	api.identitySourceId = identity-source-ID 必須使用外部使用者和群組來管理 ACL。Google Workspace 管理員設定的 Cloud Search 識別資訊來源 ID。
服務帳戶	api.serviceAccountPrivateKeyFile = path-to-private-key 必要欄位。Google Workspace 管理員建立的 Cloud Search 服務帳戶金鑰檔案路徑。

資料庫存取參數

擺設	參數
資料庫網址	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 的新記錄建立索引，以及為所有現有記錄重新建立索引。

「漸進式週遊」只會讀取及重新建立索引，只會讀取新修改的資料庫記錄以及資料庫中近期的項目。增量週遊會比完整週遊更有效率。如要使用增量週遊，資料庫必須包含時間戳記欄位，以表示修改後的記錄。

如果 Oracle 資料庫中的目標欄名稱不區分大小寫，請在連接器設定中指定資料欄名稱。

範例：db.allRecordsSql=SELECT CUSTOMER_ID, FIRST_NAME FROM ADDRESS_BOOK

連接器會根據您在 週遊排程參數中定義的排程執行這些週遊。

擺設	參數
完整週遊查詢	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 查詢之間的修改。 如要追蹤上次更新時間的資料庫時間戳記欄，請將 timestamp_column 別名新增至 SQL 陳述式；否則，請使用連接器週遊的目前時間戳記。 如果是第一次漸進式週遊，連接器會使用連接器的開始時間。在第一次漸進式週遊後，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 資料欄搭配使用。