你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

逐页浏览 Azure AI 搜索 列表结果（预览版）

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

在 2026-08-01-preview REST API 中，使用游标分页（预览版）逐页列出受支持的服务资源。 当有更多结果可用时，服务将返回不透明的延续 URL。

本文介绍游标约定，并演示如何对现有索引进行分页浏览。

先决条件

  • 最新的 Azure.Search.Documents 预览包：dotnet add package Azure.Search.Documents --prerelease

  • 对于无密钥身份验证，请使用 Azure.Identity 软件包：dotnet add package Azure.Identity

    注释

    客户端库必须支持 2026-08-01-preview 搜索服务 REST API 的版本。 早期版本不公开本文所示的游标参数。

  • 最新的 azure-search-documents 预览包：pip install --pre azure-search-documents

  • 对于无密钥身份验证，请使用 azure-identity 软件包：pip install azure-identity

    注释

    客户端库必须支持 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);
}

Reference：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)

Reference：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

Reference：List Indexes

如果有超过 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

Reference：List Indexes

终端响应包含最终索引名称和省略 @odata.nextLink，指示没有更多页面可用。 结果顺序不是游标协定的一部分：

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

处理游标行为

  • 判断是否为最后一页： 仅当响应中包含 @odata.nextLink 时才继续分页。 终端页面省略了此属性，且响应中不包含 @odata.count。

  • 保留延续状态： 严格按返回内容原样使用完整的 @odata.nextLink。 不要构造、修改、解码或重用其 $skiptoken。 该令牌仅支持向前分页。

  • 更改请求参数： 启动新的初始请求，以更改资源路径、API 版本、搜索前缀、所选属性或页面大小。 结合$skiptokensearch或pageSize返回 HTTP 400。

  • 考虑集合变化： 仅当集合保持不变时，正向分页才稳定。 在枚举期间添加、更新或删除资源可能会产生重复或省略的结果。

相关内容

  • Last updated on