你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure AI 搜索 REST API 参考
Azure AI 搜索（以前称为 Azure 认知搜索）是一项完全托管的云搜索服务，提供用户拥有的内容的信息检索。
数据平面 REST API 用于索引和查询工作流，并记录在本部分中。
服务管理的控制平面操作在单独的 管理 REST API中介绍。
版本控制 API 文档
REST API 文档现已进行版本控制。 打开 API 参考页时，版本选择器将显示在目录上方。 请确保 API 引用来自 引用 > 数据平面 文件夹。
关键概念
Azure AI 搜索具有 搜索服务的概念、索引、文档、索引器、数据源、技能集以及 同义词映射。
- 搜索服务托管索引、索引器、数据源、技能集和同义词映射作为顶级对象。
- 搜索索引提供搜索文档的持久存储。 搜索文档是你的数据，作为字段的集合，从外部源加载并推送到索引，使其可搜索。
- 搜索索引器添加自动化、以本机格式读取数据并将其序列化为 JSON。
- 索引器具有数据源并指向索引。
- 索引器可能还有一个技能集，用于向索引管道添加 AI 扩充 和 集成矢量 化。 技能集始终附加到索引器。 它们调用机器学习来提取或区块文本、向量化内容、推断功能或向内容添加结构，以便通过搜索服务改进索引。
完全可以在搜索服务上创建以下对象：
| 对象 | 描述 |
|---|---|
| 数据源 | 索引器用于检索和刷新用于编制索引的文档的数据源连接。 数据源具有 type。 可以使用 Azure 或合作伙伴连接器Microsoft提供的连接。 有关完整列表，请参阅 数据源库。 |
| 文件 | 从概念上讲，文档是索引中的实体。 将此概念映射到更熟悉的数据库等效项：搜索索引等同于表，文档大致相当于表中的行。 文档仅存在于索引中，并且仅通过针对索引的文档集合（/docs）的查询进行检索。 对集合执行的所有操作（如上传、合并、删除或查询文档）都发生在单个索引的上下文中，因此 URL 格式文档操作始终包括给定索引名称的 /indexes/[index name]/docs。 |
| 指标 | 索引存储在搜索服务上，并使用索引和标记化的 JSON 文档进行填充，以便进行信息检索。 索引的字段集合定义搜索文档的结构。 字段具有确定使用情况的名称、数据类型和属性。 例如，searchable 字段用于全文搜索，从而在索引期间进行标记。 索引还定义了其他构造，例如用于相关性优化、建议器、语义配置和自定义分析器的计分配置文件。 |
| 索引 | 索引器提供索引自动化。 索引器连接到数据源，读取数据，并将其传递给搜索引擎，以便索引到目标搜索索引。 索引器使用数据源中的连接信息从外部源读取，并将传入数据序列化为 JSON 搜索文档。 除了数据源，索引器还需要索引。 索引指定搜索文档的字段和属性。 |
| 技能集 | 技能组将外部处理步骤添加到索引器执行，并用于应用 AI 或深度学习模型来分析或转换内容，以提高索引中的可搜索性。 技能集的内容是一个或多个 技能，可以 由Microsoft、自定义技能或两者的组合创建的内置技能。 存在用于图像分析的内置技能，包括 OCR 和自然语言处理。 其他内置技能示例包括实体识别、关键短语提取、将文本分块到逻辑页等。 技能集是高级独立对象，它存在于与索引、索引器和数据源等效的级别上，但它仅在索引器处理中运行。 作为高级对象，可以设计一次技能集，然后在多个索引器中引用它。 |
| 同义词映射 | 同义词映射是包含用户定义的同义词的服务级别对象。 此对象独立于搜索索引进行维护。 上传后，可以将任何可搜索字段指向同义词映射（每个字段一个）。 |
权限和访问控制
可以通过Microsoft Entra ID 使用基于密钥的身份验证或基于角色的身份验证。
基于密钥的身份验证 依赖于为搜索服务生成的 API 密钥。 在发送请求和处理请求的服务之间，让有效的密钥根据每个请求建立信任。 可以使用 管理 API 密钥 进行读写操作，也可以使用 查询 API 密钥 来读取搜索索引的文档集合。
Microsoft Entra ID 身份验证和基于角色的访问控制 要求你在具有安全主体和角色分配的 Microsoft Entra ID 中有一个已建立的租户。 以下角色的成员具有数据平面访问权限。 如果内置角色不足，则可以创建自定义角色。
角色 访问 搜索服务参与者 对对象的访问，但无权访问索引内容。 此角色创建搜索索引和其他顶级对象，但无法查询搜索索引或添加、删除或更新搜索索引中的文档。 此角色适用于创建、更新和删除对象定义的开发人员。 它还适用于需要管理对象的管理员，但无法查看或访问对象数据。 搜索数据索引参与者 对索引内容的读写访问权限。 此角色适用于需要导入、刷新或查询索引的文档集合的开发人员或索引所有者。 搜索数据索引读取器 对索引内容的读取访问权限。 此角色适用于运行查询的应用和用户。
在连接上使用角色时，客户端应用在授权标头中显示持有者令牌。 请参阅 使用 Microsoft Entra ID 授权访问搜索应用，获取有关设置此功能的帮助。
可以禁用基于密钥的身份验证或基于角色的身份验证。 如果禁用基于角色的身份验证，则它仅适用于数据平面操作。 控制平面操作（如服务管理）始终使用基于角色的身份验证。 有关详细信息，请参阅 azure AI 搜索
调用 API
本节中记录的 API 提供对搜索数据的操作（如索引创建和填充、文档上传和查询）的访问权限。 调用 API 时，请记住以下几点：
必须通过 HTTPS（在默认端口 443 上）发出请求。
请求 URI 必须包含 api 版本。 该值必须设置为受支持的版本，格式如下例所示：
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01请求标头 必须包括 api 密钥 或经过身份验证的连接持有者令牌。 （可选）可以设置 Accept HTTP 标头。 如果未设置内容类型标头，则假定默认为
application/json。