部署 CSV 連接器

本指南適用於 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 連接器也支援使用存取控制清單，控管使用者對搜尋結果中內容的存取權。

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 連接器，請按照下列步驟操作：

1. 安裝 Google Cloud Search CSV 連接器軟體
2. 指定 CSV 連接器設定
3. 設定 Google Cloud Search 資料來源的存取權
4. 設定 CSV 檔案存取權
5. 指定要建立索引的資料欄名稱、不重複的鍵資料欄和日期時間資料欄
6. 指定要在可點選的搜尋結果網址中使用的資料欄
7. 指定中繼資料資訊、資料欄格式
8. 排定資料遍歷時間
9. 指定存取控制清單 (ACL) 選項

1. 安裝 SDK

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

1. 從 GitHub 複製 SDK 存放區。

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

2. 查看所需版本的 SDK：

   $ git checkout tags/v1-0.0.3

3. 建構連接器：

   $ mvn package

4. 將連結器 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 檔案並為相關內容建立索引，請先建立設定檔。

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

1. 開啟所選文字編輯器，並命名設定檔。
   如以下各節所述，將 key=value 組合新增至檔案內容。
2. 儲存並命名設定檔。
   Google 建議您將設定檔命名為 connector-config.properties，這樣執行連接器時就不需要額外的命令列參數。

由於您可以在指令列指定設定檔路徑，因此不需要標準檔案位置。不過，請將設定檔放在與連接器相同的目錄中，方便追蹤及執行連接器。

如要確保連接器能辨識設定檔，請在指令列中指定設定檔路徑。否則，連接器會使用本機目錄中的 connector-config.properties 做為預設檔案名稱。如要瞭解如何在指令列上指定設定路徑，請參閱「執行 Cloud Search CSV 連接器」。

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

每個設定檔都必須先指定存取 Cloud Search 資料來源所需的參數，如下表所示。一般來說，您需要資料來源 ID、服務帳戶 ID，以及服務帳戶私密金鑰檔案的路徑，才能設定連接器對 Cloud Search 的存取權。如要瞭解設定資料來源的步驟，請參閱「管理第三方資料來源」。

4. 設定 CSV 檔案參數

連接器必須先找出 CSV 檔案的路徑，才能遍歷檔案並擷取資料以供建立索引。您也可以指定檔案格式和檔案編碼類型。 在設定檔中新增下列參數，指定 CSV 檔案屬性。

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

如要讓連結器存取及建立 CSV 檔案的索引，您必須在設定檔中提供欄定義的相關資訊。如果設定檔未包含指定要建立索引的資料欄名稱和唯一鍵資料欄的參數，系統會使用預設值。

6. 指定要在可點選的搜尋結果網址中使用的資料欄

使用者透過 Google Cloud Search 搜尋時，系統會顯示結果網頁，其中包含每個結果的可點選網址。如要啟用這項功能，請務必將下表所示的參數新增至設定檔。

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

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

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

中繼資料設定參數

「中繼資料設定參數」一節說明用於填入項目中繼資料的 CSV 欄。如果設定檔未包含這些參數，系統會使用預設值。下表列出這些參數。

日期時間格式

日期時間格式會指定中繼資料屬性中預期的格式。如果設定檔未包含這項參數，系統會使用預設值。下表顯示這個參數。

欄格式

資料欄格式會指定應納入可搜尋內容的資料欄資訊。如果設定檔未包含這些參數，系統會使用預設值。下表列出這些參數。

搜尋品質

Cloud Search CSV 連接器可自動為資料欄位設定 HTML 格式。連接器會在執行開始時定義資料欄位，然後使用內容範本格式化每筆資料記錄，再上傳至 Cloud Search。

內容範本會定義每個欄位值在搜尋時的重要性。標題為必要欄位，且優先順序最高。你也可以為所有其他內容欄位指定搜尋品質重要程度：高、中或低。如果特定類別未定義任何內容欄位，系統會預設為低優先順序。下表列出這些參數。

8. 排定資料遍歷作業

遍歷是連接器從資料來源 (在本例中為 CSV 檔案) 探索內容的程序。CSV 連接器執行時，會遍歷 CSV 檔案的資料列，並透過 Indexing API 將每個資料列編入 Cloud Search 索引。

完整遍歷會為檔案中的所有資料欄建立索引。增量遍歷只會為上次遍歷後新增或修改的資料欄建立索引。CSV 連接器只會執行完整遍歷。不會執行增量遍歷。

排程參數會決定連接器在遍歷之間等待的頻率。如果設定檔未包含排程參數，系統會使用預設值。下表列出這些參數。

9. 指定存取控管清單 (ACL) 選項

Google Cloud Search CSV 連接器支援透過存取控制清單 (ACL) 設定權限，控管搜尋結果中 CSV 檔案內容的存取權。您可以使用多種 ACL 選項，保護使用者對已建立索引記錄的存取權。

如果存放區的每個文件都含有個別 ACL 資訊，請上傳所有 ACL 資訊，以便控管 Cloud Search 中的文件存取權。如果存放區提供的 ACL 資訊不完整或沒有 ACL 資訊，您可以在下列參數中提供預設 ACL 資訊，SDK 會將這些資訊提供給連接器。

連接器會啟用設定檔中的預設 ACL。如要啟用預設 ACL，請將 defaultAcl.mode 設為 none 以外的任何模式，並使用 defaultAcl.* 進行設定。

結構定義

Cloud Search 可建立結構化和非結構化內容的索引，並提供這些內容。如要支援資料的結構化資料查詢，您必須為資料來源設定結構定義。

定義完成後，CSV 連接器即可參照定義的結構建立索引要求。舉例來說，假設您有一個包含電影資訊的 CSV 檔案。

假設輸入的 CSV 檔案包含下列內容。

1. movieId
2. movieTitle
3. 說明
4. 年
5. releaseDate
6. 演員 (以半形逗號 (,) 分隔多個值)
7. 類型 (多個值)
8. 評分

根據上述資料結構，您可以為資料來源定義結構定義，以便從 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，將記錄檔寫入檔案。