連線 Bot 進行搜尋（預覽）

發行項
01/11/2024

本文說明如何建立自定義同盟搜尋提供者（由 Bot 提供電源），並將其連線至搜尋通道。一旦租用戶系統管理員在其租用戶中啟用提供者，企業使用者就會從 Office.com、SharePoint.com 和 Bing.com 搜尋，包含自定義搜尋提供者的結果。

Microsoft 同盟搜尋平臺可讓您建置自定義的同盟搜尋提供者，讓您的資訊能夠參與 Microsoft 搜尋的答案和垂直體驗，而不需要將該資訊與您的 Microsoft 365 索引合併。如需詳細資訊，請參閱 Microsoft 同盟搜尋平臺和 Dynamics 365 同盟搜尋（預覽）的宣布開發人員預覽。

注意

搜尋通道處於私人預覽狀態。若要要求存取權，請使用 Microsoft 搜尋 Developer Private Preview 窗體。在問題 7 中，選取 [同盟搜尋]。

您必須執行下列步驟，才能將 Bot 連線至搜尋通道。本文稍後會詳細說明這些步驟。

實作 Bot 以做為搜尋提供者。
如果您的 Bot 需要使用者登入：
1. 在 Azure 入口網站中，將 Bot API 公開至搜尋平臺。
2. 在您的 Bot 程式代碼中，使用產生的範圍 URI 來產生使用者令牌。
將 Bot 部署到 Azure。
將搜尋通道新增至 Bot。
要求 IT 系統管理員檢閱 Bot 註冊，並在租用戶中發佈 Bot。

提示

建議您在生產環境中啟用搜尋提供者之前，先在測試租用戶中啟用搜尋提供者。

必要條件

瞭解 Bot Framework 服務的基本概念，以及如何使用 Bot Framework SDK 建立 Bot。
要連線到通道的 Bot。
如果您沒有 Azure 帳戶，請在您開始之前先建立免費帳戶。

您可以使用 Bot Framework SDK 所支援的任何語言來實作 Bot。本文使用 C# 同盟搜尋 Bot 作為範例。

將 Bot API 公開至搜尋

提示

只有在 Bot 需要存取受保護的用戶資源時，才需要此步驟。

在某些商務工作流程中，Bot 可能需要用戶認證，才能代表使用者執行動作。若要在搜尋通道中為您的 Bot 建立單一登入（SSO）體驗，您必須允許搜尋平臺代表用戶保護來自 Microsoft Entra ID 的存取令牌。

若要為您的 Bot 產生範圍 URI 和應用程式識別碼：

前往 Azure 入口網站。
如果您還沒有 Bot 資源，請建立 Azure Bot 資源。
移至 Microsoft Entra ID 服務。
移至 [應用程式註冊] 窗格。
選取與您的 Bot 相關聯的應用程式。
移至 [ 公開 API ] 窗格。
選取新增範圍。
1. 在 [ 新增範圍 ] 窗格中，建議您保留自動產生的 應用程式標識碼 URI。選取 [儲存並繼續] 。
2. 輸入範圍名稱。
3. 對於 神秘可以同意嗎？，建議使用管理員和使用者，但兩個選項都可以運作。
4. 輸入 管理員同意顯示名稱和管理員同意描述。
5. 或者，輸入使用者同意顯示名稱和使用者同意描述。
6. 確認 [狀態 ] 已設定為 [已啟用]。
7. 選取新增範圍。
選取新增用戶端應用程式。
1. 在 [新增用戶端應用程式] 窗格中，將 [用戶端標識符] 設定為 81473081-50b9-469a-b9d8-303109583ecb，搜尋平臺的用戶端識別碼。
2. 在 [授權範圍] 下，選取您在上一個步驟中建立的範圍 URI。
3. 選取新增應用程式。
移至 [ 概觀 ] 窗格。 複製應用程式識別碼 URI。當您在搜尋通道中註冊 Bot 時，您將需要此專案。

實作 Bot

搜尋通道會將每個使用者查詢傳送至 Bot，作為名為「application/search」的叫用活動。您的 Bot 會在叫用回應中傳回查詢結果。針對傳回至搜尋通道的查詢結果，使用調適型卡片格式。

將專案中的任何 Bot Framework 和調適型卡片套件更新為最新版本。
或者，新增驗證碼以產生使用者令牌。
針對要包含的每個數據源實作數據搜尋方法。
產生調適型卡片以顯示結果。

取得搜尋平臺追蹤標識碼

搜尋平臺會將唯一的追蹤標識碼指派給傳送至 Bot 的每個查詢。平臺會將此新增至叫用活動的通道數據。您可能會決定記錄要求的追蹤識別碼。使用通道數據的 traceId 屬性來取得追蹤標識符。

在同盟搜尋範例中SearchHelper.GetSearchTraceId，方法示範如何從叫用活動取得追蹤標識符。

新增驗證

如果您將 Bot API 公開至搜尋，並在將 Bot 連線至搜尋時要求驗證，您可以從活動的通道數據取得使用者驗證令牌。

通道資料的 authorizations 屬性可以包含驗證令牌清單。如果您將 Bot API 公開至 [搜尋]，清單將會包含代表令牌。清單中的權杖會有下列結構：

屬性名稱	類型	描述
authType	整數	驗證令牌類型： `0` 未知或預設值，或 `2` 代表令牌。
token	string	驗證令牌本身。

在同盟搜尋範例中：

類別 SearchBotAuthenticationToken 和 AuthenticationTypes 列舉表示這項資訊。
方法 SearchHelper.GetSearchOboToken 示範如何從叫用活動取得令牌。

擁有令牌之後，您可以在要求使用者的任何受保護資源時使用它。如需使用代理令牌的資訊，請參閱 Microsoft 身分識別平台和 OAuth 2.0 代理者流程。

查詢每個數據存放區

搜尋通道會將查詢傳送至 Bot 做為 invoke 活動，而活動 value 屬性中的查詢詳細數據則代表具有下列結構的 JSON 物件：

屬性名稱	類型	描述
queryText	string	查詢文字。
kind	string	查詢類型：當結果會顯示在自定義垂直索引標籤中時，或當結果顯示為 [所有] 索引標籤中的答案時，則為 “searchAnswer”。
queryOptions	object	用於分頁的其他查詢選項。
queryOptions.skip	整數	要傳送之第一個結果的索引。
queryOptions.top	整數	要傳送的結果數目上限。

您會在叫用回應中傳回搜尋結果：

一律將叫用回應物件的 Status 屬性設定為 200，這表示網路連線沒問題。對象的 Body 屬性有個別的狀態代碼。

屬性 Body 代表具有下列結構的 JSON 物件：

屬性名稱	類型	描述
statusCode	整數	用來指出 Bot 是否能夠成功執行查詢的 HTTP 狀態代碼。
type	string	叫用回應的類型，定義值欄位的格式。針對搜尋結果使用「application/vnd.microsoft.search.searchResponse」，或針對錯誤訊息使用 “application/vnd.microsoft.error”。
value	object	對應至值的值 `type`。

針對錯誤訊息， value 物件包含：

屬性名稱	類型	描述
code	string	Bot 所定義的錯誤碼，如果未指定， `null` 則為。
message	string	錯誤訊息，如果未指定， `null` 則為。

針對搜尋結果， value 物件包含：

屬性名稱	類型	描述
結果	搜尋結果對象的陣列	結果，如果沒有 `null` ，則為。
displayLayouts	顯示配置物件的陣列	顯示版面配置，如果沒有 `null` 則為。
totalResultCount	整數	如果支援分頁，則提供的總結果;否則為 `null`。
moreResultsAvailable	布林值	指出是否有更多結果可供使用。

搜尋結果物件包含：

屬性名稱	類型	描述
value	string	此搜尋結果的唯一標識碼或值。
layoutId	string	要用於此結果的顯示配置識別碼。
data.searchResultText	string	此結果的文字。

顯示版面設定物件包含：

屬性名稱	類型	描述
layoutId	string	配置標識碼。
layoutBody	string	配置本文做為調適型卡片 JSON 物件。

在同盟搜尋範例中，SearchHelper.RunFederatedSearch方法示範如何從叫用活動取得查詢資訊，以及如何格式化叫用回應。

顯示搜尋結果

您可以建立搜尋垂直和結果類型，以自定義使用者在 SharePoint、Office 和 Bing 中搜尋時看到的搜尋結果。垂直可讓使用者更輕鬆地尋找他們有權查看的資訊。如需詳細資訊，請參閱支援的調適型卡片元素一節。

如果您的 Bot 收到沒有回應的查詢，其回復應包含空的回應。

在 Azure 中註冊 Bot

若要將 Bot 連線至搜尋通道，您必須在 Azure 中佈建 Bot 資源。如需詳細資訊，請參閱如何使用 Azure 註冊 Bot，或如何在 Azure 中部署 Bot。