本指南適用於 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 的 Query API 搜尋 CSV 檔案中的個別資料列。CSV 連接器也支援使用 ACL 控管使用者對搜尋結果內容的存取權。
Google Cloud Search CSV 連接器可在 Linux 或 Windows 上安裝。在部署 Google Cloud Search CSV 連接器之前，請確認您具備下列必要元件：
- 在執行 Google Cloud Search CSV 連接器的電腦上安裝 Java JRE 1.8
需要 Google Workspace 資訊，才能建立 Google Cloud Search 和資料來源之間的關係：
- Google Workspace 私密金鑰 (包含服務帳戶 ID)
- Google Workspace 資料來源 ID
一般來說，網域的 Google Workspace 管理員可為您提供這些憑證。
部署步驟
如要部署 Google Cloud Search CSV 連接器，請按照下列步驟操作：
- 安裝 Google Cloud Search CSV 連接器軟體
- 指定 CSV 連接器設定
- 設定 Google Cloud Search 資料來源的存取權
- 設定 CSV 檔案存取權
- 指定要索引的資料欄名稱、不重複的索引鍵資料欄及日期時間資料欄
- 指定要用於可點選搜尋結果網址的資料欄
- 指定中繼資料資訊、資料欄格式
- 排定資料週遊作業
- 指定存取控制清單 (ACL) 選項
1. 安裝 SDK
在本機 Maven 存放區中安裝 SDK。
從 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 的資料欄
- 週遊選項
- 限制資料存取權的 ACL 選項
如要讓連接器正確存取 CSV 檔案，並為相關內容建立索引，您必須先建立其設定檔。
如何建立設定檔：
- 開啟您選擇的文字編輯器，並為設定檔命名。
按照以下各節所述，在檔案內容中加入 key=值組合。 - 儲存設定檔並為其命名。
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
選用設定。CSV 欄名稱；系統會將其值逸出，以產生有效的檢視網址。 |
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 檔案的資料列，並透過 Indexing API 為各個資料列建立索引。
「完整週遊」會為檔案中的所有資料欄建立索引。「增量週遊」功能只會為在上次週遊後新增或修改的資料欄建立索引。CSV 連接器只會執行完整週遊，不會執行漸進式週遊。
排程參數會決定連接器在周遊之間等待的頻率。如果設定檔不含排程參數，系統會使用預設值。下表列出這些參數。
| 設定 | 參數 |
| 每隔一段時間才完整週遊 | schedule.traversalIntervalSecs=7200
連接器會在指定的時間間隔後執行完整週遊。指定週遊之間的間隔時間 (以秒為單位)。預設值為 86400 (一天的秒數)。 |
| 連接器啟動時完整週遊 | schedule.performTraversalOnStart=false
連接器會在連接器啟動時執行完整週遊，而不是等待第一個間隔到期。預設值為 true。 |
9. 指定存取控制清單 (ACL) 選項
Google Cloud Search CSV 連接器支援透過 ACL 取得權限，以控制搜尋結果中 CSV 檔案內容的存取權。目前有多種 ACL 選項可讓您保護使用者存取已建立索引的記錄。
如果您的存放區含有與每份文件相關聯的個別 ACL 資訊，請上傳所有 ACL 資訊，以在 Cloud Search 中控管文件存取權。如果您的存放區提供部分或不含 ACL 資訊，您可以在下列參數中提供預設的 ACL 資訊，SDK 會將該資訊提供給連接器。
連接器必須使用設定檔啟用的預設 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 |
| Common ACL 拒絕群組讀取器 | defaultAcl.denied.groups=group3 |
| 常見的 Acl 拒絕讀取者 | defaultAcl.denied.users=user4, user5 |
| 整個網域存取權 | 如要指定網域中的所有使用者皆可公開存取每個已建立索引的記錄，請將下列兩個選項的值設為：
|
| 常見的定義的 ACL | 如要為資料存放區的每筆記錄指定一個 ACL，請設定下列所有參數值：
|
結構定義定義
Cloud Search 可讓您建立索引及提供結構化和非結構化的內容。為支援資料的結構化資料查詢，您必須為資料來源設定結構定義。
定義完成後，CSV 連接器就可以參照定義的結構定義，藉此建構索引要求。 如要提供說明範例，我們來看一個包含電影相關資訊的 CSV 檔案。
假設輸入的 CSV 檔案具有下列內容。
- movieId
- movieTitle
- description
- 年
- 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 來記錄檔案。