你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
(Azure AI 搜索 REST API) 添加、更新或删除文档
可以使用 HTTP POST 将 搜索文档导入 指定的索引。 对于大型更新，建议对 (每批最多 1000 个文档进行批处理，或每个批处理) 大约 16 MB，这将显著提高索引编制性能。
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
对于支持的 Azure 数据源， 索引器 提供了一种更简单的替代方法，用于添加和更新文档。 有关详细信息，请参阅 Indexer operations（Indexer 操作）。
URI 参数
| 参数 | 说明 |
|---|---|
| 服务名称 | 必需。 将此设置为搜索服务的唯一用户定义名称。 |
| 索引名称 | URI 上是必需的，指定要发布文档的索引。 一次只能将文档发布到一个索引。 |
| api-version | 必需。 当前稳定版本为 api-version=2020-06-30。 有关更多 版本，请参阅 API 版本。 |
请求标头
下表介绍必需和可选的请求标头。
| 字段 | 说明 |
|---|---|
| Content-Type | 必需。 将其设置为 application/json |
| api-key | 如果使用 Azure 角色 并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。 上传文档需要管理员 API 密钥。 有关详细信息 ，请参阅使用密钥身份验证连接到 Azure AI 搜索 。 |
请求正文
请求的正文包含要编入索引的一个或多个文档。 文档由区分大小写的唯一键标识。 每个文档都与一个操作相关联：“upload”、“delete”、“merge”或“mergeOrUpload”。 上传请求必须包含文档数据作为一组键/值对。
{
"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)
...
},
...
]
}
| 属性 | 说明 |
|---|---|
| @search.action | 必需。 有效值为“upload”、“delete”、“merge”或“mergeOrUpload”。 默认为“upload”。 可以将操作（每个文档一个）合并到同一批中。
“upload”：上传操作类似于“upsert”，在“更新插入”中，如果文档是新的文档，将插入文档，如果文档存在，则会对其进行更新/替换。 在更新案例中，将替换所有字段。 “delete”：删除将从索引中删除指定的文档。 除键字段外，在删除操作中指定的任何字段都将被忽略。 如果要从文档中删除单个字段，请改用 merge ，并将该字段显式设置为 null。
“mergeOrUpload”：如果索引中已存在具有给定键的文档，则此操作的行为类似于 merge。 如果文档不存在，则其行为类似于使用新文档进行上传。 “merge”：Merge 更新具有指定字段的现有文档。 如果文档不存在，合并将失败。 merge 中指定的任何字段都将替换文档中的现有字段。 这也适用于基元和复杂类型的集合。 在基元集合中，如果文档包含值为 [“budget”] 的 Collection (Edm.String) 类型的 Tags 字段，并且对 Tag 执行值为 [“economy”， “pool”] 的合并，则 Tags 字段的最终值为 [“economy”， “pool”]。 而不是 ["budget", "economy", "pool"]。 在复杂集合中，如果文档包含名为 Rooms 的复杂集合字段，其值为 [{ “Type”： “Budget Room”， “BaseRate”： 75.0 }]，并执行值为 [{ “Type”： “Standard Room” }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }]的合并值，“会议室”字段的最终值将为 [{ “Type”： “Standard Room” }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }]。 它不是以下任一类型： [{ “Type”： “Budget Room”， “BaseRate”： 75.0 }， { “Type”： “Standard Room” }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }] (追加元素) [{ “Type”： “Standard Room”， “BaseRate”： 75.0 }， { “Type”： “Budget Room”， “BaseRate”： 60.5 }] (按顺序合并元素，然后追加任何附加) |
| key_field_name | 必需。 用作文档键且仅包含唯一值的索引中的字段定义。 文档键只能包含字母、数字、短划线 () "-" 、下划线 () "_" ，以及 () "=" 和区分大小写的等号。 有关详细信息，请参阅 命名规则。 |
| field_name | 必需。 名称-值对，其中字段的名称对应于索引定义中的字段名称。 该值是用户定义的，但对于字段类型必须有效。 |
注意
没有先执行请求正文中的操作的排序保证。 不建议在单个请求正文中将多个“合并”操作与同一文档相关联。 如果同一文档需要多个“合并”操作，请在更新搜索索引中的文档之前执行合并客户端。
响应
状态代码：成功响应返回 200，这意味着所有项都已持久存储，并开始编制索引。 索引在后台运行，使新文档 (即，在索引操作完成几秒钟后，) 查询和可搜索的文档可用。 具体延迟取决于服务上的负载。
成功编制索引时，所有项目的 status 属性设置为 true，对于新上传的文档) 设置为 201 (，或者对于合并或删除的文档) ，状态属性设置为 200 (：
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
状态代码：如果至少一个项目未成功编制索引，则返回 207。 尚未编制索引的项的状态字段设置为 false。 errorMessage 和 statusCode 属性指示索引错误的原因：
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
errorMessage 属性指示索引错误的原因（如果可能）。
下表介绍了可在响应中返回的各种按文档 状态代码 。 某些状态代码指示请求本身存在问题，而其他状态代码则指示临时错误条件。 对于后者，应在延迟后重试。
| 状态代码 | 含义 | 可重试 | 备注 |
|---|---|---|---|
| 200 | 文档已成功修改或删除。 | N/A | 删除操作是幂等的。 也就是说，即使索引中不存在文档键，尝试使用该键执行删除操作会导致 200 状态代码。 |
| 201 | 已成功创建文档。 | N/A | |
| 400 | 文档中存在阻止其编入索引的错误。 | 否 | 响应中的错误消息指示文档出了问题。 |
| 404 | 无法合并文档，因为索引中不存在给定键。 | 否 | 上载不会发生此错误，因为它们创建新文档，并且不会在删除时发生此错误，因为它们是 幂等的。 |
| 409 | 尝试将文档编入索引时检测到了版本冲突。 | 是 | 尝试将相同文档同时多次编入索引时，可能发生此错误。 |
| 422 | 索引暂时不可用，因为在将“allowIndexDowntime”标志设置为“true”的情况下更新了它。 | 是 | |
| 503 | 搜索服务暂时不可用，可能是因为负荷较重。 | 是 | 在此情况下，代码应在重试前等待，否则面临延长服务不可用性状态的风险。 |
注意
如果客户端代码经常遇到 207 响应，则一个可能的原因是系统过载。 可通过检查 statusCode 属性中的 503 来确定此原因。 如果出现这种情况，我们建议限制索引请求。 否则，如果索引流量不下降，系统可能开始使用 503 错误拒绝所有请求。
状态代码：429 表示已超出每个索引的文档数配额。 必须创建新索引或升级以提高容量限制。
示例
示例：上传两个完全定义的文档
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
注意
将包含时区信息的值上传到 DateTimeOffset 索引时，Azure AI 搜索会将这些值规范化为 UTC。 例如，2019-01-13T14：03：00-08：00 将存储为 2019-01-13T22：03：00Z。 如果需要存储时区信息，则需要向索引添加额外的列。