逐頁瀏覽 Azure AI 搜尋服務 清單結果（預覽）

Note

Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務 預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

從 REST API 開始 2026-08-01-preview ，使用游標分頁（預覽版）逐頁列舉支援的服務資源。 當有更多結果可用時，服務會回傳一個不透明的續頁網址。

本文說明游標合約，並示範如何瀏覽現有索引。

先決條件

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

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

    Note

    用戶端函式庫必須支援 2026-08-01-preview 搜尋服務 REST API 的版本。 早期版本並未揭露本文中所示的游標參數。

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

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

    Note

    用戶端函式庫必須支援 2026-08-01-preview 搜尋服務 REST API 的版本。 早期版本並未揭露本文中所示的游標參數。

選擇列表操作

2026-08-01-preview游標合約適用於以下列表操作：

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

要求並逐頁存取

以下範例列出名稱以 hotels 開頭的索引，並要求每頁最多 50 個索引。 對 AsyncPageable<SearchIndex> 結果進行迭代時，系統會自動請求後續各頁。

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 AzureCliCredential(),
    options);

AsyncPageable<SearchIndex> indexes = client.GetIndexesAsync(
    search: "hotels",
    pageSize: 50,
    searchType: ListingSearchType.Prefix);

await foreach (SearchIndex index in indexes)
{
    Console.WriteLine(index.Name);
}

參考資料：SearchIndexClient.GetIndexesAsync

以下範例列出名稱以 hotels 開頭的索引，並要求每頁最多 50 個索引。 對 ItemPaged 結果進行迭代時，系統會自動請求後續各頁。

import os

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

endpoint = os.getenv("AZURE_SEARCH_ENDPOINT")

with SearchIndexClient(
    endpoint,
    AzureCliCredential(),
    api_version="2026-08-01-preview",
) as client:
    indexes = client.list_indexes(
        select=["name"],
        search="hotels",
        page_size=50,
        search_type="prefix",
    )
    for index in indexes:
        print(index.name)

參考資料：SearchIndexClient.list_indexes

發送初始請求，列出名稱以 hotels為開頭的索引。 請求最多回傳 50 個索引名稱：

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

參考資料：列表索引

當存在超過 50 個匹配索引時，回應會包含 @odata.nextLink，其中包含完整的續集 URL 及一個不透明的標記。 以下回應為簡短說明：

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

若要請求下一頁，請使用傳回的完整 @odata.nextLink 值原樣傳送 GET 要求。 保持相同的認證標頭：

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

參考資料：列表索引

終端回應包含最終索引名稱並省略 @odata.nextLink，表示沒有更多頁面可用。 結果順序不包含在游標合約中：

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

控制游標行為

  • 尋找最後一頁： 僅在回應包含 @odata.nextLink時繼續分頁。 終端頁面省略了此特性，回應也未包含 @odata.count。

  • 保留接續狀態：完全依照傳回的內容使用完整的 @odata.nextLink。 不要建構、修改、解碼或重複使用其 $skiptoken。 權杖僅支援向前分頁。

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

  • 將集合變更納入考量： 只有在集合維持不變的情況下，向前分頁才是穩定的。 在列舉過程中新增、更新或刪除資源可能會導致重複或遺漏結果。

相關內容

  • Last updated on