本指南適用於 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，控制使用者對搜尋結果中內容的存取權。
您可以在 Linux 或 Windows 上安裝 Google Cloud Search CSV 連接器。部署 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 的資料欄
- 週遊選項
- 用來限制資料存取權的 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 服務帳戶金鑰檔案，用於存取 Google Cloud Search CSV 連接器。 |
| 識別資訊來源 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
要根據值產生每筆記錄專屬 ID 的 CSV 資料欄，如未指定，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 資訊，您可以在下列參數中提供預設 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 |
| 常見的 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 來記錄檔案。