Azure CosmosDB调用ReplaceItemAsync报404，Upsert无数据变更问题

问题原因分析 #

1. ReplaceItemAsync返回404错误 #

Cosmos DB的ReplaceItemAsync操作需要同时指定文档ID和分区键才能精准定位文档。原代码仅传递了item.id，未传入分区键参数，导致Cosmos无法在正确分区中找到目标文档，返回404 NotFound错误。

2. UpsertItemAsync无报错但属性未更新 #

• 未指定分区键时，Upsert可能无法匹配现有文档，转而插入新文档（若新文档与原文档不在同一分区，会出现属性无变更的假象）；
• 实体类ActionItem的属性序列化配置错误，比如Executed或id未正确映射到Cosmos DB中的字段，导致修改后的属性无法被序列化存储。

解决方案 #

1. 修复ReplaceItemAsync调用 #

调用ReplaceItemAsync时必须传入分区键参数（你的容器分区键为TransferId）：

public async Task UpdateActionAsync(ActionItem item)
{
    // 补充分区键参数，确保Cosmos定位到目标分区的文档
    await _transfer.ReplaceItemAsync<ActionItem>(item, item.id, new PartitionKey(item.TransferId));
}

2. 确保实体类属性映射正确 #

检查ActionItem类的序列化配置，确保字段名与Cosmos DB文档字段完全匹配（以System.Text.Json为例，Newtonsoft.Json配置逻辑类似）：

using System.Text.Json.Serialization;

public class ActionItem
{
    // 必须映射到Cosmos的"id"字段
    [JsonPropertyName("id")]
    public string id { get; set; }

    // 映射到分区键字段TransferId
    [JsonPropertyName("TransferId")]
    public string TransferId { get; set; }

    // 确保Executed字段可被正确序列化
    [JsonPropertyName("Executed")]
    public bool Executed { get; set; }

    // 其他业务属性...
}

3. 修复UpsertItemAsync调用（如需使用） #

若偏好使用Upsert，同样需要指定分区键，确保操作目标为现有文档而非插入新文档：

public async Task UpdateActionAsync(ActionItem item)
{
    await _transfer.UpsertItemAsync<ActionItem>(item, new PartitionKey(item.TransferId));
}

额外排查点 #

• 确认Cosmos DB容器的分区键确实配置为/TransferId，分区键配置错误会导致所有分区相关操作失效；
• 查看Cosmos DB操作日志（Azure门户容器的「数据资源管理器-操作日志」），确认Upsert/Replace操作是更新现有文档还是插入新文档，辅助定位问题。

内容的提问来源于stack exchange，提问作者Marcel W.