警告:Cloud Search 參考連接器是以「現狀」提供,做為建立您自己的有效連接器的程式碼範例。這個程式碼範例需要大量自訂和測試,才能用於概念驗證或實際工作環境。如要在實際工作環境中使用,強烈建議您向我們的 Cloud Search 合作夥伴尋求協助。如需尋找合適的 Cloud Search 合作夥伴的相關說明,請與您的 Google 客戶經理聯絡。 |
您可以使用 Google Cloud Search 資料庫連接器,讓 Google Cloud Search 探索貴機構資料庫中的資料,並為其建立索引。
重要事項
只要連接器同時能夠存取網際網路和資料庫,您就可以在幾乎任何可執行 Java 應用程式的環境中,安裝及執行 Cloud Search 資料庫連接器。
系統需求
系統需求 | |
---|---|
作業系統 | Windows 或 Linux |
SQL 資料庫 | 任何具備 JDBC 4.0 以上版本驅動程式的 SQL 資料庫,包括:
|
軟體 | 可讓連接器存取資料庫的 JDBC 驅動程式 (需另外下載並安裝) |
部署連接器
下列步驟說明如何安裝及設定連接器,為指定的資料庫建立索引,並將結果傳回 Cloud Search 使用者。
必要條件
部署 Cloud Search 資料庫連接器之前,請先收集以下資訊:
- Google Workspace 私密金鑰,當中包含服務帳戶 ID。如要瞭解如何取得私密金鑰,請參閱「 設定 Google Cloud Search REST API 的存取權」。
- Google Workspace 資料來源 ID。如要瞭解如何取得資料來源 ID,請參閱「在搜尋中新增資料來源」。
步驟 1:下載並建構資料庫連接器軟體
- 從 GitHub 複製連接器存放區。
$ git clone https://github.com/google-cloudsearch/database-connector.git $ cd database-connector
- 查看所需連接器版本:
$ git checkout tags/v1-0.0.3
- 建構連接器。
$ mvn package
如要在建立連接器時略過測試,請使用mvn package -DskipTests
。 - 將連接器 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:設定資料庫連接器
- 建立文字檔案,並將其命名為
connector-config.properties
(預設) 或類似名稱。Google 建議您使用.properties
或.config
副檔名命名設定檔,並將檔案保留在與連接器相同的目錄中。如要使用其他名稱或路徑,您必須在執行連接器時指定路徑。 - 將參數新增為檔案內容中的鍵/值組合。設定檔必須指定資料來源存取、資料庫存取權、資料庫完整週遊 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
必要欄位。待存取資料庫的完整路徑,例如 |
資料庫使用者名稱和密碼 | 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}
可能的值包括:
|
遞增週遊查詢 | db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?
如果您排定漸進式週遊的時間,則為必填屬性。 查詢中的「?」是時間戳記值的必要預留位置,連接器會使用時間戳記來追蹤漸進式週遊 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...]
將內容欄 ( |
內容資料欄 | db.contentColumns = column-1[, column-2...]
指定資料庫中的內容欄。這些檔案經過格式化,並上傳至 Cloud Search,做為可供搜尋的文件內容。 如未指定值,預設值為「*」,表示所有資料欄都應用於內容。 |
Blob 資料欄 | db.blobColumn = column-name
請指定用於文件內容的單一 blob 資料欄名稱,而非內容資料欄的組合。 如果指定 blob 資料欄,且同時定義了內容資料欄,則系統會將其視為錯誤。不過,中繼資料和結構化資料資料欄定義仍可與 blob 資料欄搭配使用。 |