部署連接器

本頁的 Cloud Search 教學課程說明如何設定資料來源和內容連接器，以便為資料建立索引。如要從本教學課程的開頭開始學習，請參閱 Cloud Search 入門教學課程

建構連接器

將工作目錄變更為 cloud-search-samples/end-to-end/connector 目錄，然後執行下列指令：

mvn package -DskipTests

這個指令會下載建構內容連接器所需的依附元件，並編譯程式碼。

建立服務帳戶憑證

連接器需要服務帳戶憑證才能呼叫 Cloud Search API。如要建立憑證，請按照下列步驟操作：

1. 返回 Google Cloud 控制台。
2. 在左側導覽面板中，按一下「憑證」。畫面上會顯示「憑證」頁面。
3. 按一下「+ 建立憑證」下拉式清單，然後選取「服務帳戶」。畫面上會顯示「建立服務帳戶」頁面。
4. 在「Service account name」(服務帳戶名稱) 欄位中輸入「tutorial」。
5. 請記下服務帳戶 ID 值 (服務帳戶名稱右側)。這個值稍後會用到。
6. 按一下「建立」。畫面上會顯示「Service account permissions (optional)」(服務帳戶權限 (選用)) 對話方塊。
7. 按一下「繼續」。系統隨即顯示「Grant users access to this service account (optional)」(將這個服務帳戶的存取權限授予使用者 (選用)）對話方塊。
8. 點按「完成」。畫面會顯示「憑證」畫面。
9. 在「服務帳戶」下方，按一下服務帳戶的電子郵件地址。「服務帳戶詳細資料」頁面隨即顯示。
10. 在「金鑰」下方，按一下「新增金鑰」下拉式選單，然後選取「建立新的金鑰」。畫面上會顯示「Create private key」對話方塊。
11. 點選「建立」。
12. (選用) 如果畫面上出現「是否允許在 console.cloud.google.com 上進行下載？」對話方塊，請按一下「允許」。
13. 私密金鑰檔案會儲存到您的電腦中。請記下下載檔案的位置。這個檔案可用於設定內容連接器，讓連接器在呼叫 Google Cloud Search API 時進行驗證。

初始化第三方支援

您必須先初始化 Google Cloud Search 的第三方支援，才能呼叫任何其他 Cloud Search API。

注意： 如果您已成功執行 Cloud Search 教學課程，就已為 Cloud Search 初始化第三方支援，因此可以略過這個步驟。

如要初始化 Cloud Search 的第三方支援功能，請按照下列步驟操作：

1. Cloud Search 平台專案包含服務帳戶憑證。不過，為了初始化第三方支援，您必須建立網頁應用程式憑證。如需建立網頁應用程式憑證的操作說明，請參閱「建立憑證」。完成這個步驟後，您應該會取得用戶端 ID 和用戶端密碼檔案。

2. 使用 Google 的 OAuth 2 Playground 取得存取權杖：

   1. 按一下「設定」，然後勾選「使用您自己的驗證憑證」。
   2. 輸入步驟 1 中的用戶端 ID 和用戶端密碼。
   3. 按一下「關閉」。
   4. 在「範圍」欄位中輸入 https://www.googleapis.com/auth/cloud_search.settings，然後按一下「授權」。OAuth 2 Playground 會傳回授權碼。
   5. 按一下「Exchange authorization code for tokens」。系統會傳回權杖。

3. 如要初始化 Cloud Search 的第三方支援，請使用下列 curl 指令。請務必將 [YOUR_ACCESS_TOKEN] 替換為在步驟 2 中取得的權杖。

   curl --request POST \
   'https://cloudsearch.googleapis.com/v1:initializeCustomer' \
     --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{}' \
     --compressed
   

   如果成功，回應主體會包含 operation 的例項。例如：

   {
   name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY"
   }
   

   如果無法成功，請與 Cloud Search 支援團隊聯絡。

4. 使用 operations.get 驗證第三方支援是否已完成初始化：

   curl \
   'https://cloudsearch.googleapis.com/v1/operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY?key=
   [YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --compressed
   

   第三方初始化完成後，其中的欄位 done 會設為 true。例如：

   {
   name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY"
   done: true
   }
   

建立資料來源

接著，請在管理控制台中建立資料來源。資料來源會提供命名空間，以便使用連接器為內容建立索引。

注意： 這些步驟必須由網域管理員執行。

1. 開啟 Google 管理控制台。
2. 按一下「應用程式」圖示。畫面上會顯示「應用程式管理」頁面。
3. 按一下「Google Workspace」。畫面上會顯示「Google Workspace 應用程式管理」頁面。
4. 向下捲動並點選「Cloud Search」。系統會顯示「Google Workspace 設定」頁面。
5. 按一下「第三方資料來源」。「資料來源」頁面隨即顯示。
6. 按一下圓形黃色 + 圖示，畫面上會顯示「新增資料來源」對話方塊。
7. 在「顯示名稱」欄位中，輸入「tutorial」。
8. 在「Service account email addresses」欄位中，輸入您在上一節建立的服務帳戶電子郵件地址。如果您不知道服務帳戶的電子郵件地址，請在「服務帳戶」頁面中查詢該值。
9. 按一下「新增」。系統會顯示「已成功建立資料來源」對話方塊。
10. 按一下「OK」。記下新建立的資料來源的來源 ID。來源 ID 可用於設定內容連接器。

為 GitHub API 產生個人存取權杖

連接器需要經過驗證的 GitHub API 存取權，才能取得足夠的配額。為了簡化操作，連接器會使用個人存取權杖，而非 OAuth。個人權杖可讓使用者以有限的權限進行驗證，類似於 OAuth。

1. 登入 GitHub。
2. 按一下右上角的個人資料相片。系統會顯示下拉式選單。
3. 按一下 [設定]。
4. 按一下「開發人員設定」。
5. 按一下「個人存取權杖」。
6. 按一下「產生個人存取權杖」。
7. 在「附註」欄位中輸入「Cloud Search 教學課程」。
8. 檢查 public_repo 範圍。
9. 按一下「產生權杖」。
10. 記下系統產生的權杖。連接器會使用這個值呼叫 GitHub API，並提供 API 配額來執行索引。

設定連接器

建立憑證和資料來源後，請更新連接器設定，加入下列值：

1. 在指令列中，將目錄變更為 cloud-search-samples/end-to-end/connector/。
2. 使用文字編輯器開啟 sample-config.properties 檔案。
3. 將 api.serviceAccountPrivateKeyFile 參數設為先前下載的服務憑證檔案路徑。
4. 將 api.sourceId 參數設為先前建立的資料來源 ID。
5. 將 github.user 參數設為您的 GitHub 使用者名稱。
6. 將 github.token 參數設為先前建立的存取權杖。
7. 儲存檔案。

更新結構定義

連接器會為結構化和非結構化內容建立索引。在為資料建立索引之前，您必須先更新資料來源的結構定義。執行下列指令來更新結構定義：

mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.SchemaTool \
    -Dexec.args="-Dconfig=sample-config.properties"

執行連接器

如要執行連接器並開始建立索引，請執行下列指令：

mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.GithubConnector \
    -Dexec.args="-Dconfig=sample-config.properties"

連接器的預設設定是為 googleworkspace 機構中的單一存放區建立索引。索引儲存庫大約需要 1 分鐘。初始索引完成後，連接器會持續輪詢存放區的變更，並將這些變更反映在 Cloud Search 索引中。

審查程式碼

接下來幾節將說明連接器的建構方式。

啟動應用程式

連接器的進入點為 GithubConnector 類別。main 方法會將 SDK 的 IndexingApplication 例項化並啟動。

GithubConnector.java

前往 GitHub 查看

/**
 * Main entry point for the connector. Creates and starts an indexing
 * application using the {@code ListingConnector} template and the sample's
 * custom {@code Repository} implementation.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new GithubRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args)
      .build();
  application.start();
}

SDK 提供的 ListingConnector 實作了一種遍歷策略，可利用 Cloud Search 佇列追蹤索引中項目的狀態。它會將權限委派給由範例連接器實作的 GithubRepository，以便存取 GitHub 中的內容。

遍歷 GitHub 存放區

在完整遍歷期間，系統會呼叫 getIds() 方法，將可能需要建立索引的項目推送至佇列。

連接器可為多個存放區或機構建立索引。為盡量減少失敗的影響，系統會一次檢查一個 GitHub 存放區。系統會傳回檢查點，其中包含檢索結果，其中包含在後續對 getIds() 的呼叫中要索引的存放區清單。如果發生錯誤，系統會從目前的存放區繼續建立索引，而不是從頭開始。

GithubRepository.java

前往 GitHub 查看

/**
 * Gets all of the existing item IDs from the data repository. While
 * multiple repositories are supported, only one repository is traversed
 * per call. The remaining repositories are saved in the checkpoint
 * are traversed on subsequent calls. This minimizes the amount of
 * data that needs to be reindex in the event of an error.
 *
 * <p>This method is called by {@link ListingConnector#traverse()} during
 * <em>full traversals</em>. Every document ID and metadata hash value in
 * the <em>repository</em> is pushed to the Cloud Search queue. Each pushed
 * document is later polled and processed in the {@link #getDoc(Item)} method.
 * <p>
 * The metadata hash values are pushed to aid document change detection. The
 * queue sets the document status depending on the hash comparison. If the
 * pushed ID doesn't yet exist in Cloud Search, the document's status is
 * set to <em>new</em>. If the ID exists but has a mismatched hash value,
 * its status is set to <em>modified</em>. If the ID exists and matches
 * the hash value, its status is unchanged.
 *
 * <p>In every case, the pushed content hash value is only used for
 * comparison. The hash value is only set in the queue during an
 * update (see {@link #getDoc(Item)}).
 *
 * @param checkpoint value defined and maintained by this connector
 * @return this is typically a {@link PushItems} instance
 */
@Override
public CheckpointCloseableIterable<ApiOperation> getIds(byte[] checkpoint)
    throws RepositoryException {
  List<String> repositories;
  // Decode the checkpoint if present to get the list of remaining
  // repositories to index.
  if (checkpoint != null) {
    try {
      FullTraversalCheckpoint decodedCheckpoint = FullTraversalCheckpoint
          .fromBytes(checkpoint);
      repositories = decodedCheckpoint.getRemainingRepositories();
    } catch (IOException e) {
      throw new RepositoryException.Builder()
          .setErrorMessage("Unable to deserialize checkpoint")
          .setCause(e)
          .build();
    }
  } else {
    // No previous checkpoint, scan for repositories to index
    // based on the connector configuration.
    try {
      repositories = scanRepositories();
    } catch (IOException e) {
      throw toRepositoryError(e, Optional.of("Unable to scan repositories"));
    }
  }

  if (repositories.isEmpty()) {
    // Nothing left to index. Reset the checkpoint to null so the
    // next full traversal starts from the beginning
    Collection<ApiOperation> empty = Collections.emptyList();
    return new CheckpointCloseableIterableImpl.Builder<>(empty)
        .setCheckpoint((byte[]) null)
        .setHasMore(false)
        .build();
  }

  // Still have more repositories to index. Pop the next repository to
  // index off the list. The remaining repositories make up the next
  // checkpoint.
  String repositoryToIndex = repositories.get(0);
  repositories = repositories.subList(1, repositories.size());

  try {
    log.info(() -> String.format("Traversing repository %s", repositoryToIndex));
    Collection<ApiOperation> items = collectRepositoryItems(repositoryToIndex);
    FullTraversalCheckpoint newCheckpoint = new FullTraversalCheckpoint(repositories);
    return new CheckpointCloseableIterableImpl.Builder<>(items)
        .setHasMore(true)
        .setCheckpoint(newCheckpoint.toBytes())
        .build();
  } catch (IOException e) {
    String errorMessage = String.format("Unable to traverse repo: %s",
        repositoryToIndex);
    throw toRepositoryError(e, Optional.of(errorMessage));
  }
}

方法 collectRepositoryItems() 會處理單一 GitHub 存放區的遍歷作業。這個方法會傳回 ApiOperations 集合，代表要推送至佇列的項目。項目會以資源名稱和雜湊值推送，代表項目目前的狀態。

這個雜湊值會用於後續的 GitHub 存放區檢索作業。這個值可提供輕量檢查，用於判斷內容是否已變更，而無須上傳額外內容。連接器會盲目地將所有項目排入佇列。如果項目是新的，或雜湊值已變更，則可在佇列中進行輪詢。否則系統會將該項目視為未經修改。

GithubRepository.java

前往 GitHub 查看

/**
 * Fetch IDs to  push in to the queue for all items in the repository.
 * Currently captures issues & content in the master branch.
 *
 * @param name Name of repository to index
 * @return Items to push into the queue for later indexing
 * @throws IOException if error reading issues
 */
private Collection<ApiOperation> collectRepositoryItems(String name)
    throws IOException {
  List<ApiOperation> operations = new ArrayList<>();
  GHRepository repo = github.getRepository(name);

  // Add the repository as an item to be indexed
  String metadataHash = repo.getUpdatedAt().toString();
  String resourceName = repo.getHtmlUrl().getPath();
  PushItem repositoryPushItem = new PushItem()
      .setMetadataHash(metadataHash);
  PushItems items = new PushItems.Builder()
      .addPushItem(resourceName, repositoryPushItem)
      .build();

  operations.add(items);
  // Add issues/pull requests & files
  operations.add(collectIssues(repo));
  operations.add(collectContent(repo));
  return operations;
}

處理佇列

完整檢索作業完成後，連接器就會開始輪詢佇列，找出需要建立索引的項目。系統會為從佇列中拉出的每個項目呼叫 getDoc() 方法。這個方法會讀取 GitHub 中的項目，並將其轉換為適當的索引表示法。

由於連接器會針對隨時可能變更的即時資料執行，getDoc() 也會驗證佇列中的項目是否仍有效，並從索引中刪除不再存在的任何項目。

GithubRepository.java

前往 GitHub 查看

/**
 * Gets a single data repository item and indexes it if required.
 *
 * <p>This method is called by the {@link ListingConnector} during a poll
 * of the Cloud Search queue. Each queued item is processed
 * individually depending on its state in the data repository.
 *
 * @param item the data repository item to retrieve
 * @return the item's state determines which type of
 * {@link ApiOperation} is returned:
 * {@link RepositoryDoc}, {@link DeleteItem}, or {@link PushItem}
 */
@Override
public ApiOperation getDoc(Item item) throws RepositoryException {
  log.info(() -> String.format("Processing item: %s ", item.getName()));
  Object githubObject;
  try {
    // Retrieve the item from GitHub
    githubObject = getGithubObject(item.getName());
    if (githubObject instanceof GHRepository) {
      return indexItem((GHRepository) githubObject, item);
    } else if (githubObject instanceof GHPullRequest) {
      return indexItem((GHPullRequest) githubObject, item);
    } else if (githubObject instanceof GHIssue) {
      return indexItem((GHIssue) githubObject, item);
    } else if (githubObject instanceof GHContent) {
      return indexItem((GHContent) githubObject, item);
    } else {
      String errorMessage = String.format("Unexpected item received: %s",
          item.getName());
      throw new RepositoryException.Builder()
          .setErrorMessage(errorMessage)
          .setErrorType(RepositoryException.ErrorType.UNKNOWN)
          .build();
    }
  } catch (FileNotFoundException e) {
    log.info(() -> String.format("Deleting item: %s ", item.getName()));
    return ApiOperations.deleteItem(item.getName());
  } catch (IOException e) {
    String errorMessage = String.format("Unable to retrieve item: %s",
        item.getName());
    throw toRepositoryError(e, Optional.of(errorMessage));
  }
}

針對連接器索引的每個 GitHub 物件，對應的 indexItem() 方法會處理建構 Cloud Search 的項目表示法。舉例來說，如要建構內容項目的表示法：

GithubRepository.java

前往 GitHub 查看

/**
 * Build the ApiOperation to index a content item (file).
 *
 * @param content      Content item to index
 * @param previousItem Previous item state in the index
 * @return ApiOperation (RepositoryDoc if indexing,  PushItem if not modified)
 * @throws IOException if unable to create operation
 */
private ApiOperation indexItem(GHContent content, Item previousItem)
    throws IOException {
  String metadataHash = content.getSha();

  // If previously indexed and unchanged, just requeue as unmodified
  if (canSkipIndexing(previousItem, metadataHash)) {
    return notModified(previousItem.getName());
  }

  String resourceName = new URL(content.getHtmlUrl()).getPath();
  FieldOrValue<String> title = FieldOrValue.withValue(content.getName());
  FieldOrValue<String> url = FieldOrValue.withValue(content.getHtmlUrl());

  String containerName = content.getOwner().getHtmlUrl().getPath();
  String programmingLanguage = FileExtensions.getLanguageForFile(content.getName());

  // Structured data based on the schema
  Multimap<String, Object> structuredData = ArrayListMultimap.create();
  structuredData.put("organization", content.getOwner().getOwnerName());
  structuredData.put("repository", content.getOwner().getName());
  structuredData.put("path", content.getPath());
  structuredData.put("language", programmingLanguage);

  Item item = IndexingItemBuilder.fromConfiguration(resourceName)
      .setTitle(title)
      .setContainerName(containerName)
      .setSourceRepositoryUrl(url)
      .setItemType(IndexingItemBuilder.ItemType.CONTAINER_ITEM)
      .setObjectType("file")
      .setValues(structuredData)
      .setVersion(Longs.toByteArray(System.currentTimeMillis()))
      .setHash(content.getSha())
      .build();

  // Index the file content too
  String mimeType = FileTypeMap.getDefaultFileTypeMap()
      .getContentType(content.getName());
  AbstractInputStreamContent fileContent = new InputStreamContent(
      mimeType, content.read())
      .setLength(content.getSize())
      .setCloseInputStream(true);
  return new RepositoryDoc.Builder()
      .setItem(item)
      .setContent(fileContent, IndexingService.ContentFormat.RAW)
      .setRequestMode(IndexingService.RequestMode.SYNCHRONOUS)
      .build();
}

接著，部署搜尋介面。

返回 繼續