部署 CSV 連接器

本指南適用於 Google Cloud Search CSV (逗號分隔值) 連接器管理員，負責下載、設定、執行及監控連接器。

本指南包含下列重要工作的操作說明：

下載 Cloud Search CSV 連接器軟體。
為特定 CSV 資料來源設定連接器。
部署及執行連接器。

如要瞭解本文中的概念，請熟悉 Google Workspace、CSV 檔案和存取控管清單 (ACL)。

Cloud Search CSV 連接器總覽

Cloud Search CSV 連接器可處理任何半形逗號分隔值 (CSV) 文字檔案。CSV 檔案會儲存表格資料，每一行都是一筆資料記錄。

連接器會從 CSV 檔案中擷取資料列，並使用 Indexing API 將資料列編入 Cloud Search 索引。編入索引後，即可透過 Cloud Search 用戶端或 Query API 搜尋資料列。此外，連接器也支援 ACL，可控管使用者內容存取權。

您可以在 Linux 或 Windows 上安裝連接器。部署前，請確認您具備下列元件：

在執行連接器的電腦上安裝 Java JRE 1.8。
建立連線所需的 Google Workspace 資訊：
- Google Workspace 私密金鑰 (內含服務帳戶 ID)。
- Google Workspace 資料來源 ID。

通常網域的 Google Workspace 管理員會提供這些憑證。

部署步驟

請按照下列步驟部署 Cloud Search CSV 連接器：

安裝連接器軟體
指定連接器設定
設定 Cloud Search 資料來源的存取權
設定 CSV 檔案存取權
指定資料欄名稱、專屬鍵和日期時間資料欄
指定可點選的搜尋結果網址資料欄
指定中繼資料和資料欄格式
排定資料遍歷時間
指定 ACL 選項

1. 安裝 SDK

將 SDK 安裝到本機 Maven 存放區。

從 GitHub 複製 SDK 存放區。

$ git clone https://github.com/google-cloudsearch/connector-sdk.git
$ cd connector-sdk/csv

查看所選版本：
```
$ git checkout tags/v1-0.0.3
```
建構連接器：
```
$ mvn package
```

解壓縮並安裝連接器：

$ 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 檔案位置和定義。
不重複的 ID 欄。
遍歷和 ACL 選項。

如要建立設定檔，請按照下列步驟操作：

開啟文字編輯器，並將檔案命名為 connector-config.properties。
以 key=value 對的形式新增設定參數，每對參數各占一行。如需設定檔範例，請參閱「設定檔範例」。

將設定檔與連接器放在同一目錄中，方便追蹤。如要確保連接器能辨識檔案，請在指令列中指定檔案路徑。否則，連接器預設為本機目錄中的 connector-config.properties。請參閱「執行連接器」。

3. 設定 Cloud Search 資料來源的存取權

設定檔必須指定參數，才能存取 Cloud Search 資料來源。您需要資料來源 ID、服務帳戶 ID，以及服務帳戶私密金鑰檔案的路徑。

設定	參數
資料來源 ID	`api.sourceId=1234567890abcdef` 必填。Google Workspace 管理員設定的 Cloud Search 來源 ID。
服務帳戶私密金鑰的路徑	`api.serviceAccountPrivateKeyFile=./PrivateKey.json` 必填。連接器可存取的服務帳戶金鑰檔案。
識別資訊來源 ID	`api.identitySourceId=x0987654321` 如果使用外部使用者和群組，則為必要項目。Google Workspace 管理員設定的身分來源 ID。

4. 設定 CSV 檔案參數

找出檔案的路徑、格式和編碼。

設定	參數
CSV 檔案路徑	`csv.filePath=./movie_content.csv` 必填。要建立索引的檔案路徑。
檔案格式	`csv.format=DEFAULT` 檔案格式。可能的值來自 Apache Commons CSV CSVFormat 類別。格式值包括：`DEFAULT`、`EXCEL`、`INFORMIX_UNLOAD`、`INFORMIX_UNLOAD_CSV`、`MYSQL`、`RFC4180`、`ORACLE`、`POSTGRESQL_CSV`、`POSTGRESQL_TEXT` 和 `TDF`。如未指定，Cloud Search 會使用 `DEFAULT`。
檔案格式修飾符	`csv.format.withMethod=value` Cloud Search 處理檔案的方式有所變更。可能的方法來自 Apache Commons CSV CSVFormat 類別，包括採用單一字元、字串或布林值的方法。舉例來說，如要指定半形分號做為分隔符，請使用 `csv.format.withDelimiter=;`。如要忽略空白行，請使用 `csv.format.withIgnoreEmptyLines=true`。
檔案編碼類型	`csv.fileEncoding=UTF-8` 要使用的 Java 字元集。預設為平台字元集。

5. 指定要建立索引的資料欄和不重複鍵資料欄

在設定檔中提供資料欄資訊。

設定	參數
要建立索引的資料欄	`csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...` 要從 CSV 檔案建立索引的資料欄名稱。根據預設，系統會將 CSV 檔案的第一列做為標題。如果指定 `csv.csvColumns`，則優先採用該值。如要避免在設定 `csv.csvColumns` 時，將第一列編入索引做為資料，且第一列包含標題，請同時設定 `csv.skipHeaderRecord=true`。
不重複的索引鍵資料欄	`csv.uniqueKeyColumns=movieId` 用來產生專屬 ID 的資料欄。預設為記錄的雜湊碼。

6. 指定可點選搜尋結果網址的資料欄

為搜尋結果啟用可點選的網址。

設定	參數
搜尋結果網址格式	`url.format=https://mymoviesite.com/movies/{0}` 必填。用於建構檢視網址的格式。
網址參數	`url.columns=movieId` 必填。CSV 欄名稱，其值會用於產生記錄的檢視網址。
要逸出的搜尋結果網址參數	`url.columnsToEscape=movieId` (選用步驟) 系統會對這些 CSV 資料欄名稱的值進行網址逸出，以產生有效的檢視網址。

7. 指定中繼資料、資料欄格式和搜尋品質

您可以在設定檔中加入參數，指定下列項目：

中繼資料設定參數
資料欄格式
搜尋品質

中繼資料設定參數

這些參數會說明用於填入商品中繼資料的資料欄。

設定	參數
職稱	`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=type` `itemMetadata.objectType.defaultValue=movie` 連接器使用的物件類型，如結構定義中所定義。如果未指定這項屬性，連接器就不會為任何結構化資料建立索引。

日期時間格式

這個參數會指定其他日期時間格式，用於將字串值剖析為日期或日期時間欄位。

設定	參數
其他日期時間格式	`structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX` 以半形分號分隔的額外 `java.time.format.DateTimeFormatter` 模式清單。剖析中繼資料或結構定義中任何日期或日期時間欄位的字串值時，系統會使用這些模式。預設值為空白清單，但系統一律支援 RFC 3339 和 RFC 1123 格式。

欄格式

這些參數會指定如何剖析 CSV 檔案中的資料欄。

設定	參數
略過標頭	`csv.skipHeaderRecord=true` 忽略第一行。預設值為 false。
多值資料欄	`csv.multiValueColumns=genre,actors` 含有多個值的資料欄名稱。
多值資料欄的分隔符號	`csv.multiValue.genre=;` 多值資料欄的分隔符號。預設分隔符號為半形逗號。

搜尋品質

連接器會使用內容範本來格式化記錄。系統會優先處理「名稱」欄位。您可以為其他欄位指派優先順序 (高、中、低)。

設定	參數
內容標題	`contentTemplate.csv.title=movieTitle` 內容標題是搜尋品質最高的欄位。
內容欄位的高搜尋品質	`contentTemplate.csv.quality.high=actors` 內容欄位獲得高搜尋品質值。預設值為空字串。
內容欄位的搜尋品質不佳	`contentTemplate.csv.quality.low=genre` 內容欄位的搜尋品質值偏低。預設值為空字串。
內容欄位的搜尋品質一般	`contentTemplate.csv.quality.medium=description` 內容欄位獲得中等搜尋品質值。預設值為空字串。
未指定的內容欄位	`contentTemplate.csv.unmappedColumnsMode=IGNORE` 連接器如何處理未指定的內容欄位。有效值如下： APPEND：將未指定的內容欄位附加至範本 IGNORE：忽略未指定的內容欄位預設值為 APPEND。

8. 排定資料遍歷作業

遍歷是指探索內容的過程。連接器會遍歷 CSV 資料列，並使用 Indexing API 為這些資料列建立索引。CSV 連接器只會執行完整遍歷。

設定	參數
周遊間隔	`schedule.traversalIntervalSecs=7200` 完整遍歷之間的間隔時間，單位為秒。預設值為 86400 (一天)。
啟動時遍歷	`schedule.performTraversalOnStart=false` 連接器會在啟動時執行遍歷，而不是等待第一個間隔到期。預設值為 `true.`

9. 指定 ACL 選項

連接器會使用 ACL 控制存取權。如果存放區提供 ACL，請上傳這些 ACL。否則請設定預設 ACL。將 defaultAcl.mode 設為 none 以外的值。

設定	參數
ACL 模式	`defaultAcl.mode=fallback` 必填。連接器僅支援備援模式。
預設 ACL 名稱	defaultAcl.name=`VIRTUAL_CONTAINER_FOR_CONNECTOR_1` (選用步驟) 覆寫連接器用於預設 ACL 的虛擬容器名稱。預設值為 `DEFAULT_ACL_VIRTUAL_CONTAINER`。如果多個連接器正在為相同資料來源中的內容建立索引，請考慮覆寫這項設定。
預設公開 ACL	`defaultAcl.public=true` 將整個存放區設為公版資源存取權。預設值為 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`
整個網域的存取權	如要指定網域中的每位使用者都能公開存取所有已建立索引的記錄，請為下列兩個選項設定值： `defaultAcl.mode=fallback` `defaultAcl.public=true`
常見的已定義 ACL	如要為每筆記錄定義通用 ACL，請設定下列參數： `defaultAcl.mode=fallback` `defaultAcl.public=false` `defaultAcl.readers.groups=google:group1, group2` `defaultAcl.readers.users=user1, user2, google:user3` `defaultAcl.denied.groups=group3` `defaultAcl.denied.users=user4, user5` 除非加上「`google:`」前置字串，否則系統會假設使用者和群組是由本機網域定義。預設使用者或群組為空字串。只有在 `defaultAcl.public` 為 `false` 時，才提供使用者和群組選項。如要新增多個群組和使用者，請使用以半形逗號分隔的清單。如果 `defaultAcl.mode` 為 `none`，記錄就無法搜尋，除非有個別 ACL。

結構定義

如要支援結構化資料查詢，請為資料來源設定結構定義。

舉例來說，假設 CSV 檔案包含下列電影資訊：

movieId
movieTitle
說明
年
releaseDate
演員 (多個值以半形逗號 (,) 分隔)
類型 (多個值)
評分

根據這個結構，您可以為資料來源定義下列架構：

{
  "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

執行連接器

如要透過指令列執行連接器，請按照下列步驟操作：

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

根據預設，連接器記錄會顯示在標準輸出內容中。您可以指定 logging.properties，將記錄檔寫入檔案。