建立內容連接器

「內容連接器」是一種軟體程式，可用來週遊資料庫中的資料 並填入資料來源Google 提供下列指標： 內容連接器開發選項：

• Content Connector SDK。如要設計程式，建議採用這種做法 。Content Connector SDK 是包裝函式 REST API，可讓您快速建立連接器。創作內容 請參閱 使用 Content Connector SDK 建立內容連接器。

• 低階 REST API 或 API 程式庫。如果您不是 或是您的程式碼集更適合使用 REST API 或程式庫如要使用 REST API 建立內容連接器，請參閱 到 使用 REST API 建立內容連接器。

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

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

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

下列各節將說明如何使用 Content Connector SDK。

設定依附元件

您必須在建構檔案中加入特定依附元件，才能使用 SDK。按一下 ，查看建構環境的依附元件：

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

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 帳戶。

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

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

將設定檔傳送至連接器

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

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

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

決定週遊策略

內容連接器的主要功能是掃遍存放區 建立索引您必須根據 存放區中的資料版面配置你可以自行設計策略，也可以選擇 ：

完整週遊策略

完整的周遊策略掃描整個存放區，以及盲目索引 每個項目當存放區較小，且 能夠負擔得起您每次為索引 執行完整週遊的負擔

這項週遊策略適用於大部分 靜態、非階層式的靜態資料您也可以使用這項週遊策略 變更偵測不準確或存放區不支援的情況下。

清單週遊策略

清單週遊策略會掃描整個存放區，包括所有子項 進而決定每個項目的狀態接著，連接器會花費一秒 然後只將新項目或自上次更新後已更新的項目編入索引 建立索引這項策略通常用於執行 更新現有索引 (不必每次都執行 您更新索引時)。

此週遊策略在難以偵測變更，或 存放區不支援、非階層式資料，而您 處理極為龐大的資料集

圖表週遊

圖表週遊策略可掃描整個父項節點 每個項目的狀態。接著，連接器會第二次通過，且只會建立索引 根節點中的項目為新的項目，或自上次建立索引後已更新內容。 最後，連接器會傳送任何子 ID，然後為子節點中的項目建立索引 建立容器連接器會以遞迴方式持續執行 直到所有項目都處理完為止。這類週遊通常 用於階層式存放區，但其中會列出所有 ID 實際可行

如果您有需要的階層式資料 例如一系列目錄或網頁

，瞭解如何調查及移除這項存取權。

以上週遊策略皆由範本連接器實作 SDK 中的類別。雖然你可以導入自己的周遊策略 大幅加快連接器的開發速度。目的地： 使用範本建立連接器，並繼續前往 你的周遊策略：

• 使用範本類別建立完整的周遊連接器
• 使用範本類別建立清單週遊連接器
• 使用範本類別建立圖表週遊連接器

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

在這一節，說明文件中的 FullTraversalSample 範例。

實作連接器的進入點

連接器的進入點是 main() 方法。這個方法的主要工作是建立 Application敬上 並叫用其類別 start() 方法來執行連接器。

通話前 application.start()、 請使用 IndexingApplication.Builder 類別，將 FullTraversalConnector 範本。 FullTraversalConnector敬上 接受 Repository 物件。下列程式碼片段顯示 實作 main() 方法：

/**
 * 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();
}

SDK 會在背景呼叫 initConfig()敬上 方法出現在連接器的 main() 方法呼叫之後 Application.build。 initConfig() 種方式 會執行下列工作：

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

導入 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 物件的單一自訂整數值：

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

如要取得並剖析含有數個值的參數，請使用 Configuration 類別的類型剖析器來將資料剖析為獨立的區塊。 下列程式碼片段取自教學課程連接器 getMultiValue敬上 方法來取得 GitHub 存放區名稱清單：

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，例如建立索引。

如果項目組合過大，無法在單一呼叫中處理，請加入 檢查站 hasMore(true)敬上 ，指出還有更多可建立索引的項目。

設定項目的權限

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

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

Content Connector SDK 提供了豐富的 ACL 類別和方法， 建立大多數存放區的 ACL您必須分析以下項目的 ACL： 並為 Google Cloud Search 建立對應的 ACL 編入索引如果存放區的 ACL 採用了 ACL 等概念 然而，如果以 ACL 手法呈現 ACL 可能並不容易如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL。

注意：Cloud Search Indexing API 支援單一網域 ACL。沒有 支援跨網域 ACL。使用 Acl.Builder敬上 類別，使用 ACL 設定每個項目的存取權。下列程式碼片段 從完整週遊樣本中 所有使用者或「主體」 (getCustomerPrincipal())。 也就是所有項目的「讀者」 (.setReaders()) 也比較容易瞭解

// 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、網址和版本。 下列程式碼片段說明如何使用 Item IndexingItemBuilder 輔助類別中。

// 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敬上 類別以下範例說明如何建立單一可編入索引的項目。

// 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() 要求。

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

ASYNCHRONOUS

非同步模式會導致索引建立服務延遲的時間較長，且 適用於索引要求的大型處理量配額。非同步模式為 建議您用於執行整個存放區的初始索引 (補充作業) 作業。

SYNCHRONOUS

同步模式可縮短索引至提供服務的延遲時間， 可採納有限的處理量配額。同步模式為 建議用於建立更新項目和存放區變更的索引。如果 未指定，要求模式預設為 SYNCHRONOUS。

將每個可建立索引的項目封裝在疊代器中

getAllDocs() 這個方法會傳回 Iterator，特別是 CheckpointCloseableIterable、 / RepositoryDoc 如需儲存大量結構化物件 建議使用 Cloud Bigtable您可以使用 CheckpointClosableIterableImpl.Builder敬上 類別，建構並傳回疊代器。下列程式碼片段顯示 建構並傳回疊代器

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

SDK 會執行疊代器中包含的每個索引呼叫。

後續步驟

以下是您可能採取的後續步驟：

• (選用) 如果你的索引處理量似乎緩慢，請參閱「提高 FullTraversalConnector 的索引建立率」。
• (選用) 導入 close() 方法以在關閉前釋出任何資源。
• (選用) 建立識別資訊連接器 整合內容

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

Cloud Search Indexing 佇列可用來保存 ID 和選用的雜湊值 存放區中每個項目的值清單週遊連接器推送 項目 ID 加入 Google Cloud Search Indexing 佇列，並逐一擷取 建立索引所需的時間。Google Cloud Search 會維護佇列 比較佇列內容來判斷項目狀態，例如項目是否 已從存放區刪除如要進一步瞭解 Cloud Search 建立索引佇列，請參閱 Cloud Search Indexing API 佇列。

在這一節，說明文件中的 ListTraversalSample 範例。

實作連接器的進入點

連接器的進入點是 main() 方法。這個方法的主要工作是建立 Application敬上 並叫用其類別 start() 方法來執行連接器。

通話前 application.start()、 請使用 IndexingApplication.Builder 類別，將 ListingConnector 範本。ListingConnector 接受 Repository 物件。下列程式碼片段說明如何 將 ListingConnector 及其相關聯的 Repository 例項化：

/**
 * 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();
}

SDK 會在背景呼叫 initConfig()敬上 方法出現在連接器的 main() 方法呼叫之後 Application.build。 initConfig() 方法：

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

導入 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 物件的單一自訂整數值：

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

如要取得並剖析含有數個值的參數，請使用 Configuration 類別的類型剖析器來將資料剖析為獨立的區塊。 下列程式碼片段取自教學課程連接器 getMultiValue敬上 方法來取得 GitHub 存放區名稱清單：

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

執行清單週遊

覆寫 getIds()敬上 方法來擷取存放區中所有記錄的 ID 和雜湊值。 getIds() 方法可接受查核點。系統會使用查核點恢復運作 ，應該就會中斷該程序。

接下來，請覆寫 getDoc()敬上 方法處理 Cloud Search 索引佇列中的每個項目。

推送項目 ID 和雜湊值

覆寫 getIds()敬上 從 Cloud Storage 也提供目錄同步處理功能然後，系統會將 ID 和雜湊值組合封裝至推送作業 將要求傳送至 Cloud Search Indexing 佇列根 ID 或父項 ID 通常是 依序按下子 ID 和子 ID，直到項目階層完成 處理完畢

getIds() 方法接受查核點，以代表要提供的最後一個項目 已編入索引。查核點可用於恢復特定項目的索引作業 程序中斷。針對存放區中的每個項目，執行下列動作 getIds() 方法中的步驟：

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

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

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。

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

系統會將項目推送至 Cloud Search 索引佇列，以進行進一步處理。

擷取及處理每個項目

覆寫 getDoc() 用於處理 Cloud Search Indexing 佇列中的每個項目。 項目可以是新增、修改、未變更，或是不再存在於來源中 Cloud Storage 也提供目錄同步處理功能擷取每個新或修改過的項目並建立索引。移除項目 從來源存放區不再存在的索引中移除。

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

1. 檢查項目的 ID 是否位於 Cloud Search 索引佇列中 指定容器映像檔如果沒有，請從索引刪除項目。

2. 輪詢項目狀態的索引，如果項目未變更 (ACCEPTED)，則不要 什麼都不做

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

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

注意：ListingConnector 範本不支援在以下日期傳回 null： getDoc() 方法。傳回 null 結果，此結果為 NullPointerException.

處理已刪除的項目

下列程式碼片段說明如何判斷項目是否存在於 如果有，請將其刪除

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 中輪詢項目狀態 將佇列編入索引並處理未變更的項目。

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();
}

如要判斷項目是否已修改，請一併檢查項目狀態 顯示為其他中繼資料在這個例子中 雜湊碼可用來判斷項目是否已變更。

/**
 * 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 手法呈現 ACL 可能並不容易如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL。

注意：Cloud Search Indexing API 支援單一網域 ACL。沒有 支援跨網域 ACL。使用 Acl.Builder敬上 類別，使用 ACL 設定每個項目的存取權。下列程式碼片段 從完整週遊樣本中 所有使用者或「主體」 (getCustomerPrincipal())。 也就是所有項目的「讀者」 (.setReaders()) 也比較容易瞭解

// 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、網址和版本。 下列程式碼片段說明如何使用 Item IndexingItemBuilder 輔助類別中。

// 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。 以下範例說明如何建立單一可編入索引的項目。

// 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() 請求。

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

ASYNCHRONOUS

非同步模式會導致索引建立服務延遲的時間較長，且 適用於索引要求的大型處理量配額。非同步模式為 建議您用於執行整個存放區的初始索引 (補充作業) 作業。

SYNCHRONOUS

同步模式可縮短索引至提供服務的延遲時間， 可採納有限的處理量配額。同步模式為 建議用於建立更新項目和存放區變更的索引。如果 未指定，要求模式預設為 SYNCHRONOUS。

，瞭解如何調查及移除這項存取權。

後續步驟

以下是您可能採取的後續步驟：

• (選用) 導入 close() 方法以在關閉前釋出任何資源。
• (選用) 建立識別資訊連接器 整合內容

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

Cloud Search Indexing 佇列可用來保存 ID 和選用的雜湊值 為存放區中的每個項目建立狀態圖表週遊連接器會將項目 ID 推送到 Google Cloud Search Indexing 佇列，並逐一擷取 建立索引Google Cloud Search 會維護佇列，並比較佇列內容到 判斷項目狀態，例如該項目是否已從 Cloud Storage 也提供目錄同步處理功能如要進一步瞭解 Cloud Search Indexing 佇列，請參閱 到 Google Cloud Search Indexing 佇列。

索引期間，商品內容會從資料存放區和 子項項目 ID 會推送至佇列。連接器會以遞迴方式繼續操作 才會處理父項和子項 ID，直到所有項目都處理完成。

在這一節，說明文件中的 GraphTraversalSample 範例。

實作連接器的進入點

連接器的進入點是 main() 方法。這個方法的主要工作是建立 Application敬上 並叫用其類別 start() 方法來執行連接器。

通話前 application.start()、 請使用 IndexingApplication.Builder 類別，將 ListingConnector 範本例項化。 ListingConnector敬上 接受 Repository 物件。

下列程式碼片段說明如何 將 ListingConnector 及其相關聯的 Repository 例項化：

/**
 * 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();
}

SDK 會在背景呼叫 initConfig()敬上 方法出現在連接器的 main() 方法呼叫之後 Application.build。 initConfig() 方法：

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

導入 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 物件的單一自訂整數值：

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

如要取得並剖析含有數個值的參數，請使用 Configuration 類別的類型剖析器來將資料剖析為獨立的區塊。 下列程式碼片段取自教學課程連接器 getMultiValue敬上 方法來取得 GitHub 存放區名稱清單：

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

執行圖形週遊

覆寫 getIds()敬上 方法來擷取存放區中所有記錄的 ID 和雜湊值。 getIds() 方法可接受查核點。系統會使用查核點恢復運作 ，應該就會中斷該程序。

接下來，請覆寫 getDoc()敬上 方法處理 Cloud Search 索引佇列中的每個項目。

推送項目 ID 和雜湊值

覆寫 getIds()敬上 從 Cloud Storage 也提供目錄同步處理功能然後，系統會將 ID 和雜湊值組合封裝至推送作業 將要求傳送至 Cloud Search Indexing 佇列根 ID 或父項 ID 通常是 依序按下子 ID 和子 ID，直到項目階層完成 處理完畢

getIds() 方法接受查核點，以代表要提供的最後一個項目 已編入索引。查核點可用於恢復特定項目的索引作業 程序中斷。針對存放區中的每個項目，執行下列動作 getIds() 方法中的步驟：

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

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

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

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

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

系統會將項目推送至 Cloud Search 索引佇列，以進行進一步處理。

擷取及處理每個項目

覆寫 getDoc() 用於處理 Cloud Search Indexing 佇列中的每個項目。 項目可以是新增、修改、未變更，或是不再存在於來源中 Cloud Storage 也提供目錄同步處理功能擷取每個新或修改過的項目並建立索引。移除項目 從來源存放區不再存在的索引中移除。

getDoc() 方法接受 Cloud Search Indexing 中的項目 待播清單。對佇列中的每個項目執行下列步驟： getDoc() 方法：

1. 檢查該項目的 ID 是否位於 Cloud Search Indexing 佇列的 Cloud Storage 也提供目錄同步處理功能如果沒有，請從索引刪除項目。如果項目確實存在 繼續進行下一步

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

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

處理已刪除的項目

下列程式碼片段說明如何判斷索引中有項目 而不是刪除

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 手法呈現 ACL 可能並不容易如要進一步瞭解 Google Cloud Search ACL，請參閱 Google Cloud Search ACL。

注意：Cloud Search Indexing API 支援單一網域 ACL。沒有 支援跨網域 ACL。使用 Acl.Builder敬上 類別，使用 ACL 設定每個項目的存取權。下列程式碼片段 從完整週遊樣本中 所有使用者或「主體」 (getCustomerPrincipal())。 也就是所有項目的「讀者」 (.setReaders()) 也比較容易瞭解

// 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、網址和版本。 下列程式碼片段說明如何使用 Item IndexingItemBuilder 輔助類別中。

// 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。 以下範例說明如何建立單一可編入索引的項目。

// 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() 要求。

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

ASYNCHRONOUS

非同步模式會導致索引建立服務延遲的時間較長，且 適用於索引要求的大型處理量配額。非同步模式為 建議您用於執行整個存放區的初始索引 (補充作業) 作業。

SYNCHRONOUS

同步模式可縮短索引至提供服務的延遲時間， 可採納有限的處理量配額。同步模式為 建議用於建立更新項目和存放區變更的索引。如果 未指定，要求模式預設為 SYNCHRONOUS。

將子 ID 放入 Cloud Search 索引佇列

以下程式碼片段說明如何在 目前處理父項項目排入處理佇列中這些 ID 才會在父項項目建立索引後才處理

// 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();

後續步驟

以下是您可能採取的後續步驟：

• (選用) 導入 close() 方法以在關閉前釋出任何資源。
• (選用) 建立識別資訊連接器 使用 Identity Connector SDK

使用 REST API 建立內容連接器

下列各節將說明如何使用 REST API 使用。

決定週遊策略

內容連接器的主要功能是掃遍存放區 建立索引您必須根據 存放區中的資料版面配置以下是三種常見的周遊 策略：

完整週遊策略

完整的周遊策略掃描整個存放區，以及盲目索引 每個項目當存放區較小，且 能夠負擔得起您每次為索引 執行完整週遊的負擔

這項週遊策略適用於大部分 靜態、非階層式的靜態資料您也可以使用這項週遊策略 變更偵測不準確或存放區不支援的情況下。

清單週遊策略

清單週遊策略會掃描整個存放區，包括所有子項 進而決定每個項目的狀態接著，連接器會花費一秒 然後只將新項目或自上次更新後已更新的項目編入索引 建立索引這項策略通常用於執行 更新現有索引 (不必每次都執行 您更新索引時)。

此週遊策略在難以偵測變更，或 存放區不支援、非階層式資料，而您 處理極為龐大的資料集

圖表週遊

圖表週遊策略可掃描整個父項節點 每個項目的狀態。接著，連接器會第二次通過，且只會建立索引 根節點中的項目為新的項目，或自上次建立索引後已更新內容。 最後，連接器會傳送任何子 ID，然後為子節點中的項目建立索引 建立容器連接器會以遞迴方式持續執行 直到所有項目都處理完為止。這類週遊通常 用於階層式存放區，但其中會列出所有 ID 實際可行

如果您有需要的階層式資料 例如係列目錄或網頁

，瞭解如何調查及移除這項存取權。

實作週遊策略和索引項目

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

註冊結構定義後，即可透過以下方式填入索引：

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

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 呼叫驗證商品 已建立索引。

如要執行完整的周遊，建議您定期為整個 Cloud Storage 也提供目錄同步處理功能如要執行清單或圖形週遊，您必須執行 處理存放區變更。

處理存放區變更

您可以定期收集存放區中的每個項目並建立索引，以便執行 完整的索引建立作業除了能有效確保索引是最新的， 處理大型存放區或階層存放區時，可能會耗用大量資源。

您應避免頻繁使用索引呼叫為整個存放區建立索引，而不是頻繁地為整個存放區建立索引 您也可以使用 Google Cloud Indexing Queue 以利追蹤變更，並只為含有 已變更。您可以使用 items.push 要求將項目推送到佇列，以便稍後輪詢及更新。如要 Google Cloud Indexing 佇列的相關資訊，請參閱 Google Cloud Indexing 佇列：

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