你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
添加、更新或删除文档（预览版 REST API）
适用于：2023-07-01-Preview。 此版本不再受支持。 将立即升级到较新版本。
重要
2023-07-01-Preview 添加：
- 支持文档中的矢量字段。
可以使用 HTTP POST 将包含矢量字段的文档推送到指定的索引中。 对于大型更新，批处理（每个批最多 1000 个文档或每批大约 16 MB）可提高索引性能。
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
URI 参数
| 参数 | 描述 |
|---|---|
| 服务名称 | 必填。 将此值设置为搜索服务的唯一用户定义的名称。 |
| 索引名称 | 必填。 将此值设置为接收文档的索引的名称。 一次只能将文档发布到一个索引。 |
| api-version | 有关更多版本，请参阅 API 版本。 |
请求标头
下表描述了必需的和可选的请求标头。
| 领域 | 描述 |
|---|---|
| Content-Type | 必填。 将此值设置为 application/json |
| api-key | 如果使用 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是唯一的系统生成的字符串，用于对搜索服务的请求进行身份验证。 上传文档需要管理员 API 密钥。 有关详细信息，请参阅 使用密钥身份验证 连接到 Azure AI 搜索。 |
请求正文
请求的正文包含要编制索引的一个或多个文档。 文档通过区分大小写的键进行唯一标识。 每个文档都与操作相关联：“upload”、“delete”、“merge”或“mergeOrUpload”。 上传请求必须包含文档数据作为一组键/值对。
矢量字段的类型为 Collection(Edm.Single)。 矢量数据由单精度浮点数数组组成。
矢量字段可以包含数千个嵌入内容，具体取决于原始内容的复杂性、长度或类型。 Azure AI 搜索不会将内容转换为嵌入内容。 推送到索引的文档必须包含之前生成的嵌入内容。
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| 财产 | 描述 |
|---|---|
| @search.action | 必填。 有效值为“upload”、“delete”、“merge”或“mergeOrUpload”。 默认值为“upload”。 |
| key_field_name | 必填。 索引中的字段定义，用作文档键，并且仅包含唯一值。 文档键只能包含字母、数字、短划线（"-"）、下划线（"_"）和等号（"="），并且区分大小写。 |
| field_name | 必填。 名称值对，其中字段的名称与索引定义中的字段名称相对应。 该值是用户定义的，但必须对字段类型有效。 |
响应
状态代码：为成功的响应返回 200，这意味着所有项都已持久存储，并且索引已开始。 索引在后台运行，并在索引操作完成后几秒钟内提供新的文档（即可查询和可搜索）。
当所有项的状态属性设置为 true 时，指示成功编制索引。 statusCode 属性应为 201（对于新上传的文档）或 200（对于合并或删除的文档）。
例子
示例：上传两个包含文本和矢量内容的文档
为了提高可读性，以下示例显示了文档和嵌入的子集。 上传文档请求的正文由 108 个文档组成，每个文档都有一组完整的嵌入“titleVector”和“contentVector”。
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
注意
将具有时区信息的 DateTimeOffset 值上传到索引时，Azure AI 搜索将这些值规范化为 UTC。 例如，2019-01-13T14：03：00-08：00 将存储为 2019-01-13T22：03：00Z。 如果需要存储时区信息，请将额外的列添加到索引中。