你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
本文介绍如何将文档导入预定义的搜索索引。 在 Azure AI 搜索中，先创建搜索索引，接着的第二步是导入数据。 例外情况是 Azure 门户和索引器管道中的导入向导，该向导在一个工作流中创建和加载索引。
数据导入的工作原理
搜索服务接受符合索引架构的 JSON 文档。 搜索服务可以在 JSON 文档中导入和索引纯文本内容和矢量内容。
纯文本内容通过从外部数据源的字段、元数据属性或由技能集生成的丰富内容中获取。 技能可以从图像和非结构化内容中提取或推断文本说明。
矢量内容从提供它的数据源中检索，或者由在 Azure AI 搜索索引器工作负载中实现集成矢量化的技能集创建。
你可自行准备这些文档，但是如果内容驻留在支持的数据源中，那么运行索引器或使用导入向导可自动完成文档检索、JSON 序列化和索引。
索引数据后，索引的物理数据结构将被锁定。 有关可更改和不可更改的内容的指南，请参阅更新并重新生成索引。
索引不是一个后台进程。 搜索服务平衡索引编制和查询工作负荷，但如果 查询延迟过高，可以 添加容量 或识别用于加载索引的低查询活动的时间段。
有关详细信息，请参阅数据导入策略。
使用 Azure 门户
在 Azure 门户中，使用 导入向导 在无缝工作流中创建和加载索引。 如果要加载现有索引，请选择替代方法。
在 “概述 ”页上，选择命令栏上的 “导入数据 ”或 “导入数据”（新）， 以创建和填充搜索索引。
可以点击以下链接查看工作流：快速入门：创建 Azure AI 搜索索引和快速入门：集成矢量化。
向导完成后，使用搜索资源管理器检查结果。
提示
导入向导会创建并运行索引器。 如果已定义索引器，则可以从 Azure 门户重置并运行索引器，这在以增量方式添加字段时非常有用。 重置会迫使索引器重头开始，从所有源文档中选取所有字段。
使用 REST API
文档 - 索引是用于将数据导入搜索索引的 REST API。
请求的正文包含要编入索引的一个或多个文档。 通过区分大小写的键对文档进行唯一标识。 每个文档都与一个动作相关联：“上传”、“删除”、“合并”或“合并或上传”。 上传请求必须包含文档数据作为一组键/值对。
REST API 适用于初始概念验证测试，可以在其中测试索引工作流，而无需编写大量代码。
@search.action 参数根据特定字段的新值或替换值确定是部分还是全部添加文档。
快速入门：使用 REST 进行全文搜索 介绍了这些步骤。 下面的示例是修改后的示例版本。 为简洁起见，对该值进行了剪裁，并更改了第一个 HotelId 值，以避免覆盖现有文档。
构建一个 POST 调用，用于指定索引名称、“docs/index”终结点，以及一个包含
@search.action参数的请求正文。POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2025-09-01 Content-Type: application/json api-key: [admin key] { "value": [ { "@search.action": "upload", "HotelId": "1111", "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ] }, { "@search.action": "mergeOrUpload", "HotelId": "2", "HotelName": "Old Century Hotel", "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ] } ] }将
@search.action参数设置为upload以创建或覆盖文档。 如果要更新文档中的特定字段，请将其设置为merge或uploadOrMerge。 上一个示例显示了这两个操作。操作 效果 上传 类似于“upsert”，如果文档是新文档，则插入；如果文档已经存在，则进行更新或替换。 如果文档缺少索引所需的值，则将文档字段的值设置为 null。 合并 更新已有的文档，如果找不到该文档，则会失败。 合并将替换现有值。 因此，请务必检查是否有包含多个值的集合字段，例如类型为 Collection(Edm.String)的字段。 例如，如果tags字段以["budget"]值开头，并且你执行与["economy", "pool"]的合并，则tags字段的最终值为["economy", "pool"]。 不是["budget", "economy", "pool"]。合并或上传 如果文档已存在，则行为类似于合并；如果文档是新的，则类似于上传。 这是增量更新的最常见操作。 删除 删除从索引中删除指定的文档。 在删除作中指定的任何字段（键字段以外的任何字段）将被忽略。 如果要从文档中移除单个字段，请改用 merge 并将该字段显式设置为 null。 对于首先执行请求正文中的哪项操作并未提供排序保证。 不建议在单个请求正文中将多个“merge”操作与同一文档关联。 如果同一文档需要多个“merge”操作，请先在客户端执行合并操作，然后再更新搜索索引中的文档。
在基元集合中，如果文档包含值为 ["budget"] 的类型“
Collection(Edm.String)”的 Tags 字段，并且对其执行值为 ["economy", "pool"] 的合并，则 Tags 字段的最终值为 ["economy", "pool"]。 它不是 ["budget", "economy", "pool"]。在复杂集合中，如果文档包含名为 Rooms 的复杂集合类型的字段，其值为 [{“Type”: “Budget Room”, “BaseRate”: 75.0}]，并合并值为 [{“Type”: “Standard Room”}, {“Type”: “Budget Room”, “BaseRate”: 60.5}]，那么 Rooms 字段的最终值将为 [{“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 }]（按顺序合并元素，然后追加任何额外内容）
注释
将包含时区信息的 DateTimeOffset 值上传到索引时，Azure AI 搜索将这些值规范化为 UTC。 例如，2025-01-13T14：03：00-08：00 将存储为 2025-01-13T22：03：00Z。 如果需要存储时区信息，请将额外的列添加到索引中。
发送请求。
下表说明了可在响应中返回的各种每文档 状态代码 。 某些状态代码会指示请求本身的问题，而另一些代码会指示临时错误条件。 对于后者，应在延迟后重试。
状态代码 Meaning 可重试 注释 200 文档已成功修改或删除。 n/a 删除操作是幂等的。 也就是说，即使索引中不存在某个文档键，使用该键尝试执行删除操作也会生成 200 状态代码。 201 已成功创建文档。 n/a 400 文档中存在阻止其编入索引的错误。 否 响应中的错误消息指示文档存在的问题。 404 文档无法合并，因为索引中不存在给定键。 否 上传不会发生此错误，因为上传会创建新文档；删除不会发生此错误，因为删除是幂等的。 409 尝试将文档编入索引时检测到了版本冲突。 是的 尝试将相同文档同时多次编入索引时，可能发生此错误。 422 索引暂时不可用，因为在将“allowIndexDowntime”标志设置为“true”的情况下更新了它。 是的 429 表明您已超出了每个索引可用的文档数量配额。 否 必须创建新的索引或升级以提高容量限制。 503 搜索服务暂时不可用，可能是因为负荷较重。 是的 在此情况下，代码应在重试前等待，否则面临延长服务不可用性状态的风险。 注释
如果客户端代码经常遇到 207 响应，则一个可能的原因是系统过载。 可以通过检查
statusCode503 的属性来确认这一点。 如果是这种情况，我们建议限制索引请求。 否则，如果索引流量不下降，系统可能开始使用 503 错误拒绝所有请求。查找你刚才添加为验证步骤的文档：
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01
当文档键或 ID 为新时， null 将成为文档中未指定的任何字段的值。 对于现有文档上的操作，更新后的值将替换之前的值。 “merge”或“mergeUpload”未指定的任何字段都在搜索索引中保持不变。
使用 Azure SDK
以下 Azure SDK 中提供了可编程性。
Azure SDK for .NET 提供以下 API，用于将简单和批量文档上传到索引中：
有几个示例来阐释简单和大规模索引上下文中的索引：