部署 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 連接器也支援使用 ACL 控管使用者對搜尋結果中內容的存取權。

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. 開啟您選擇的文字編輯器，並為設定檔命名。
   按照下列各節所述，在檔案內容中新增 鍵=值組合。
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 檔案的資料列，並透過索引 API 為每個資料列建立索引，以便在 Cloud Search 中使用。

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

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

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

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

如果您的存放區有與每份文件相關聯的個別 ACL 資訊，請上傳所有 ACL 資訊，以便在 Cloud Search 中控制文件存取權。如果您的存放區提供的 ACL 資訊不完整或沒有提供，您可以在 SDK 提供給連接器的下列參數中，提供預設的 ACL 資訊。

連接器會依賴在設定檔中啟用的預設 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 將記錄寫入檔案。