用 Scope 篩選結果

Microsoft Web IQ 中的範圍(Scopes)可讓你透過在 Web Search、News Search 和 Auto 結果中納入或排除網址、網站和網域,微調 Grounding API 請求。

開發者與企業管理員可利用 Scopes 將 AI 體驗建立在核准且理想的網路來源上。 定義可重複使用的 URL、網域和路徑包含與排除清單,以控制你的接地搜尋可返回的來源。

作用域是一種包含與排除規則的具名設定。 在 Web IQ 入口網站或客戶管理 API 中為帳單帳號建立範圍,然後在網路搜尋、新聞搜尋或自動要求中依名稱選取該範圍。 這兩種管理選項都使用相同的具名範圍。 這些搜尋範圍並非 Microsoft Entra OAuth 權限範圍。

Warning

對於「自動」,範圍只限制網路和新聞結果。 其他答案類型未被範圍過濾,且可能包含範圍外的結果,即使 scopeApplied 是 true。

商業情境與常見使用案例

劇本 使用案例範例 如何使用 Scopes
精選研究 讓研究助理以你所在組織審查過的來源為基礎,例如經核准的醫學出版物。 請包含核准的網域、子網域或個別頁面。
組織來源政策 請將貴組織限制的網域排除在網路搜尋和新聞搜尋的 grounding 結果中。 維護排除清單,並在每個請求中選擇範圍。
自有資產搜尋 將支援助理或面向員工的搜尋經驗限制在你的公開產品、幫助或公司網站。 請包含你擁有的網域和相關的文件路徑。
精選新聞監控 以所選的一組出版商為依據產生新聞摘要。 請包含發行者網域,並在新聞搜尋要求中選取範疇。

範圍會篩選選定搜尋端點可用的內容。 包含的來源並不保證匹配的內容會被索引或回傳。

Prerequisites

  • 一個有效的 Web IQ 帳單帳號。
  • 若要使用 API 建立範圍,需要有現有的 Microsoft Entra 應用程式、其租戶 ID 與應用程式(用戶端)ID,以及 OAuth 2.0 用戶端憑證流程的憑證。 其工作負載身分識別必須處於啟用狀態,並且在預期的 Web IQ 帳單帳戶上具有CustomerApiAccess。

Important

搜尋 API 與 Web IQ 管理 API 的存取權是分開授予的。 工作中的搜尋 API 金鑰或綁定在 Web IQ 執行檔的 Entra 應用程式,並不會授予建立範圍的權限。 工作負載需要另外的帳單帳戶管理授權。

要檢查入口網站存取權限,打開 Scopes ,尋找預期的帳單帳戶和 New Scope 控制。 若頁面、帳號或創建控制無法使用,請請帳號管理員檢查你的存取權限,或聯絡 Web IQ 支援。

請為你的範圍命名並選擇資料來源

選擇一個裁剪後最多 128 個字元的範圍名稱。 支援的字元包括 ASCII 字母、數字、句點(.)、底線(_)、以及連字號(-)。 空格和斜線不支援。 名稱在範圍集合中不分大小寫唯一。

範圍由 Web IQ 帳單帳戶中的 Web IQ AppID 透過該帳戶指定的範圍集合共享。 它們不是每個 AppID 的獨立設定。 如果帳單帳戶共享一個集合,它們共享相同的範圍和名稱。

  • 納入 會將結果限制為僅包含符合範圍納入清單中至少一個項目的來源。 若清單為空,則所有未被排除的來源皆符合資格。
  • 排除 會移除與範圍排除列表中任何條目相符的結果,即使這些結果也符合包含規則。 排除永遠是優先的。

你可以包含或排除網域、URL 路徑或個別網頁。 每個項目稱為 選擇器:

Selector 範例 相符項目
Domain example.com 網域及其後代子網域
路徑前綴 docs.example.org/products 指定路徑及其在該主機上的子路徑,但不包括像 /products-old 這類路徑
確切 URL https://docs.example.org/products/guide 那是精確的 HTTPS URL,不是路徑下的每個頁面

加入 https:// 會使選擇器比對精確的 URL,而不是網域或路徑前綴。 不支援像 *.example.com 這樣的萬用字元、明確連接埠、查詢字串和片段。 路徑大小寫會被保留。 命名範圍的選擇器沒有獨立的子目錄深度限制,但每個選擇器在裁剪前及正規化後必須能容納在 2,048 個字元內。

API 會標準化、排序及移除重複項目。 被接受的選擇器並不保證匹配的內容會被索引或回傳。

在入口網站建立一個範圍

  1. 開啟Web IQ 入口網站中的 Scopes。
  2. 選擇預期的 帳單帳戶。
  3. 選擇 新範圍。 在 建立新範圍時,輸入 範圍名稱,例如 ProductDocs,並建立該範圍。
  4. 在範圍詳細資料頁面,使用「新增網站」來新增要包含的來源,位於「包含」索引標籤上。 使用「 排除 」標籤上的同一個按鈕來新增排除來源,例如 ads.example.com。
  5. 檢視兩個清單,選擇發佈,並確認發佈變更?

發佈後,傳播至搜尋通常約需10分鐘,但在某些情況下可能長達30分鐘。 請先確認範圍,再於您的應用程式中依賴它。

在搜尋請求中選擇範疇

請另行設定 執行時搜尋認證 。 所選的 Web IQ 應用程式設定檔必須屬於其集合包含你的範圍的 Web IQ 帳單帳戶。

在 POST https://api.microsoft.ai/v3/search/web、POST https://api.microsoft.ai/v3/search/news 或 POST https://api.microsoft.ai/v3/auto 的 JSON 請求主體中設置以下可選欄位。 三個端點都使用相同的命名範圍設定。

參數 類型 Behavior
scopeName 字串 現有範圍的名稱,例如 ProductDocs。 其包含與排除規則會過濾請求的結果。 對於 Auto,範圍只限制網路和新聞結果。 其他答案類型未被範圍過濾,且可能包含範圍外的結果,即使 scopeApplied 是 true。 若省略或 null,則不會要求任何具名範圍。
failOnMissingScope boolean 預設為 true,即使省略或設為 null 時亦然。 當 true時,報告的範圍-應用失敗會回傳錯誤,而非未套用範圍的結果。 當 false時,若無法套用範圍,搜尋可在不套用範圍的情況下繼續進行。 只有在未限制範圍的結果可接受時,才使用 false。 沒有 scopeName 時無效。

在以下範例中,請使用獨立設定的執行時 API 金鑰。

篩選網路搜尋結果

若要搜尋由 ProductDocs 允許的網頁,請發送:

POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

篩選新聞搜尋結果

若要搜尋相同範圍內允許的新聞文章,請使用新聞搜尋端點。 選擇納入的來源,其具有已建立索引的新聞內容;納入的網頁不一定能透過新聞搜尋找到。

POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product announcements",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

篩選自動結果

對於 Auto,範圍只限制網路和新聞結果。 其他答案類型未被範圍過濾,且可能包含範圍外的結果,即使 scopeApplied 是 true。 如果你只想要範圍內的網路與新聞證據,請包含 responseFilter: ["web", "news"]:

POST /v3/auto HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "mode": "lite",
  "responseFilter": ["web", "news"]
}

解譯結果

網路搜尋會回傳位於 webResults 的結果,新聞搜尋會回傳位於 newsResults 的結果,而自動會回傳位於 results 的證據項目(AutoEvidenceResponse)。 有效的作用域可能不會回傳匹配結果,例如當沒有任何索引內容同時符合查詢與範圍規則時。

在預設的 failOnMissingScope: true 情況下,回報的範圍套用失敗會回傳錯誤,而非未套用範圍的結果。 已確認缺少 scope 會回傳 HTTP 400(HandlerInvalidInput);其他 scope 套用失敗則回傳 HTTP 500(ScopeFailedToApply)。 請參見 命名範圍錯誤 以獲得復原指引。

如果你將 failOnMissingScope 設為 false 且找不到範圍,搜尋會針對整個沒有範圍的索引執行,且回應包含 "scopeApplied": false。 這種情況可能發生在名稱錯誤或作用域尚未傳播到處理請求的分割區或副本時。

當找到並套用請求範圍時,回應包含 "scopeApplied": true,即使 failOnMissingScope 是 false。 這確認該請求的範圍已應用,而非最新定義被使用或變更是否覆蓋到每個分割區或副本。 當未報告應用結果時,回應會 scopeApplied 省略;不要將缺失的屬性視為範圍已應用的證明。

如果你省略 scopeName 或設定為 null,則不會請求指定範圍,也 failOnMissingScope 不會有影響。 不要期待對於沒有命名範圍的請求,scopeApplied 會一直存在且其值為 false。

只有當你的應用程式能接受無範圍的結果時才使用 false,並在回應中確認 scopeApplied。 當需要一個作用域時,不要實作會移除該作用域並重新嘗試不受限制請求的備援機制。 請參見 網頁搜尋、 新聞搜尋及 自動 參考,了解請求參數與回應欄位。

用 API 建立一個 scope

所有管理請求皆使用 https://api.microsoft.ai,且路徑皆以 /v1/customer/ 開頭。 在範例中,將 <access-token> 和 <billingAccountId> 替換成預期的帳號 ID 和僅 App 的存取權杖。 授權資源參考與範圍管理參考描述端點合約。

將管理 API 存取權授予應用程式

帳單帳戶或客戶管理員會授予以下存取權限:

  1. 使用現有的 Microsoft Entra 應用程式註冊,或在 Azure 入口網站註冊應用程式。
  2. 在 Web IQ 入口網站開啟帳號設定。
  3. 選擇欲使用的帳單帳戶。
  4. 在 管理 API 存取中,選取 授與 Entra 應用程式存取權。
  5. 在 「授與 Entra 應用程式此帳單帳戶的存取權」 對話方塊中,確認帳單帳戶名稱與 ID。 輸入應用程式的 租戶 ID 與 應用程式(用戶端)ID,以及非空白的 顯示名稱值。
  6. 選擇 「將管理 API 存取權授與此應用程式」,然後選擇 「授權存取」。

授與存取權會授權現有的身分識別。 它不會建立 Entra 應用程式、用戶端密碼、憑證或搜尋 API 金鑰。 該授與適用於所選的帳單帳戶。

授權會指派 CustomerApiAccess 角色。 它不是僅限 scopes(scopes)或唯讀權限:它允許帳號探索、scope(範圍)讀寫,以及執行階段設定檔的 Entra ID 管理。 它不允許應用程式授予其他應用程式存取權。 將授權限制在需要這些管理功能的應用程式。

取得一個僅限應用程式的代幣

利用你應用程式現有的憑證和用戶端憑證流程來請求 Microsoft Entra 存取權杖:

Setting Value
權威 https://login.microsoftonline.com/<tenant-id>
權杖請求範圍 https://api.microsoft.ai/.default

請使用確切的 .default 範圍,而不是你建立的搜尋範圍名稱。 每次管理請求時都發送令牌:

Authorization: Bearer <access-token>

不要用搜尋 API 金鑰來處理這些管理呼叫。 請勿將存取權杖和應用程式憑證放入原始碼控制和診斷報告中。

尋找帳單帳戶

用你的應用程式專用代幣呼叫 GET https://api.microsoft.ai/v1/customer/authorized-resources。 選擇建立請求的預期帳號 billingAccounts[].billingAccountId ;不要自動選擇第一個帳號。

請使用 授權資源參考 作為回應結構、ID 定義及權限欄位解釋的參考。

發送建立請求

使用選定的帳單帳號 ID,傳送 POST /v1/customer/billing-accounts/{billingAccountId}/scopes,並附上你的範圍名稱和規則。 例如:

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}

提供兩個陣列,並使用 [] 表示刻意留空的清單。 在 201 Created上,將回傳的定義和 ETag 保存以供後續修改。

關於標頭、驗證規則及回應細節,請參閱 create-scope 契約。 若要更改現有範圍,而非建立新的,請使用 更新操作。

使用前請確認範圍

  1. 閱讀已儲存的範圍 ,確認其規則是否符合你預期的來源。
  2. 使用 failOnMissingScope: true 執行代表性的網路搜尋、新聞搜尋或自動請求。 在啟用相依流量前,請先檢查包含與排除的情況。

Important

傳播通常約需 10 分鐘,但在某些情況下可能長達 30 分鐘。 沒有傳播 SLA,這些時間也無法保證。 成功的管理寫入或讀取、發佈 或 scopeApplied: true,並不能證明最新的定義已生效。 不要只用經過時間作為準備狀況的檢查。 詳情請參見 搜尋傳播 。

部署已變更的定義

如果暫時使用先前的定義無法接受,則建立一個使用新名稱的範圍,例如 ProductDocs-v2。 在切換來電者前,請完成上述驗證步驟,並保留先前的範圍,直到來電者不再依賴該範圍。

這樣在驗證時,舊名稱的意義不會改變;它不會提供原子級的全局開關。

保留並行控制保護供後續變更使用

在編輯或刪除之前,先閱讀目前的範圍,並在 If-Match 中傳送其加上引號的 ETag。 在協調並行編輯或重試寫入時,請遵循 並行與不確定結果指引。 如果你需要變更記錄,請將已審查過的定義保存在你自己的唯一可信資料來源中。

針對建立進行疑難排解

若預期帳號未被發現,請管理員檢查工作負載身分、管理授權及帳號資格。 其他失敗則使用 發現狀態參考 或 範圍管理錯誤參考。

若持續失敗,請聯絡 Web IQ 支援 ,提供帳單帳號 ID、範圍名稱、UTC 時間、HTTP 狀態及可用請求 ID。 包含經過淨化的預期與實際行為,絕不包含權杖、API 金鑰或應用程式憑證。