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 套件。
先決條件
Foundry IQ(Azure AI 搜尋服務)服務,其中包含其中一種支援的列出作業所需的物件。
列出服務上物件的權限。 設定無金鑰驗證,並將搜尋服務參與者角色指派給您的使用者帳戶(建議),或使用管理員 API 金鑰。
最新的
Azure.Search.Documents預覽套件:dotnet add package Azure.Search.Documents --prerelease對於無鑰匙認證,套件如下
Azure.Identity:dotnet add package Azure.IdentityNote
用戶端函式庫必須支援搜尋服務 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-identityNote
用戶端函式庫必須支援搜尋服務 REST API 的
2026-10-01或2026-08-01-preview版本。 早於2026-08-01-preview此之前的版本會忽略本文中所示的篩選器和分頁參數。
搜尋服務 REST API 的 2026-10-01 版本。
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
設定 SDK 範例
設定您的開發環境以執行範例。
將
AZURE_SEARCH_ENDPOINT環境變數設為您的 Foundry IQ 服務端點。 這些範例會讀取此值,以告知用戶端要連線到哪個 Foundry IQ 服務。安裝 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 個。