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

Azure AI 搜索 REST API 参考

  • 项目

Azure AI 搜索 (以前称为 Azure 认知搜索) 是一种完全托管的云搜索服务，可基于用户拥有的内容检索信息。

数据平面 REST API 用于索引和查询工作流，本部分介绍了这些 API。

可以通过单独的 管理 REST API 访问控制平面操作。

版本控制 API 文档

REST API 文档现已进行版本控制。 打开 API 参考页时，目录上方会显示版本选择器。 确保 API 引用来自“ 引用 > 数据平面 ”文件夹。

版本选择器的屏幕截图。

关键概念

Azure AI 搜索具有搜索服务、索引、文档、索引器、数据源、技能集和同义词映射的概念。

  • 搜索服务将索引、索引器、数据源、技能组和同义词映射作为顶级对象托管。
  • 搜索索引提供搜索文档的持久存储。 搜索文档是你的数据，以字段集合的形式表述，从外部源加载并推送到索引，使其可搜索。
  • 搜索索引器添加了自动化功能，以本机格式读取数据并将其序列化为 JSON。
  • 索引器具有数据源并指向索引。
  • 索引器可能还具有向索引管道添加 AI 扩充 和 集成矢量化的 技能集。 技能集始终附加到索引器。 它们调用机器学习来提取或分块文本、矢量化内容、推理特征或向内容添加结构，以便搜索服务可对其进行索引。

总之，可以在搜索服务上创建以下对象：

对象 说明
数据源 索引器用于检索和刷新文档以编制索引的数据源连接。 数据源具有 type。 可以通过合作伙伴为 Azure 或第三方连接器使用 Microsoft 提供的连接。 有关完整列表 ，请参阅数据源库 。
文档 从概念上讲，文档是索引中的实体。 将此概念映射到更熟悉的数据库等效项：搜索索引等同于表，文档大致等效于表中的行。 文档仅存在于索引中，并且只能通过以索引) (/docs 文档集合为目标的查询进行检索。 对集合执行的所有操作（例如上传、合并、删除或查询文档）都发生在单个索引的上下文中，因此 URL 格式文档操作将始终包括 /indexes/[index name]/docs 给定索引名称。
索引 索引存储在搜索服务上，并填充了为信息检索编制索引和标记化的 JSON 文档。 索引的 fields 集合定义搜索文档的结构。 字段具有确定其使用方式的名称、数据类型和属性。 例如， searchable 字段用于全文搜索，因此在索引编制期间进行标记化。 索引还定义其他构造，例如相关性优化、建议器、语义配置和自定义分析器的评分配置文件。
索引器 索引器提供索引自动化。 索引器连接到数据源，读取数据，并将其传递给搜索引擎，以便将索引编制到目标搜索索引中。 索引器使用数据源中的连接信息从外部源读取，并将传入数据序列化为 JSON 搜索文档。 除了数据源，索引器还需要索引。 索引指定搜索文档的字段和属性。
技能集 技能组将外部处理步骤添加到索引器执行，通常用于添加 AI 或深度学习模型以分析或转换内容，使其可在索引中搜索。 技能集的内容是一个或多个 技能，可以是 Microsoft 创建的 内置技能 、自定义技能或两者的组合。 存在用于图像分析的内置技能，包括 OCR 和自然语言处理。 内置技能的其他示例包括实体识别、关键短语提取、将文本分块成逻辑页等。 技能组是高级独立对象，存在于与索引、索引器和数据源等效的级别上，但它仅在索引器处理中运行。 作为高级对象，可以设计技能组一次，然后在多个索引器中引用它。
同义词映射 同义词映射是包含用户定义的同义词的服务级别对象。 此对象独立于搜索索引进行维护。 上传后，可以将任何可搜索字段指向同义词映射， (每个字段) 一个。

权限和访问控制

可以通过Microsoft Entra ID使用基于密钥的身份验证或基于角色的身份验证。

  • 基于密钥的身份验证 依赖于为搜索服务生成的 API 密钥。 具有有效的密钥可以在发送请求的应用程序与处理请求的服务之间建立信任关系，这种信任关系以每个请求为基础。 可以使用 管理员 API 密钥执行读写操作，或使用查询 API 密钥读取搜索索引的文档集合。

  • Microsoft Entra ID身份验证和基于角色的访问控制要求在Microsoft Entra ID中具有已建立的租户，并具有安全主体和角色分配。 以下角色的成员具有数据平面访问权限。 如果内置角色不足，可以创建自定义角色。

    角色 Access
    搜索服务参与者 访问对象，但无法访问索引内容。 此角色无法查询搜索索引或添加、删除或更新搜索索引中的文档。 此角色适用于需要管理对象但无法查看或访问对象数据的管理员。
    搜索数据索引参与者 对索引内容的读写访问。 此角色适用于需要导入、刷新或查询索引文档集合的开发人员或索引所有者。
    搜索数据索引读取器 对索引内容的读取访问权限。 此角色适用于运行查询的应用和用户。

在连接上使用角色时，客户端应用在授权标头中显示持有者令牌。 有关设置此功能的帮助，请参阅使用 Microsoft Entra ID 授权访问搜索应用。

可以禁用基于密钥的身份验证或基于角色的身份验证。 如果禁用基于角色的身份验证，则某些内置角色仍具有访问权限。 有关详细信息，请参阅 azure AI 搜索 Microsoft Entra ID身份验证和基于角色的访问控制。

调用 API

本部分介绍的 API 可让你访问对搜索数据执行的操作，例如，创建和填充索引、上载文档和查询。 调用 API 时，请记住以下几点：

  • 必须在默认端口 443) 上通过 HTTPS (发出请求。

  • 请求 URI 必须包含 api 版本。 值必须设置为受支持的版本，格式如下例所示： GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • 请求标头 必须包含用于经过身份验证的连接的 API 密钥 或持有者令牌。 （可选）可以设置 Accept HTTP 标头。 如果未设置内容类型标头，则假定默认值为 application/json。

另请参阅