本指南適用對象為 Google Cloud Search CSV (半形逗號分隔值) 連接器管理員，也就是負責下載、設定、執行及監控連接器的任何人。
本指南提供執行 CSV 連接器部署作業的相關操作說明：
- 下載 Google Cloud Search CSV 連接器軟體
- 設定連接器，以便與特定 CSV 資料來源搭配使用
- 部署及執行連接器
如要瞭解本文中的概念，您必須熟悉 Google Workspace、CSV 檔案和存取控制清單 (ACL) 的基本概念。
Google Cloud Search CSV 連接器總覽
Cloud Search CSV 連接器可搭配任何半形逗號分隔值 (CSV) 文字檔使用。CSV 檔案會儲存表格資料，檔案中的每一行都是資料記錄。
Google Cloud Search 的 CSV 連接器會從 CSV 檔案中擷取個別資料列，並透過 Cloud Search 的 Indexing API 將這些資料列編入 Cloud Search。成功編入索引後，您就能透過 Cloud Search 的用戶端或 Cloud Search 的 Query API 搜尋 CSV 檔案中的個別資料列。CSV 連接器也支援使用 ACL 控管使用者對搜尋結果中內容的存取權。
Google Cloud Search CSV 連接器可安裝在 Linux 或 Windows 上。部署 Google Cloud Search CSV 連接器前，請確認您已具備下列必要元件：
- 在執行 Google Cloud Search CSV 連接器的電腦上安裝 Java JRE 1.8
在 Google Cloud Search 和資料來源之間建立關係時，需要使用下列 Google Workspace 資訊：
- Google Workspace 私密金鑰 (包含服務帳戶 ID)
- Google Workspace 資料來源 ID
通常，網域的 Google Workspace 管理員可以為您提供這些憑證。
部署步驟
如要部署 Google Cloud Search CSV 連接器，請按照下列步驟操作：
- 安裝 Google Cloud Search CSV 連接器軟體
- 指定 CSV 連接器設定
- 設定 Google Cloud Search 資料來源的存取權
- 設定 CSV 檔案存取權
- 指定要建立索引的資料欄名稱、不重複索引鍵資料欄和日期時間資料欄
- 指定要用於可點選搜尋結果網址的資料欄
- 指定中繼資料資訊和欄格式
- 排程資料遍歷
- 指定存取控制清單 (ACL) 選項
1. 安裝 SDK
將 SDK 安裝到本機 Maven 存放區。
從 GitHub 複製 SDK 存放區。
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
查看所需的 SDK 版本：
$ git checkout tags/v1-0.0.3
建構連接器：
$ mvn package
將連接器 ZIP 檔案複製到本機安裝目錄：
$ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir $ cd installation-dir $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip $ cd google-cloudsearch-csv-connector-v1-0.0.3
2. 指定 CSV 連接器設定
連接器管理員可控管 CSV 連接器的行為，以及在連接器設定檔中定義參數的屬性。可設定的參數包括：
- 資料來源存取權
- CSV 檔案的位置
- CSV 欄位定義
- 定義不重複 ID 的資料欄
- 檢索選項
- 限制資料存取權的存取控管清單選項
如要讓連接器正確存取 CSV 檔案並為相關內容建立索引，您必須先建立設定檔。
如要建立設定檔，請按照下列步驟操作：
- 開啟您選擇的文字編輯器，並為設定檔命名。
按照下列各節所述，在檔案內容中新增 鍵=值組合。 - 儲存並命名設定檔。
Google 建議您將設定檔命名為connector-config.properties，這樣執行連接器時就不需要額外的命令列參數。
您可以在指令列上指定設定檔路徑，因此不需要標準檔案位置。不過，請將設定檔放在連接器所在的目錄中，以便簡化連接器的追蹤和執行作業。
為確保連接器能辨識設定檔，請在指令列上指定其路徑。否則，連接器會使用本機目錄中的 connector-config.properties 做為預設檔案名稱。如要瞭解如何在指令列上指定設定路徑，請參閱「執行 Cloud Search CSV 連接器」。
3. 設定 Google Cloud Search 資料來源的存取權
每個設定檔都必須指定第一個參數，這些參數是存取 Cloud Search 資料來源所需的參數，如下表所示。一般來說，您需要資料來源 ID、服務帳戶 ID，以及服務帳戶私密金鑰檔案的路徑，才能設定連接器的 Cloud Search 存取權。如要瞭解設定資料來源的必要步驟，請參閱「管理第三方資料來源」一文。
| 設定 | 參數 |
| 資料來源 ID | api.sourceId=1234567890abcdef
必要欄位。Google Workspace 管理員設定的 Google Cloud Search 來源 ID，詳情請參閱「管理第三方資料來源」。 |
| 服務帳戶私密金鑰檔案的路徑 | api.serviceAccountPrivateKeyFile=./PrivateKey.json
必要欄位。Google Cloud Search CSV 連接器存取權的 Google Cloud Search 服務帳戶金鑰檔案。 |
| 識別資訊來源 ID | api.identitySourceId=x0987654321
如要使用外部使用者和群組，則必須提供此值。Google Workspace 管理員設定的 Google Cloud Search 識別資訊來源 ID。 |
4. 設定 CSV 檔案參數
連接器必須先識別檔案路徑，才能遍歷 CSV 檔案並從中擷取資料進行索引。您也可以指定檔案格式和檔案編碼類型。新增下列參數，在設定檔中指定 CSV 檔案屬性。
| 設定 | 參數 |
| CSV 檔案路徑 | csv.filePath=./movie_content.csv
必要欄位。要存取的 CSV 檔案路徑，以及要用於建立索引的內容。 |
| 檔案格式 | csv.format=DEFAULT
檔案格式。可能的值來自 Apache Commons CSV CSVFormat 類別。 格式值包括： |
| 檔案格式修飾符 | csv.format.withMethod=value
修改 Cloud Search 處理檔案的方式。可能的方法來自 Apache Commons CSV CSVFormat 類別，包括採用單一字元、字串或布林值的方法。 舉例來說，如要指定分號做為分隔符，請使用 |
| 檔案編碼類型 | csv.fileEncoding=UTF-8
Cloud Search 讀取檔案時使用的 Java 字元集。如未指定，Cloud Search 會使用平台的預設字元集。 |
5. 指定要索引的資料欄名稱和不重複索引鍵欄
如要讓連接器存取 CSV 檔案並為檔案建立索引，您必須在設定檔中提供資料欄定義資訊。如果設定檔未包含用來指定索引和唯一鍵資料欄的資料欄名稱參數，系統會使用預設值。
| 設定 | 參數 |
| 要建立索引的資料欄 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
要從 CSV 檔案建立索引的欄名稱。如果未設定 |
| 不重複索引鍵欄 | csv.uniqueKeyColumns=movieId
CSV 欄的值會用來產生每筆記錄的專屬 ID。如果未指定，CSV 記錄的雜湊值應做為其不重複值鍵。預設值為記錄的雜湊碼。 |
6. 指定要用於可點選搜尋結果網址的資料欄
使用者使用 Google Cloud Search 進行搜尋時，系統會回應顯示結果頁面，其中包含每個結果的可點選網址。如要啟用這項功能，您必須在設定檔中新增下表所示的參數。
| 設定 | 參數 |
| 搜尋結果網址格式 | url.format=https://mymoviesite.com/movies/{0}
必要欄位。用於建構 CSV 內容檢視網址的格式。 |
| 搜尋結果網址參數。 | url.columns=movieId
必要欄位。CSV 欄名稱，其值會用於產生記錄的檢視網址。 |
| 要轉義的搜尋結果網址參數 | url.columnsToEscape=movieId
選用設定。值會經過網址轉義，以產生有效的檢視網址。 |
7. 指定中繼資料資訊、欄格式和搜尋品質
您可以在設定檔中加入參數，指定下列項目：
中繼資料設定參數
「中繼資料設定參數」說明用於填入項目中繼資料的 CSV 欄位。如果設定檔不含這些參數，系統會使用預設值。下表列出這些參數。
| 設定 | 參數 |
| 標題 | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
中繼資料屬性，內含與文件標題相對應的值。預設值為空白字串。 |
| 網址 | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
中繼資料屬性，其中包含搜尋結果文件網址的值。 |
| 建立時間戳記 | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
包含文件建立時間戳記值的中繼資料屬性。 |
| 上次修改時間 | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
中繼資料屬性，包含文件上次修改時間戳記的值。 |
| 文件語言 | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
要建立索引的文件內容語言。 |
| 結構定義物件類型 | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
連接器使用的物件類型，如結構定義所定義。如果未指定此屬性，連接器就不會為任何結構化資料建立索引。 |
日期時間格式
日期時間格式會指定中繼資料屬性中預期的格式。如果設定檔案未包含這個參數，系統會使用預設值。下表列出這個參數。
| 設定 | 參數 |
| 其他日期時間格式 | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
以分號分隔的清單，其中包含其他 java.time.format.DateTimeFormatter 格式。剖析中繼資料或結構定義中任何日期或日期時間欄位的字串值時，會使用這些模式。預設值為空白清單，但系統一律支援 RFC 3339 和 RFC 1123 格式。 |
欄格式
資料欄格式會指定應納入可搜尋內容的資料欄資訊。如果設定檔未包含這些參數，系統會使用預設值。下表列出這些參數。
| 設定 | 參數 |
| 略過標頭 | csv.skipHeaderRecord=true
布林值。忽略 CSV 檔案中的標頭記錄 (第一行)。如果您已設定 |
| 多值欄 | csv.multiValueColumns=genre,actors
CSV 檔案中含有多個值的資料欄名稱。預設值為空白字串。 |
| 多值欄的分隔符號 | csv.multiValue.genre=;
多值欄的分隔符號。預設分隔符號為半形逗號。 |
搜尋品質
Cloud Search CSV 連接器可自動為資料欄位套用 HTML 格式。連接器會在執行作業的開頭定義資料欄位，然後使用內容範本設定每個資料記錄的格式，再將資料記錄上傳至 Cloud Search。
內容範本會定義每個欄位值在搜尋時的重要性。標題欄位為必要欄位，且定義為最高優先順序。您可以為所有其他內容欄位指定搜尋品質重要程度：高、中或低。未在特定類別中定義的內容欄位，預設為低優先順序。下表列出這些參數。
| 設定 | 參數 |
| 內容標題 | contentTemplate.csv.title=movieTitle
內容標題是搜尋品質最高的欄位。 |
| 內容欄位搜尋品質高 | contentTemplate.csv.quality.high=actors
內容欄位已獲得高搜尋品質值。預設值為空字串。 |
| 內容欄位搜尋品質不佳 | contentTemplate.csv.quality.low=genre
內容欄位獲得的搜尋品質值偏低。預設值為空字串。 |
| 內容欄位搜尋品質為中等 | contentTemplate.csv.quality.medium=description
內容欄位已獲得中等搜尋品質值。預設值為空字串。 |
| 未指定的內容欄位 | contentTemplate.csv.unmappedColumnsMode=IGNORE
連接器處理未指定內容欄位的方式。有效值如下：
|
8. 排定資料檢視作業
檢索是指連接器從資料來源 (在本例中為 CSV 檔案) 中探索內容的程序。當 CSV 連接器執行時，會逐一檢視 CSV 檔案的資料列，並透過索引 API 為每個資料列建立索引，以便在 Cloud Search 中使用。
完整檢查會為檔案中的所有欄建立索引。增量檢查作業只會為上次檢查後新增或修改的資料欄建立索引。CSV 連接器只會執行完整的檢索作業。不會執行漸進式遍歷。
排程參數會決定連接器在兩次檢索之間的等待時間。如果設定檔案不含排程參數，系統會使用預設值。下表列出這些參數。
| 設定 | 參數 |
| 間隔後的完整檢查 | schedule.traversalIntervalSecs=7200
連接器會在指定間隔後執行完整的遍歷作業。以秒為單位指定檢查間隔。預設值為 86400 (一天的秒數)。 |
| 連接器啟動時的完整檢查 | schedule.performTraversalOnStart=false
連接器會在啟動時執行完整的檢查作業，而不會等待第一個間隔到期。預設值為 true。 |
9. 指定存取控制清單 (ACL) 選項
Google Cloud Search CSV 連接器支援透過 ACL 設定權限，以便控管搜尋結果中 CSV 檔案內容的存取權。您可以使用多種 ACL 選項，保護使用者對已編入索引的記錄存取權。
如果您的存放區有與每份文件相關聯的個別 ACL 資訊，請上傳所有 ACL 資訊，以便在 Cloud Search 中控制文件存取權。如果您的存放區提供的 ACL 資訊不完整或沒有提供，您可以在 SDK 提供給連接器的下列參數中，提供預設的 ACL 資訊。
連接器會依賴在設定檔中啟用的預設 ACL。如要啟用預設 ACL，請將 defaultAcl.mode 設為 none 以外的任何模式，並使用 defaultAcl.* 進行設定
| 設定 | 參數 |
| ACL 模式 | defaultAcl.mode=fallback
必要欄位。CSV 連接器會依賴預設 ACL 功能。連接器僅支援備用模式。 |
| 預設 ACL 名稱 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
選用設定。可讓您覆寫連接器用於設定預設 ACL 的虛擬容器名稱。預設值為「DEFAULT_ACL_VIRTUAL_CONTAINER」。如果有多個連接器在同一個資料來源中為內容建立索引，建議您覆寫這個值。 |
| 預設公開 ACL | defaultAcl.public=true
整個存放區使用的預設 ACL 會設為公開網域存取權。預設值為 false。 |
| 常見的 ACL 群組讀取者 | defaultAcl.readers.groups=google:group1, group2 |
| 常見的 ACL 讀取器 | defaultAcl.readers.users=user1, user2, google:user3 |
| 常見的 ACL 拒絕群組讀取權限 | defaultAcl.denied.groups=group3 |
| 常見的 Acl 拒絕讀取者 | defaultAcl.denied.users=user4, user5 |
| 整個網域存取權 | 如要指定每個已編入索引的記錄可供網域中的所有使用者公開存取，請為下列兩個選項設定值：
|
| 常見的定義 ACL | 如要為資料存放區的每個記錄指定一個 ACL，請設定下列所有參數值：
|
結構定義
Cloud Search 可為結構化和非結構化內容建立索引並提供服務。如要支援資料的結構化資料查詢，您必須為資料來源設定結構定義。
定義完成後，CSV 連接器就能參照定義的結構定義，建立索引要求。為了說明這個概念，我們以 CSV 檔案為例，其中包含電影相關資訊。
假設輸入的 CSV 檔案含有以下內容。
- movieId
- movieTitle
- 說明
- 年
- releaseDate
- 演員 (多個值以半形逗號 (,) 分隔)
- 類型 (多個值)
- 評分
根據上述資料結構，您可以為要從 CSV 檔案建立索引的資料來源定義結構定義。
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "actors",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"textPropertyOptions": {
"operatorOptions": {
"operatorName": "actor"
}
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
}
},
{
"name": "movieTitle",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"textPropertyOptions": {
"retrievalImportance": {
"importance": "HIGHEST"
},
"operatorOptions": {
"operatorName": "title"
}
}
},
{
"name": "genre",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"enumPropertyOptions": {
"operatorOptions": {
"operatorName": "genre"
},
"possibleValues": [
{
"stringValue": "Action"
},
{
"stringValue": "Documentary"
},
{
"stringValue": "Drama"
},
{
"stringValue": "Crime"
},
{
"stringValue": "Sci-fi"
}
]
}
},
{
"name": "userRating",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": true,
"integerPropertyOptions": {
"orderedRanking": "ASCENDING",
"maximumValue": "10",
"operatorOptions": {
"operatorName": "score",
"lessThanOperatorName": "scorebelow",
"greaterThanOperatorName": "scoreabove"
}
}
}
]
}
]
}
設定檔範例
以下範例設定檔顯示定義範例連接器行為的參數 key=value 組合。
# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json
# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle
# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE
#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true
如需各參數的詳細說明，請參閱設定參數參考資料。
執行 Cloud Search CSV 連接器
如要透過指令列執行連接器，請輸入下列指令：
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
根據預設，連接器記錄會顯示在標準輸出內容中。您可以指定 logging.properties 將記錄寫入檔案。