ASP.NET Core构建Cosmos DB REST API时GetItemById分区键报错

这个问题我之前做Cosmos DB项目时也踩过坑——核心原因很明确：你的容器已经配置了分区键，但调用GetItemByIdAsync（或者它底层的GetItemAsync）时，没有传入对应的分区键值，导致Cosmos DB无法定位到正确的分区，所以抛出了Microsoft.Azure.Documents.DocumentClientException这个错误。

下面给你一步步的解决方案：

1. 先明确你的容器分区键配置 #

先确认你的Cosmos DB容器的分区键路径，比如是/userId、/category还是其他字段。假设你的Todo实体的分区键是/userId（你可以替换成自己实际的分区键路径）。

2. 修改GetByIdAsync方法，显式传入分区键 #

你原来的调用大概率是没传分区键的，类似这样：

public async Task<Todo> GetByIdAsync(string id)
{
    var response = await _container.GetItemAsync<Todo>(id);
    return response.Resource;
}

这种写法在无分区的容器里没问题，但分区容器必须指定分区键。这里有两种可行的修改方案：

方案一：从URL路由传递分区键 #

调整你的API URL，把分区键也包含进来，比如改成http://localhost:54084/api/todo/{userId}/{id}，然后修改控制器方法：

[HttpGet("{userId}/{id}")]
public async Task<IActionResult> GetTodo(string userId, string id)
{
    var todo = await _todoService.GetByIdAsync(id, userId);
    return Ok(todo);
}

对应的Service层方法也要更新，传入分区键并生成PartitionKey对象：

public async Task<Todo> GetByIdAsync(string id, string partitionKey)
{
    var partitionKeyValue = new PartitionKey(partitionKey);
    var response = await _container.GetItemAsync<Todo>(id, partitionKeyValue);
    return response.Resource;
}

方案二：如果分区键是实体的固有属性（谨慎使用） #

如果你的Todo实体本身就带分区键属性（比如public string UserId { get; set; }），但这里要注意：你还是需要提前知道分区键值才能查询，因为GetItemByIdAsync必须依赖分区键定位分区。如果是这种情况，你可以从业务逻辑中获取分区键值再传入，和方案一本质是一样的。

3. 避坑注意事项 #

• 别被“id唯一”误导：在分区容器中，id只在同一个分区内唯一，不同分区可以有相同的id，所以必须指定分区键才能精准找到目标文档。
• 匹配分区键类型：如果你的分区键是数字、布尔值等非字符串类型，要确保传入的PartitionKey类型和容器定义一致，别把数字当成字符串传。
• 核对分区键路径：比如容器设置的分区键是/partitionKey，那你的实体对应的属性名（或序列化后的字段名）必须是PartitionKey，否则Cosmos DB无法识别。

4. 优化错误处理（可选） #

可以在代码中捕获这个异常，返回更友好的API响应：

public async Task<Todo> GetByIdAsync(string id, string partitionKey)
{
    try
    {
        var partitionKeyValue = new PartitionKey(partitionKey);
        var response = await _container.GetItemAsync<Todo>(id, partitionKeyValue);
        return response.Resource;
    }
    catch (DocumentClientException ex) when (ex.StatusCode == HttpStatusCode.BadRequest)
    {
        // 记录日志，抛出业务异常或返回null
        throw new InvalidOperationException("分区键不匹配或未提供，请检查请求参数", ex);
    }
}

按照上面的方法修改后，你的GetItemByIdAsync调用就能正确定位分区，不会再出现那个错误了。

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