建立內容連接器

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

內容連接器是一種軟體程式，用來掃遍企業存放區中的資料並填入資料來源。Google 提供以下選項，供您開發內容連接器：

  • Content Connector SDK如果您在 Java 中編寫程式，則建議使用這個選項。Content Connector SDK 是 REST API 的包裝函式，可讓您快速建立連接器。如要使用 SDK 建立內容連接器，請參閱使用 Content Connector SDK 建立內容連接器一文。

  • 低階 REST API 或 API 程式庫。如果您不是使用 Java 編寫程式，或者程式碼集更適合符合 REST API 或程式庫，請使用這些選項。如要使用 REST API 建立內容連接器，請參閱使用 REST API 建立內容連接器一文。

一般的內容連接器會執行下列工作：

  1. 讀取及處理設定參數。
  2. 從第三方內容存放區提取可建立索引的資料不同的片段 (稱為「items」)。
  3. 將 ACL、中繼資料和內容資料合併成可建立索引的項目。
  4. 將項目編入索引至 Cloud Search 資料來源。
  5. (選用) 監聽來自第三方內容存放區的通知。變更通知會轉換成索引要求，讓 Cloud Search 資料來源與第三方存放區保持同步。只有在存放區支援變更偵測時，連接器才會執行這項工作。

使用 Content Connector SDK 建立內容連接器

以下各節說明如何使用 Content Connector SDK 建立內容連接器。

設定依附元件

您必須在建構檔案中加入特定依附元件，才能使用 SDK。請點選以下分頁標籤，查看建構環境的依附元件：

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

compile group: 'com.google.enterprise.cloudsearch',
        name: 'google-cloudsearch-indexing-connector-sdk',
        version: 'v1-0.0.3'

建立連接器設定

每個連接器都有一個設定檔，其中包含連接器使用的參數，例如存放區的 ID。參數的定義為 鍵/值組合，例如 api.sourceId=1234567890abcdef。

Google Cloud Search SDK 含有多個由所有連接器使用的 Google 提供的設定參數。您必須在設定檔中宣告下列 Google 提供的參數：

  • 如果是內容連接器，您必須宣告 api.sourceId 和 api.serviceAccountPrivateKeyFile，因為這些參數可識別存放區的位置，以及存取存放區所需的私密金鑰。
  • 針對身分識別連接器，您必須宣告 api.identitySourceId，因為這個參數可識別外部識別資訊來源的位置。如要同步處理使用者，您也必須將 api.customerId 宣告為企業 Google Workspace 帳戶的專屬 ID。

除非您想覆寫其他 Google 提供參數的預設值，否則不需要在設定檔中宣告這些參數。如要進一步瞭解 Google 提供的設定參數，例如如何產生特定 ID 和金鑰，請參閱 Google 提供的設定參數。

您也可以定義自己的存放區專屬參數，以供設定檔使用。

將設定檔傳送至連接器

設定系統屬性 config，將設定檔傳送至連接器。啟動連接器時，您可以使用 -D 引數來設定屬性。舉例來說，下列指令會使用 MyConfig.properties 設定檔啟動連接器：

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

如果缺少這個引數，SDK 會嘗試存取名為 connector-config.properties 的預設設定檔。

制定遍歷策略

內容連接器的主要功能是掃遍存放區並為其資料建立索引。您必須根據存放區中的資料大小和版面配置，執行週遊策略。您可以自行設計策略，或從 SDK 中導入的策略中挑選合適的策略：

完整拓展策略

完整的周遊策略會掃描整個存放區，並對每個項目進行盲索引。當您有一個小型存放區時，通常會採用此策略，而且每次載入索引時，都能夠進行完整穿越。

此週遊策略適用於具有靜態、非階層性資料的小型存放區。當存放區難以偵測或不支援變更偵測時，您也可以使用此遍歷策略。

列出週遊策略

清單週遊策略會掃描整個存放區 (包括所有子節點)，以判定每個項目的狀態。接著，連接器會使用第二個票證，只對上次建立索引之後新增或更新的項目建立索引。這項策略通常用於對現有索引執行漸進式更新 (不必在每次更新索引時執行遍歷)。

當存放區難以偵測或不支援變更變更、您擁有非階層資料，且您正在處理非常大型的資料集時，此遍歷策略將是適當選擇。

圖表週遊

圖表週遊策略會掃描整個父項節點，判定每個項目的狀態。接著，連接器會再次通過，而且只有根節點中的項目是新索引，或自上次索引之後經過更新。最後，連接器會傳送任何子 ID，然後為新節點或已更新的子節點中的項目建立索引。連接器會透過所有子節點遞迴，直到所有項目都解決為止。這類週遊通常用於階層式存放區，其中所有 ID 皆無從列出。

如果您有需要檢索的階層式資料 (例如一系列目錄或網頁)，就適合使用這種策略。

這些遍歷策略都是透過 SDK 中的範本連接器類別實作。雖然您可以實作自己的周遊策略，但這些範本可大幅加快連接器的開發速度。如要使用範本建立連接器，請參照與您的周遊策略對應的部分：

使用範本類別建立完整週遊連接器

本文件的這個章節指的是 FullTraversalSample 範例中的程式碼片段。

實作連接器的進入點

連接器的進入點是 main() 方法。此方法的主要工作是建立 Application 類別的例項，並叫用其 start() 方法來執行連接器。

呼叫 application.start() 之前，請使用 IndexingApplication.Builder 類別將 FullTraversalConnector 範本執行個體化。FullTraversalConnector 可接受 Repository 物件，其實作的方法將會執行。下列程式碼片段說明如何實作 main() 方法：

FullTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

在連接器的 main() 方法呼叫 Application.build 後，SDK 會在背景呼叫 initConfig() 方法。initConfig() 方法會執行下列工作：

  1. 呼叫 Configuation.isInitialized() 方法來確保 Configuration 尚未初始化。
  2. 使用 Google 提供的鍵/值組合初始化 Configuration 物件。每個鍵/值組合都會儲存在 Configuration 物件內的 ConfigValue 物件中。

導入 Repository 介面

Repository 物件的唯一用途是執行存放區項目的遍歷與索引。使用範本時，您只需要覆寫 Repository 介面內的某些方法，即可建立內容連接器。您要覆寫的方法，取決於您使用的範本和周遊策略。如果是 FullTraversalConnector，請覆寫以下方法：

  • init() 方法。如要執行任何資料存放區設定和初始化作業，請覆寫 init() 方法。

  • getAllDocs() 方法。若要掃遍資料存放區中的所有項目並為其建立索引，請覆寫 getAllDocs() 方法。系統會為每個排程週遊程序呼叫一次這個方法 (如設定所定義)。

  • (選用) getChanges() 方法。如果您的存放區支援變更偵測，請覆寫 getChanges() 方法。系統會為每個排程的累加式遍歷 (如設定所定義) 呼叫此方法，以擷取修改的項目並建立索引。

  • (選用) close() 方法。如果您需要執行存放區清理作業，請覆寫 close() 方法。系統會在連接器關閉時呼叫此方法。

Repository 物件的每個方法都會傳回某些類型的 ApiOperation 物件。ApiOperation 物件會以單一 (或多個) IndexingService.indexItem() 呼叫的形式執行動作，以執行存放區的實際索引作業。

取得自訂設定參數

處理連接器設定時，您需要從 Configuration 物件取得任何自訂參數。這項工作通常會在 Repository 類別的 init() 方法中執行。

Configuration 類別有多種方法，可以從設定取得不同的資料類型。每個方法都會傳回 ConfigValue 物件。然後，請使用 ConfigValue 物件的 get() 方法擷取實際值。下列來自 FullTraversalSample 的程式碼片段說明如何從 Configuration 物件擷取單一自訂整數值：

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

如要取得和剖析包含多個值的參數，請使用 Configuration 類別的其中一個類型剖析器，將資料剖析為離散區塊。下列程式碼片段的教學課程連接器使用 getMultiValue 方法取得 GitHub 存放區名稱：

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

執行完整週遊

覆寫 getAllDocs() 以執行完整週遊，並為存放區建立索引。getAllDocs() 方法可接受查核點。如果程序中斷，系統會透過檢查點繼續為特定項目建立索引。為存放區中的每個項目，在 getAllDocs() 方法中執行下列步驟：

  1. 設定權限。
  2. 為您要建立索引的項目設定中繼資料。
  3. 將中繼資料和項目結合成一個可建立索引的 RepositoryDoc。
  4. 將每個可建立索引的項目封裝至 getAllDocs() 方法傳回的疊代器中。請注意，getAllDocs() 實際上會傳回 CheckpointCloseableIterable，這是 ApiOperation 物件的疊代，每個物件都代表在 RepositoryDoc 上執行的 API 要求，例如建立索引。

如果一組項目過大而無法在單一呼叫中處理，請加入一個檢查點並設定 hasMore(true)，表示還有更多項目可供建立索引。

設定項目的權限

您的存放區會使用存取控制清單 (ACL) 來識別有權存取項目的使用者或群組。ACL 是可存取該項目的群組或使用者的 ID 清單。

您必須複製存放區使用的 ACL，以確保只有具備項目存取權的使用者能在搜尋結果中看到該項目。在為項目建立索引時，您必須納入項目的 ACL，以便 Google Cloud Search 取得所需資訊，以提供正確的項目層級存取權。

Content Connector SDK 提供豐富的 ACL 類別和方法，可用來建立大部分存放區的 ACL 模型。您必須分析存放區中每個項目的 ACL，並為 Google Cloud Search 建立項目索引時建立對應的 ACL。如果您的存放區的 ACL 採用如 ACL 繼承等概念，那麼使用 ACL 進行模擬可能並不容易。如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL 一文。

注意：Cloud Search Indexing API 支援單一網域 ACL。不支援跨網域 ACL。使用 Acl.Builder 類別使用 ACL 設定每個項目的存取權。下列程式碼片段是從完整遍歷樣本中擷取，允許所有使用者或「主體」(getCustomerPrincipal()) 在執行搜尋時擁有所有項目的「讀取者」(.setReaders())。

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

您必須瞭解 ACL，才能正確為存放區建立 ACL 模型。例如，您可能會在檔案系統中使用某種某種繼承模型，為下層資料夾繼承上層資料夾的權限。建立 ACL 繼承需要 Google Cloud Search ACL 中涵蓋的額外資訊

設定項目的中繼資料

中繼資料會儲存在 Item 物件中。如要建立 Item，您需要項目專屬的不重複字串 ID、項目類型、ACL、網址和版本。下列程式碼片段示範如何使用 IndexingItemBuilder 輔助類別建立 Item。

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

建立可建立索引的項目

設定項目的中繼資料後，您可以使用 RepositoryDoc.Builder 類別建立實際的可建立索引項目。以下範例說明如何建立單一可建立索引的項目。

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc 是一種 ApiOperation 類型，可執行實際的 IndexingService.indexItem() 要求。

您也可以使用 RepositoryDoc.Builder 類別的 setRequestMode() 方法，將索引要求識別為 ASYNCHRONOUS 或 SYNCHRONOUS：

ASYNCHRONOUS
非同步模式可延長索引對服務的延遲時間，並長時間為索引要求提供總處理量。建議您為整個存放區進行初始索引 (補充作業) 的非同步模式。
SYNCHRONOUS
同步模式可縮短索引對服務的延遲時間，並提供有限的總處理量。建議您採用同步模式，以便對存放區的更新和變更建立索引。如未指定，要求模式會預設為 SYNCHRONOUS。

將每個可建立索引的項目封裝為 iterator

getAllDocs() 方法會傳回 RepositoryDoc 物件的 Iterator，特別是 CheckpointCloseableIterable。您可以使用 CheckpointClosableIterableImpl.Builder 類別建構及傳回疊代器。下列程式碼片段說明如何建構及傳回 iterator。

FullTraversalSample.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

SDK 會執行包含於 iterator 中的每個索引呼叫。

後續步驟

建議您採取下列步驟：

使用範本類別建立清單週遊連接器

Cloud Search Indexing Queue 可用於保存存放區中每個項目的 ID 和選用雜湊值。清單週遊器連接器會將項目 ID 推送到 Google Cloud Search 索引佇列中，且一次擷取一個 ID 以便建立索引。Google Cloud Search 會維護佇列並比較佇列內容以判斷項目狀態，例如該項目是否已從存放區中刪除。如要進一步瞭解 Cloud Search 索引佇列，請參閱 Cloud Search 索引佇列一文。

本文件的這個章節是指 ListTraversalSample 範例中的程式碼片段。

實作連接器的進入點

連接器的進入點是 main() 方法。此方法的主要工作是建立 Application 類別的例項，並叫用其 start() 方法來執行連接器。

呼叫 application.start() 之前，請使用 IndexingApplication.Builder 類別將 ListingConnector 範本執行個體化。ListingConnector 可接受您實作方法的 Repository 物件。下列程式碼片段說明如何執行個體化 ListingConnector 及其相關聯的 Repository：

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

在連接器的 main() 方法呼叫 Application.build 後，SDK 會在背景呼叫 initConfig() 方法。initConfig() 方法：

  1. 呼叫 Configuation.isInitialized() 方法來確保 Configuration 尚未初始化。
  2. 使用 Google 提供的鍵/值組合初始化 Configuration 物件。每個鍵/值組合都會儲存在 Configuration 物件內的 ConfigValue 物件中。

導入 Repository 介面

Repository 物件的唯一用途是執行存放區項目的遍歷與索引。使用範本時，您只需要覆寫 Repository 介面中的特定方法，即可建立內容連接器。視您採用的範本和遍歷策略而定，您覆寫的方法會有所不同。如果是 ListingConnector，請覆寫下列方法：

  • init() 方法。如要執行任何資料存放區設定和初始化作業，請覆寫 init() 方法。

  • getIds() 方法。如要擷取存放區中所有記錄的 ID 和雜湊值，請覆寫 getIds() 方法。

  • getDoc() 方法。如要從索引中新增、更新、修改或刪除項目，請覆寫 getDoc() 方法。

  • (選用) getChanges() 方法。如果您的存放區支援變更偵測，請覆寫 getChanges() 方法。系統會為每個排程的累加式遍歷 (如設定所定義) 呼叫此方法，以擷取修改的項目並建立索引。

  • (選用) close() 方法。如果您需要執行存放區清理作業，請覆寫 close() 方法。系統會在連接器關閉時呼叫此方法。

Repository 物件中的每個方法都會傳回某些類型的 ApiOperation 物件。ApiOperation 物件會以單一 (或多個) IndexingService.indexItem() 呼叫的形式執行動作，以執行存放區的實際索引作業。

取得自訂設定參數

處理連接器設定時，您需要從 Configuration 物件取得任何自訂參數。這項工作通常會在 Repository 類別的 init() 方法中執行。

Configuration 類別有多種方法，可以從設定取得不同的資料類型。每個方法都會傳回 ConfigValue 物件。然後，請使用 ConfigValue 物件的 get() 方法擷取實際值。下列來自 FullTraversalSample 的程式碼片段說明如何從 Configuration 物件擷取單一自訂整數值：

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

如要取得和剖析包含多個值的參數，請使用 Configuration 類別的其中一個類型剖析器，將資料剖析為離散區塊。下列程式碼片段的教學課程連接器使用 getMultiValue 方法取得 GitHub 存放區名稱：

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

執行清單週遊

覆寫 getIds() 方法，以擷取存放區中所有記錄的 ID 和雜湊值。getIds() 方法可接受查核點。如果檢查過程中斷，檢查點可用來繼續為特定項目建立索引。

接下來，請覆寫 getDoc() 方法來處理 Cloud Search Indexing Queue 中的每個項目。

推送項目編號和雜湊值

覆寫 getIds() 以從存放區擷取項目 ID 及其相關聯的內容雜湊值。接著，ID 和雜湊值組合會包裝在 Cloud Search Indexing Queue 的推送作業要求中，根層級或父項 ID 通常會先推送，接著是子項 ID，直到整個項目階層都處理完畢為止。

getIds() 方法接受一個檢查點，代表要建立索引的最後一個項目。如果處理程序中斷，您可以使用檢查點繼續為特定項目建立索引。針對存放區中的每個項目，在 getIds() 方法中執行下列步驟：

  • 從存放區取得各個項目 ID 與相關的雜湊值。
  • 將每個 ID 和雜湊值組合成一個 PushItems。
  • 將每個 PushItems 合併至 getIds() 方法傳回的疊代器。請注意，getIds() 實際上會傳回 CheckpointCloseableIterable，這是 ApiOperation 物件的疊代，每個物件都代表一個在 RepositoryDoc 上執行的 API 要求的，例如將項目推送至佇列。

下列程式碼片段說明如何取得每個項目 ID 和雜湊值，並將其插入 PushItems。「PushItems」是將項目推送至 Cloud Search 索引佇列的 ApiOperation 要求。

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

下列程式碼片段說明如何使用 PushItems.Builder 類別，將 ID 和雜湊值封裝為單一推送 ApiOperation。

ListTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

項目會推送至 Cloud Search Indexing Queue 以進一步處理。

擷取並處理每個項目

覆寫 getDoc() 來處理 Cloud Search Indexing Queue 中的每個項目。項目可以是新的、修改、未變更或已不在來源存放區中。擷取每個新項目或修改項目，並為其建立索引。將特定項目從來源存放區中移除。

getDoc() 方法可接受 Google Cloud Search 索引佇列中的項目。針對佇列中的每個項目，在 getDoc() 方法中執行下列步驟：

  1. 檢查該項目是否存在於存放區中的 Cloud Search Indexing 佇列。如果不是，請將其從索引中刪除。

  2. 輪詢項目狀態的索引。如果項目維持不變 (ACCEPTED)，則無須採取任何行動。

  3. 索引已變更或新增項目：

    1. 設定權限。
    2. 為您要建立索引的項目設定中繼資料。
    3. 將中繼資料和項目結合成一個可建立索引的 RepositoryDoc。
    4. 傳回 RepositoryDoc。

注意：ListingConnector 範本不支援在 getDoc() 方法上傳回 null。傳回 null 的結果會產生 NullPointerException.

處理已刪除的項目

下列程式碼片段說明如何判斷存放區中是否有某個項目，如果沒有的話，請將其刪除。

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

請注意，documents 是代表存放區的資料結構。如果在 documents 中找不到 documentID，傳回 APIOperations.deleteItem(resourceName) 即可從索引中刪除該項目。

處理未變更的項目

下列程式碼片段說明如何輪詢 Cloud Search 索引佇列中的項目狀態，並處理未變更的項目。

ListTraversalSample.java
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

如要判斷項目是否未經修改，請檢查項目的狀態，以及其他可能表示變更的中繼資料。在此範例中，中繼資料雜湊可用於判斷項目是否已變更。

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

設定項目的權限

您的存放區會使用存取控制清單 (ACL) 來識別有權存取項目的使用者或群組。ACL 是可存取該項目的群組或使用者的 ID 清單。

您必須複製存放區使用的 ACL，以確保只有具備項目存取權的使用者能在搜尋結果中看到該項目。在為項目建立索引時，您必須納入項目的 ACL，以便 Google Cloud Search 取得所需資訊，以提供正確的項目層級存取權。

Content Connector SDK 提供豐富的 ACL 類別和方法，可用來建立大部分存放區的 ACL 模型。您必須分析存放區中每個項目的 ACL，並為 Google Cloud Search 建立項目索引時建立對應的 ACL。如果您的存放區的 ACL 採用如 ACL 繼承等概念，那麼使用 ACL 進行模擬可能並不容易。如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL 一文。

注意：Cloud Search Indexing API 支援單一網域 ACL。不支援跨網域 ACL。使用 Acl.Builder 類別使用 ACL 設定每個項目的存取權。下列程式碼片段是從完整遍歷樣本中擷取，允許所有使用者或「主體」(getCustomerPrincipal()) 在執行搜尋時擁有所有項目的「讀取者」(.setReaders())。

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

您必須瞭解 ACL，才能正確為存放區建立 ACL 模型。例如，您可能會在檔案系統中使用某種某種繼承模型，為下層資料夾繼承上層資料夾的權限。建立 ACL 繼承需要 Google Cloud Search ACL 中涵蓋的額外資訊

設定項目的中繼資料

中繼資料會儲存在 Item 物件中。如要建立 Item，您需要項目專屬的不重複字串 ID、項目類型、ACL、網址和版本。下列程式碼片段示範如何使用 IndexingItemBuilder 輔助類別建立 Item。

ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

建立可建立索引的項目

設定項目的中繼資料後，您可以使用 RepositoryDoc.Builder 建立實際的可建立索引項目。以下範例說明如何建立單一可建立索引的項目。

ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc 是一種 ApiOperation 類型，可執行實際的 IndexingService.indexItem() 要求。

您也可以使用 RepositoryDoc.Builder 類別的 setRequestMode() 方法，將索引要求識別為 ASYNCHRONOUS 或 SYNCHRONOUS：

ASYNCHRONOUS
非同步模式可延長索引對服務的延遲時間，並長時間為索引要求提供總處理量。建議您為整個存放區進行初始索引 (補充作業) 的非同步模式。
SYNCHRONOUS
同步模式可縮短索引對服務的延遲時間，並提供有限的總處理量。建議您採用同步模式，以便對存放區的更新和變更建立索引。如未指定，要求模式會預設為 SYNCHRONOUS。

後續步驟

建議您採取下列步驟：

使用範本類別建立圖表週遊連接器

Cloud Search Indexing Queue 可用於保存存放區中每個項目的 ID 和選用雜湊值。圖表週遊連接器會將項目 ID 推送到 Google Cloud Search 索引佇列中，一次擷取一個 ID 以便建立索引。Google Cloud Search 會維護佇列並比較佇列內容以判斷項目狀態，例如項目是否已從存放區中刪除。如要進一步瞭解 Cloud Search 索引佇列，請參閱 Google Cloud Search 索引佇列一文。

在索引期間，系統會從資料存放區擷取項目內容，並將任何子項項目 ID 推送至佇列。連接器會以遞迴處理父項和子項 ID，直到所有項目都處理完畢。

本文件的這個章節是指 GraphTraversalSample 範例中的程式碼片段。

實作連接器的進入點

連接器的進入點是 main() 方法。此方法的主要工作是建立 Application 類別的例項，並叫用其 start() 方法來執行連接器。

呼叫 application.start() 之前，請使用 IndexingApplication.Builder 類別將 ListingConnector 範本執行個體化。ListingConnector 可接受 Repository 物件，其實作的方法將會執行。

下列程式碼片段說明如何執行個體化 ListingConnector 及其相關聯的 Repository：

GraphTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

在連接器的 main() 方法呼叫 Application.build 後，SDK 會在背景呼叫 initConfig() 方法。initConfig() 方法：

  1. 呼叫 Configuation.isInitialized() 方法來確保 Configuration 尚未初始化。
  2. 使用 Google 提供的鍵/值組合初始化 Configuration 物件。每個鍵/值組合都會儲存在 Configuration 物件內的 ConfigValue 物件中。

導入 Repository 介面

Repository 物件的唯一用途是執行存放區項目的遍歷與索引。使用範本時，您只需要覆寫 Repository 介面中的特定方法，即可建立內容連接器。您要覆寫的方法取決於您使用的範本和周遊策略。對於 ListingConnector，您可以覆寫以下方法：

  • init() 方法。如要執行任何資料存放區設定和初始化作業，請覆寫 init() 方法。

  • getIds() 方法。如要擷取存放區中所有記錄的 ID 和雜湊值，請覆寫 getIds() 方法。

  • getDoc() 方法。如要從索引中新增、更新、修改或刪除項目，請覆寫 getDoc() 方法。

  • (選用) getChanges() 方法。如果您的存放區支援變更偵測，請覆寫 getChanges() 方法。系統會為每個排程的累加式遍歷 (如設定所定義) 呼叫此方法，以擷取修改的項目並建立索引。

  • (選用) close() 方法。如果您需要執行存放區清理作業，請覆寫 close() 方法。系統會在連接器關閉時呼叫此方法。

Repository 物件的每個方法都會傳回某些類型的 ApiOperation 物件。ApiOperation 物件會以單一 (或多個) IndexingService.indexItem() 呼叫的形式執行動作，以執行存放區的實際索引作業。

取得自訂設定參數

處理連接器設定時，您需要從 Configuration 物件取得任何自訂參數。這項工作通常會在 Repository 類別的 init() 方法中執行。

Configuration 類別有多種方法，可以從設定取得不同的資料類型。每個方法都會傳回 ConfigValue 物件。然後，請使用 ConfigValue 物件的 get() 方法擷取實際值。下列來自 FullTraversalSample 的程式碼片段說明如何從 Configuration 物件擷取單一自訂整數值：

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

如要取得和剖析包含多個值的參數，請使用 Configuration 類別的其中一個類型剖析器，將資料剖析為離散區塊。下列程式碼片段的教學課程連接器使用 getMultiValue 方法取得 GitHub 存放區名稱：

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

執行圖表週遊

覆寫 getIds() 方法，以擷取存放區中所有記錄的 ID 和雜湊值。getIds() 方法可接受查核點。如果檢查過程中斷，檢查點可用來繼續為特定項目建立索引。

接下來，請覆寫 getDoc() 方法來處理 Cloud Search Indexing Queue 中的每個項目。

推送項目編號和雜湊值

覆寫 getIds() 以從存放區擷取項目 ID 及其相關聯的內容雜湊值。接著，ID 和雜湊值組合會包裝在 Cloud Search Indexing Queue 的推送作業要求中，根層級或父項 ID 通常會先推送，接著是子項 ID，直到整個項目階層都處理完畢為止。

getIds() 方法接受一個檢查點，代表要建立索引的最後一個項目。如果處理程序中斷，您可以使用檢查點繼續為特定項目建立索引。針對存放區中的每個項目，在 getIds() 方法中執行下列步驟：

  • 從存放區取得各個項目 ID 與相關的雜湊值。
  • 將每個 ID 和雜湊值組合成一個 PushItems。
  • 將每個 PushItems 合併至 getIds() 方法傳回的 iterator。請注意，getIds() 實際上會傳回 CheckpointCloseableIterable，這是 ApiOperation 物件的疊代，每個物件都代表一個在 RepositoryDoc 上執行的 API 要求的，例如將項目推送至佇列。

下列程式碼片段說明如何取得每個項目 ID 和雜湊值，並將其插入 PushItems。「PushItems」是將項目推送至 Cloud Search Indexing Queue 的 ApiOperation 要求。

GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

下列程式碼片段示範如何使用 PushItems.Builder 類別，將 ID 和雜湊值封裝為單一推送 ApiOperation。

GraphTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

項目會推送至 Cloud Search Indexing Queue 以進一步處理。

擷取並處理每個項目

覆寫 getDoc() 來處理 Cloud Search Indexing Queue 中的每個項目。項目可以是新的、修改、未變更或已不在來源存放區中。擷取每個新項目或修改項目，並為其建立索引。將特定項目從來源存放區中移除。

getDoc() 方法可接受來自 Cloud Search 索引佇列的項目。針對佇列中的每個項目，在 getDoc() 方法中執行下列步驟：

  1. 檢查該項目是否存在於存放區中的 Cloud Search 索引佇列中。如果不是，請將其從索引中刪除。如果該商品確實存在，請繼續進行下一個步驟。

  2. 索引已變更或新增項目：

    1. 設定權限。
    2. 為您要建立索引的項目設定中繼資料。
    3. 將中繼資料和項目結合成一個可建立索引的 RepositoryDoc。
    4. 將子 ID 放入 Cloud Search 索引佇列中，以便進一步處理。
    5. 傳回 RepositoryDoc。

處理已刪除的項目

下列程式碼片段顯示如何判斷索引中是否有該項目，但不會刪除。

GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

設定項目的權限

您的存放區會使用存取控制清單 (ACL) 來識別有權存取項目的使用者或群組。ACL 是可存取該項目的群組或使用者的 ID 清單。

您必須複製存放區使用的 ACL，以確保只有具備項目存取權的使用者能在搜尋結果中看到該項目。在為項目建立索引時，您必須納入項目的 ACL，以便 Google Cloud Search 取得所需資訊，以提供正確的項目層級存取權。

Content Connector SDK 提供豐富的 ACL 類別和方法，可用來建立大部分存放區的 ACL 模型。您必須分析存放區中每個項目的 ACL，並為 Google Cloud Search 建立項目索引時建立對應的 ACL。如果您的存放區的 ACL 採用如 ACL 繼承等概念，那麼使用 ACL 進行模擬可能並不容易。如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL 一文。

注意：Cloud Search Indexing API 支援單一網域 ACL。不支援跨網域 ACL。使用 Acl.Builder 類別使用 ACL 設定每個項目的存取權。下列程式碼片段是從完整遍歷樣本中擷取，允許所有使用者或「主體」(getCustomerPrincipal()) 在執行搜尋時擁有所有項目的「讀取者」(.setReaders())。

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

您必須瞭解 ACL，才能正確為存放區建立 ACL 模型。例如，您可能會在檔案系統中使用某種某種繼承模型，為下層資料夾繼承上層資料夾的權限。建立 ACL 繼承需要 Google Cloud Search ACL 中涵蓋的額外資訊

設定項目的中繼資料

中繼資料會儲存在 Item 物件中。如要建立 Item，您需要項目專屬的不重複字串 ID、項目類型、ACL、網址和版本。下列程式碼片段示範如何使用 IndexingItemBuilder 輔助類別建立 Item。

GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

建立可建立索引的項目

設定項目的中繼資料後，您可以使用 RepositoryDoc.Builder 建立實際的可建立索引項目。以下範例說明如何建立單一可建立索引的項目。

GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc 是一種 ApiOperation 類型，可執行實際的 IndexingService.indexItem() 要求。

您也可以使用 RepositoryDoc.Builder 類別的 setRequestMode() 方法，將索引要求識別為 ASYNCHRONOUS 或 SYNCHRONOUS：

ASYNCHRONOUS
非同步模式可延長索引對服務的延遲時間，並長時間為索引要求提供總處理量。建議您為整個存放區進行初始索引 (補充作業) 的非同步模式。
SYNCHRONOUS
同步模式可縮短索引對服務的延遲時間，並提供有限的總處理量。建議您採用同步模式，以便對存放區的更新和變更建立索引。如未指定，要求模式會預設為 SYNCHRONOUS。

將子 ID 放入 Cloud Search 索引佇列

以下程式碼片段說明如何將目前處理父項項目的子項 ID 加入佇列進行處理。系統會在父項項目建立索引後處理這些 ID。

GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

後續步驟

建議您採取下列步驟：

使用 REST API 建立內容連接器

以下各節說明如何使用 REST API 建立內容連接器。

制定遍歷策略

內容連接器的主要功能是掃遍存放區並為其資料建立索引。您必須根據存放區中的資料大小和版面配置，執行週遊策略。以下是三種常見的周遊策略：

完整拓展策略

完整的周遊策略會掃描整個存放區，並對每個項目進行盲索引。當您有一個小型存放區時，通常會採用此策略，而且每次載入索引時，都能夠進行完整穿越。

此週遊策略適用於具有靜態、非階層性資料的小型存放區。當存放區難以偵測或不支援變更偵測時，您也可以使用此遍歷策略。

列出週遊策略

清單週遊策略會掃描整個存放區 (包括所有子節點)，以判定每個項目的狀態。接著，連接器會使用第二個票證，只對上次建立索引之後新增或更新的項目建立索引。這項策略通常用於對現有索引執行漸進式更新 (不必在每次更新索引時執行遍歷)。

當存放區難以偵測或不支援變更變更、您擁有非階層資料，且您正在處理非常大型的資料集時，此遍歷策略將是適當選擇。

圖表週遊

圖表週遊策略會掃描整個父項節點，判定每個項目的狀態。接著，連接器會再次通過，而且只有根節點中的項目是新索引，或自上次索引之後經過更新。最後，連接器會傳送任何子 ID，然後為新節點或已更新的子節點中的項目建立索引。連接器會透過所有子節點遞迴，直到所有項目都解決為止。這類週遊通常用於階層式存放區，其中所有 ID 皆無從列出。

如果您有需要檢索的階層資料 (例如係列目錄或網頁)，這個策略就相當適用。

導入遍歷策略和項目索引

Cloud Search 的每一個可建立索引元素在 Cloud Search API 中都稱為「項目」。項目可以是檔案、資料夾、CSV 檔案中的行，或是資料庫記錄。

註冊結構定義之後，您就可以依照下列方式填入索引：

  1. (選用) 使用 items.upload 上傳大於 100 KiB 的檔案以供建立索引。如果是較小的檔案，請使用 items.index 以 inlineContent 的形式嵌入內容。

  2. (選用) 使用 media.upload 上傳要建立索引的媒體檔案。

  3. 使用 items.index 為項目建立索引。 例如，如果您的結構定義在電影結構定義中使用物件定義，則單一項目的索引要求看起來會像這樣：

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": {
            "values": [
              "Titanic"
            ]
          }
        },
        {
          "name": "releaseDate",
          "dateValues": {
            "values": [
              {
                "year": 1997,
                "month": 12,
                "day": 19
              }
            ]
          }
        },
        {
          "name": "actorName",
          "textValues": {
            "values": [
              "Leonardo DiCaprio",
              "Kate Winslet",
              "Billy Zane"
            ]
          }
        },
        {
          "name": "genre",
          "enumValues": {
            "values": [
              "Drama",
              "Action"
            ]
          }
        },
        {
          "name": "userRating",
          "integerValues": {
            "values": [
              8
            ]
          }
        },
        {
          "name": "mpaaRating",
          "textValues": {
            "values": [
              "PG-13"
            ]
          }
        },
        {
          "name": "duration",
          "textValues": {
            "values": [
              "3 h 14 min"
            ]
          }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (選用) 使用 items.get 呼叫驗證項目是否已建立索引。

如要執行完整週遊，您需要定期為整個存放區重新建立索引。如要執行清單或圖表週遊，您必須實作程式碼來處理存放區的變更。

處理存放區變更

您可以定期從存放區中收集每個項目並建立索引，以便執行完整的索引作業。雖然能夠確保索引為最新狀態，但在處理大型或階層存放區時，有可能產生完整的索引。

您也可以使用 Google Cloud Indexing Queue 做為追蹤變更機制的機制，並僅對已變更的項目建立索引，這樣就不需要經常使用索引呼叫為整個存放區建立索引。您可以使用 items.push 要求，將項目推送至佇列，以供之後輪詢和更新。如要進一步瞭解 Google Cloud Indexing Queue，請參閱 Google Cloud Indexing 佇列一文。

如要進一步瞭解 Google Cloud Search API，請參閱 Cloud Search API。