本指南適用於 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，將這些網頁編入索引。一次 已成功建立索引，也可以從 CSV 檔案搜尋個別資料列 Cloud Search 的用戶端或 Cloud Search Query API。CSV 連接器 支援控制使用者存取搜尋結果中的內容 ACL。
您可以在 Linux 或 Windows 上安裝 Google Cloud Search CSV 連接器。之前 部署 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
將 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 的存取權設定資料來源所需的步驟 這些 Pod 會在 管理第三方資料來源
| 設定 | 參數 |
| 資料來源 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
連接器所使用的物件類型，如 schema。 如未指定這項屬性，連接器就不會為任何結構化資料建立索引。 |
日期時間格式
日期時間格式會指定中繼資料屬性中預期的格式。如果設定檔不含這個參數，則會使用預設值。下表顯示此參數。
| 設定 | 參數 |
| 其他日期時間格式 | 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」將每一列編入索引 也能使用 Google Cloud CLI 或 Compute Engine 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 |
| 常見的 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。