求向Azure Cognitive Search索引推送JSON文档的C#实现代码及操作指引

没问题！我刚好在用Azure.Search.Documents这套命名空间做搜索索引的写入操作，给你整理了完整的实现步骤和代码示例，完全贴合你的需求：

第一步：准备工作 #

首先确保你已经安装了对应的NuGet包：

Install-Package Azure.Search.Documents

然后从Azure Portal获取三个关键信息：

• 你的Azure Cognitive Search服务Endpoint（格式类似https://xxx.search.windows.net）
• 服务的Admin Key（注意要用Admin Key，Query Key只有查询权限，没有写入权限）
• 目标索引的名称

第二步：定义索引对应的实体类 #

你需要创建一个C#类来映射索引的字段，用Azure.Search.Documents.Indexes里的属性来标注字段特性（比如主键、可搜索、可过滤等），示例如下：

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

// 类名可以自定义，字段要和你的索引字段对应
public class MySearchDocument
{
    // 标记为主键，对应索引里的主键字段
    [SimpleField(IsKey = true, IsFilterable = true)]
    public string Id { get; set; }

    // 可搜索、可排序的标题字段
    [SearchableField(IsSortable = true)]
    public string Title { get; set; }

    // 可搜索的内容字段，如果索引里的字段名和类属性名不一致，可以用Name指定
    [SearchableField(Name = "document_content")]
    public string Content { get; set; }

    // 这里添加你索引里的其他字段，比如日期、标签等
}

第三步：单条记录推送 #

通过SearchClient的UploadDocumentsAsync方法实现单条文档的插入（如果ID已存在会自动更新，也就是Upsert操作）：

using Azure;
using Azure.Search.Documents;
using System.Threading.Tasks;

public async Task PushSingleDocument()
{
    // 替换成你的信息
    string searchEndpoint = "https://your-search-service.search.windows.net";
    string adminKey = "your-admin-key";
    string indexName = "your-index-name";

    // 初始化SearchClient
    SearchClient searchClient = new SearchClient(
        new Uri(searchEndpoint),
        indexName,
        new AzureKeyCredential(adminKey));

    // 创建要推送的文档
    var newDoc = new MySearchDocument
    {
        Id = "unique-doc-id-001",
        Title = "我的第一条测试文档",
        Content = "这是文档的具体内容，会被Azure Search索引"
    };

    try
    {
        // 推送单条文档
        var response = await searchClient.UploadDocumentsAsync(new[] { newDoc });
        // 输出处理结果
        Console.WriteLine($"单条文档推送成功，状态码：{response.Value.Results[0].StatusCode}");
    }
    catch (RequestFailedException ex)
    {
        // 捕获Azure服务端错误
        Console.WriteLine($"推送失败：{ex.Message}，错误代码：{ex.Status}");
    }
}

第四步：多条记录批量推送 #

批量推送只需要传入文档列表即可，同样支持Upsert：

public async Task PushMultipleDocuments()
{
    string searchEndpoint = "https://your-search-service.search.windows.net";
    string adminKey = "your-admin-key";
    string indexName = "your-index-name";

    SearchClient searchClient = new SearchClient(
        new Uri(searchEndpoint),
        indexName,
        new AzureKeyCredential(adminKey));

    // 构造批量文档
    var docsToPush = new List<MySearchDocument>
    {
        new MySearchDocument { Id = "doc-002", Title = "批量文档1", Content = "批量内容1" },
        new MySearchDocument { Id = "doc-003", Title = "批量文档2", Content = "批量内容2" },
        new MySearchDocument { Id = "doc-004", Title = "批量文档3", Content = "批量内容3" }
    };

    try
    {
        var response = await searchClient.UploadDocumentsAsync(docsToPush);
        // 遍历每条文档的处理结果
        foreach (var result in response.Value.Results)
        {
            Console.WriteLine($"文档{result.Key}处理状态：{result.StatusCode}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"批量推送失败：{ex.Message}，错误代码：{ex.Status}");
    }
}

额外说明：严格插入（避免更新现有文档） #

如果你想确保只插入全新的文档（ID不存在时才插入，存在则报错），可以先查询该ID是否存在，或者使用IndexDocumentsAsync并结合错误处理：

// 构造仅插入的操作（如果ID存在会返回Conflict错误）
var insertAction = new IndexDocumentsAction<MySearchDocument>(IndexActionType.Upload, newDoc);
var response = await searchClient.IndexDocumentsAsync(new[] { insertAction });

注意：IndexActionType.Upload本质还是Upsert，如果要严格限制插入，需要在代码里先执行一次查询，确认ID不存在后再推送。

关键注意事项 #

• 字段映射要准确：如果索引字段名和类属性名不一致，一定要用SearchableField或SimpleField的Name参数指定，或者用JsonPropertyName属性。
• 批量大小限制：Azure Search单批请求最多支持1000个文档或100MB数据，大量文档建议分批次处理。
• 权限验证：必须使用Admin Key，Query Key没有写入索引的权限。

内容的提问来源于stack exchange，提问作者Adam Dee