本頁的 Cloud Search 教學課程說明如何設定資料來源和內容連接器,以便建立索引。如要從頭開始,請參閱 Cloud Search 入門指南。
建立連接器
將工作目錄變更為 cloud-search-samples/end-to-end/connector
目錄,然後執行下列指令:
mvn package -DskipTests
這個指令會下載建構內容連接器所需的必要依附元件,並編譯程式碼。
建立服務帳戶憑證
連接器需要服務帳戶憑證才能呼叫 Cloud Search API。如何建立憑證:
- 返回 Google Cloud 控制台。
- 在左側導覽列按一下「憑證」。畫面上會顯示「憑證」頁面。
- 按一下「+ CREATE CREDENTIALS」下拉式清單,然後選取「Service account」。接著,「建立服務帳戶」頁面就會出現。
- 在「Service account name」(服務帳戶名稱) 欄位中,輸入「tutorial」。
- 記下服務帳戶 ID 值 (緊接在服務帳戶名稱後方)。 稍後會使用這個值。
- 按一下「建立」。畫面上會顯示「服務帳戶權限 (選用)」對話方塊。
- 按一下「繼續」。畫面上會顯示「將這個服務帳戶的存取權授予使用者 (選用)」對話方塊。
- 點按「完成」。畫面上會顯示「憑證」畫面。
- 在「服務帳戶」下方,按一下服務帳戶電子郵件。「服務帳戶詳細資料」頁面顯示的介面。
- 在「Keys」(金鑰) 下方,按一下「ADD KEY」(新增金鑰) 下拉式清單,然後選取「Create new key」(建立新的金鑰)。畫面上會顯示「建立私密金鑰」對話方塊。
- 點選「建立」。
- (選用) 如果畫面顯示「您要允許在 console.cloud.google.com 上下載嗎?」對話方塊,請按一下「Allow」。
- 私密金鑰檔案會儲存在您的電腦中。記下下載檔案的位置。這個檔案用於設定內容連接器,以便在呼叫 Google Cloud Search API 時自行驗證。
初始化第三方支援
您必須先為 Google Cloud Search 初始化第三方支援,才能呼叫其他 Cloud Search API。
如何初始化 Cloud Search 的第三方支援:
您的 Cloud Search 平台專案含有服務帳戶憑證,不過,為了初始化第三方支援,您必須建立網頁應用程式憑證。如需建立網頁應用程式憑證的操作說明,請參閱「建立憑證」。完成這個步驟後,您會收到用戶端 ID 和用戶端密鑰檔案。
使用 Google OAuth 2 Playground 取得存取權杖:
- 按一下「設定」,然後勾選「使用者自己的驗證憑證」。
- 輸入步驟 1 的用戶端 ID 和用戶端密鑰。
- 按一下「關閉」。
- 在「Scope」(範圍) 欄位中輸入
https://www.googleapis.com/auth/cloud_search.settings
,然後按一下「Authorize」(授權)。OAuth 2 Playground 會傳回授權碼。 - 按一下「ExchangeAuthorization code for token」。系統會傳回權杖。
如要初始化 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 支援團隊聯絡。
使用 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
第三方初始化完成後,其中包含設為
true
的欄位done
。例如:{ name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY" done: true }
建立資料來源
接下來,請在管理控制台中建立資料來源。資料來源會提供命名空間,以便使用連接器為內容建立索引。
- 開啟 Google 管理控制台。
- 按一下「應用程式」圖示。系統會顯示「應用程式管理」頁面。
- 點按「Google Workspace」。系統會顯示「Google Workspace 管理應用程式」頁面。
- 向下捲動並點選「Cloud Search」。系統隨即會顯示「Google Workspace 的設定」頁面。
- 按一下「第三方資料來源」。「資料來源」頁面隨即顯示。
- 按一下黃色圓形 +,「新增資料來源」對話方塊隨即顯示。
- 在「顯示名稱」欄位中,輸入「tutorial」。
- 在「Service account email addresses」(服務帳戶電子郵件地址) 欄位中,輸入您在上一節建立的服務帳戶電子郵件地址。如果您不知道服務帳戶的電子郵件地址,請在服務帳戶頁面中查詢該值。
- 按一下「新增」。畫面上會顯示「已成功建立資料來源」對話方塊。
- 按一下「*確定」。記下新建立的資料來源的來源 ID。來源 ID 可用來設定內容連接器。
為 GitHub API 產生個人存取權杖
連接器需要通過 GitHub API 驗證的存取權,才能擁有足夠的配額。為求簡單起見,連接器會使用個人存取權杖,而非 OAuth。個人權杖可讓使用者以與 OAuth 類似的有限權限組合進行驗證。
- 登入 GitHub。
- 按一下右上角的個人資料相片。下拉式選單隨即顯示。
- 按一下「設定」。
- 按一下「開發人員設定」。
- 按一下「Personal access token」。
- 按一下「Generate Personal access token」。
- 在「備註」欄位中輸入「Cloud Search tutorial」。
- 請檢查 public_repo 範圍。
- 按一下「產生權杖」。
- 記下產生的權杖。連接器會使用這個檔案呼叫 GitHub API,並提供 API 配額來執行索引。
設定連接器
建立憑證和資料來源後,請更新連接器設定以加入這些值:
- 在指令列中,將目錄變更為
cloud-search-samples/end-to-end/connector/
。 - 使用文字編輯器開啟
sample-config.properties
檔案。 - 將
api.serviceAccountPrivateKeyFile
參數設為先前下載服務憑證的檔案路徑。 - 將
api.sourceId
參數設為您先前建立的資料來源 ID。 - 將
github.user
參數設為 GitHub 使用者名稱。 - 將
github.token
參數設為您先前建立的存取權杖。 - 儲存檔案。
更新結構定義
連接器會同時為結構化和非結構化的內容建立索引。您必須先更新資料來源的結構定義,才能為資料建立索引。執行下列指令以更新結構定義:
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
執行個體化並啟動。
SDK 提供的 ListingConnector
會實作週遊策略,運用 Cloud Search 佇列追蹤索引中的項目狀態。它會委派給範例連接器實作的 GithubRepository
,以便存取 GitHub 的內容。
週遊 GitHub 存放區
在完整週遊期間,系統會呼叫 getIds()
方法,將可能需要索引的項目推送至佇列。
連接器可以為多個存放區或機構建立索引。為了盡可能減少失敗的影響,一次只能週遊一個 GitHub 存放區。系統會傳回查核點以及遍歷結果,其中包含要在後續呼叫 getIds()
時建立索引的存放區清單。如果發生錯誤,系統會於目前的存放區恢復建立索引,而非從頭開始建立索引。
collectRepositoryItems()
方法會處理單一 GitHub 存放區的周遊。這個方法會傳回 ApiOperations
集合,代表要推送至佇列的項目。項目會以資源名稱的形式推送,並以雜湊值代表項目目前狀態。
雜湊值會在 GitHub 存放區的後續週遊中使用。這個值可提供輕量的檢查,用於確認內容是否有所變更,而不必上傳其他內容。連接器會模糊地將所有項目排入佇列。如果是新的項目或雜湊值已變更,則將該項目保留在佇列中以供輪詢。否則,系統會將項目視為未經修改。
處理佇列
完整週遊完成後,連接器會開始輪詢佇列,找出需要建立索引的項目。系統會為從佇列提取的每個項目呼叫 getDoc()
方法。該方法會從 GitHub 讀取項目,並將其轉換為適當的表示法來建立索引。
由於連接器正在針對可能隨時變更的即時資料執行,因此 getDoc()
也會驗證佇列中的項目是否仍有效,並刪除索引中已不存在的任何項目。
針對連接器索引的每個 GitHub 物件,對應的 indexItem()
方法會負責建構 Cloud Search 的項目表示法。舉例來說,如要建立內容項目的表示法:
接下來,請部署搜尋介面。