翻頁瀏覽 Foundry IQ(Azure AI 搜尋服務)清單結果

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

本文說明如何依名稱前綴篩選清單結果,以及伺服器端分頁的運作方式。 它透過在多租戶應用程式中列出索引,來示範兩者。

2026-10-01 和 2026-11-01-preview REST API 中的清單操作使用伺服器端分頁,也稱為游標分頁。 用來 search 依名稱前綴篩選清單,並 pageSize 設定每個頁面中您希望的結果數量。

當有更多結果可用時,回應會包含接續 URL。 該 URL 中的接續權杖會告訴服務該在哪裡繼續。 若要瀏覽完整清單,請沿著每個續頁 URL 瀏覽,直到回應中不再包含該續頁 URL。

REST 範例使用 2026-10-01。 C# 和 Python 範例使用 2026-08-01-preview 和預覽版 SDK 套件。

先決條件

  • 最新的 Azure.Search.Documents 預覽套件:dotnet add package Azure.Search.Documents --prerelease

  • 對於無鑰匙認證,套件如下 Azure.Identity : dotnet add package Azure.Identity

    Note

    用戶端函式庫必須支援搜尋服務 REST API 的 2026-10-01 或 2026-08-01-preview 版本。 早於 2026-08-01-preview 此之前的版本會忽略本文中所示的篩選器和分頁參數。

  • 最新的 azure-search-documents 預覽套件:pip install --pre azure-search-documents

  • 對於無鑰匙認證,套件如下 azure-identity : pip install azure-identity

    Note

    用戶端函式庫必須支援搜尋服務 REST API 的 2026-10-01 或 2026-08-01-preview 版本。 早於 2026-08-01-preview 此之前的版本會忽略本文中所示的篩選器和分頁參數。

設定 SDK 範例

設定您的開發環境以執行範例。

  1. 將 AZURE_SEARCH_ENDPOINT 環境變數設為您的 Foundry IQ 服務端點。 這些範例會讀取此值,以告知用戶端要連線到哪個 Foundry IQ 服務。

  2. 安裝 Azure CLI 並使用 az login 登入。 DefaultAzureCredential 可以使用此已登入的帳戶進行驗證。 帳戶的 搜尋服務參與者 角色授權列出作業。

如需其他本地登入選項,請參閱「本地開發的驗證」。

選擇列表操作

2026-10-01 REST API 支援伺服器端分頁執行下列清單操作:

Operation 資源路徑
別名清單 /aliases
列出資料來源 /datasources
列出索引器 /indexers
列出索引 /indexes
取得索引統計摘要 /indexstats
列出知識庫 /knowledgebases
知識來源列表 /knowledgesources
列出知識來源檔案 /knowledgesources('{knowledge-source-name}')/files
列出技能組合 /skillsets
列出同義字對應 /synonymmaps

對於 REST 要求,資料來源、索引器、技能集、同義詞對應,以及會傳回所選屬性的索引清單多載都支援 $select。 不要以為每個清單操作都支援它。

依名稱前綴篩選

使用此 search 參數將清單縮小至名稱以您所提供文字開頭的物件。

除了檔案名稱外,這些清單操作回傳的名稱皆為小寫。 名稱前綴比對會忽略大小寫。 API 會將大寫 search 值視為無效輸入而拒絕,而非將其轉換為小寫。

下列參數控制篩選器:

Parameter Description
search 名稱前置字串。 非空值必須以小寫字母 (a-z) 或數字 (0-9) 開頭,且僅包含小寫字母、數字、連字號及底線。 最大長度為 128 個字元。 無效的值會傳回 HTTP 400。 省略或空值並不會縮小清單。
searchType 服務如何詮釋 search。 prefix 是唯一支援的值,也是預設值。 其他值回傳 HTTP 400。

對於檔案清單,search 會比對回傳的 fileName 值,包括任何相對路徑,不分大小寫。 檔案名稱可以包含大寫字母。 獨立的 prefix 路徑篩選器會區分大小寫。

選擇不重疊的租戶前綴。 例如, search=contoso- 回傳 contoso-orders 和 contoso-products ,但排除 contoso2-orders。 請求會 search=toso 回傳空 value 陣列,因為篩選器與名稱開頭相符。

程式碼範例

以下程式碼列出 多租用戶應用程式中單一租用戶的索引。 每個索引名稱都以租戶前綴開頭,例如 contoso- 或 contoso2-。

程式碼會依 contoso- 前綴篩選清單,並每頁最多請求 10 個索引。 對於擁有 27 個相符索引的租戶,服務可傳回分別包含 10、10 和 7 個索引的頁面。

迴圈從篩選清單的開頭開始。 若要恢復,請將先前儲存的 page.ContinuationToken 值傳入 AsPages(token)。

using System;
using Azure;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

string endpoint = Environment.GetEnvironmentVariable(
    "AZURE_SEARCH_ENDPOINT")!;

var options = new SearchClientOptions(
    SearchClientOptions.ServiceVersion.V2026_08_01_Preview);
var client = new SearchIndexClient(
    new Uri(endpoint),
    new DefaultAzureCredential(),
    options);

// Filter by the tenant prefix and limit each page to 10 indexes
AsyncPageable<SearchIndex> indexes = client.GetIndexesAsync(
    search: "contoso-",
    pageSize: 10,
    searchType: ListingSearchType.Prefix);

// Fetch pages until the service returns no continuation token
await foreach (Page<SearchIndex> page in indexes.AsPages())
{
    // Read the indexes in this page without fetching another page
    foreach (SearchIndex index in page.Values)
    {
        Console.WriteLine(index.Name);
    }
}

參考:SearchIndexClient.GetIndexesAsync、 AsPages、 ContinuationToken 及 DefaultAzureCredential

外層迴圈會呼叫 AsPages() 一次,SDK 會在每次迭代中擷取一個頁面,並保留其續續權杖以供下一次請求使用。 外層迴圈用於 await 等待每個服務回應而不阻塞執行緒,而內層迴圈則讀取記憶體中的索引。 當最後一頁有 null 延續權杖時,SDK 會回報沒有更多頁面,循環結束。

外層迴圈會逐一周遊各個頁面。 內層迴圈會逐一處理每一頁上的索引。

import os

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

endpoint = os.getenv("AZURE_SEARCH_ENDPOINT")

with SearchIndexClient(
    endpoint,
    DefaultAzureCredential(),
    api_version="2026-08-01-preview",
) as client:
    # Filter by the tenant prefix and limit each page to 10 indexes
    indexes = client.list_indexes(
        select=["name"],
        search="contoso-",
        page_size=10,
        search_type="prefix",
    )

    # Create the page iterator once, starting at the first page
    pages = indexes.by_page()

    # Fetch pages until the service returns no continuation token
    for page in pages:
        # Read the indexes in this page without fetching another page
        for index in page:
            print(index.name)

參考:SearchIndexClient.list_indexes、 ItemPaged.by_page 與 DefaultAzureCredential

by_page() 建立頁面迭代器一次,然後 for page in pages 使用儲存在該迭代器的延續權杖請求每個頁面。 內層迴圈在不需其他請求的情況下讀取單一頁面的索引,而外層迴圈則在最後一頁有 None 延續標記時停止。 新的迭代器從第一頁開始,權杖為空或為 None,而 by_page(continuation_token=token) 從已儲存的標記繼續。

發送初始請求,列出名稱以 contoso-為開頭的索引。 此請求最多可回傳 10 個索引名稱:

GET https://<search-service-name>.search.windows.net/indexes?api-version=2026-10-01&search=contoso-&searchType=prefix&pageSize=10&$select=name
Authorization: Bearer <access-token>
Accept: application/json

參考資料:列出索引

當有更多結果可用時,回應會包含 @odata.nextLink,其中包含完整的續頁 URL 與不透明的標記。 一個頁面可以包含少於 10 個結果,並且仍包含續頁 URL。 以下回應為簡短說明:

{
  "value": [
    {
      "name": "<index-name>"
    }
  ],
  "@odata.nextLink": "https://<search-service-name>.search.windows.net/indexes?api-version=2026-10-01&searchType=prefix&%24select=name&%24skiptoken=<opaque-token>"
}

若要請求下一頁,請使用傳回的完整 @odata.nextLink 值原樣傳送 GET 要求。 search 數值與頁面大小會編碼在接續權杖中。 保持相同的認證標頭:

GET <[email protected]>
Authorization: Bearer <access-token>
Accept: application/json

參考資料:索引清單

每新增 @odata.nextLink 一個值就重複這個請求。 最後一頁包含剩餘的索引名稱並省略 @odata.nextLink,表示沒有更多可用的頁面:

{
  "value": [
    {
      "name": "<next-index-name>"
    }
  ]
}

伺服器端分頁行為

  • 偵測最後一頁: 當回應包含 @odata.nextLink 時,請持續分頁,即使某頁包含的結果少於要求的數量。 最後一頁省略了此屬性。 回應不包含 @odata.count。

  • 保留延續狀態: 請完全依照傳回的內容原樣使用完整 @odata.nextLink。 不要構造、修改或解碼續寫權杖(值), $skiptoken 也不要用其他串列操作來使用。 權杖僅支援向前分頁。

  • 變更請求參數: 啟動新的初始請求,以變更資源路徑、API 版本、搜尋前綴、所選屬性或頁面大小。 將 search 與 $skiptoken 或 pageSize 組合時,會回傳 HTTP 400。

  • 請考慮集合變更: 只有當集合未變更時,前向分頁才會穩定。 在列舉過程中新增、更新或刪除物件可能會產生重複或遺漏的結果。

  • 不要只依賴結果順序: 這項服務並不保證結果的順序。

  • 設定頁面大小:pageSize 預設為每頁 3,000 個項目,且最大允許值為 3,000 個。