使用PowerShell调用Azure Cosmos DB API遇分区键错误如何解决？

你的容器属于预分区时代创建的无分区键容器，迁移后Azure后台自动关联了虚拟的/_partitionKey分区键，但实际文档无此字段，此时调用API需避开分区键头的强制校验，以下是具体操作方案：

1. 读取文档（GET请求） #

读取单文档 #

直接通过文档ID的完整路径调用，无需指定任何分区键头：

$cosmosEndpoint = "https://your-account.documents.azure.com:443/"
$cosmosKey = "your-primary-key"
$databaseId = "your-db"
$containerId = "your-container"
$documentId = "target-doc-id"

$headers = @{
    "Authorization" = "type=master&ver=1.0&sig=$cosmosKey"
    "x-ms-date" = (Get-Date).ToUniversalTime().ToString("r")
    "x-ms-version" = "2021-05-15" # 使用兼容的API版本
}

$uri = "$cosmosEndpoint/dbs/$databaseId/colls/$containerId/docs/$documentId"

Invoke-RestMethod -Uri $uri -Headers $headers -Method Get

查询全量文档 #

需添加跨分区查询头，无需分区键参数：

$queryUri = "$cosmosEndpoint/dbs/$databaseId/colls/$containerId/docs"
$queryHeaders = $headers.Clone()
$queryHeaders["x-ms-documentdb-query-enablecrosspartition"] = "true"
$queryHeaders["Content-Type"] = "application/query+json"

$body = @{
    query = "SELECT * FROM c"
} | ConvertTo-Json

Invoke-RestMethod -Uri $queryUri -Headers $queryHeaders -Method Post -Body $body

2. 创建/更新文档（POST/PUT请求） #

创建或更新时无需指定任何分区键头，后台会自动处理虚拟分区键逻辑：

创建文档 #

$createUri = "$cosmosEndpoint/dbs/$databaseId/colls/$containerId/docs"
$createHeaders = $headers.Clone()
$createHeaders["Content-Type"] = "application/json"

$newDoc = @{
    id = "new-doc-001"
    otherProperty = "test value"
} | ConvertTo-Json

Invoke-RestMethod -Uri $createUri -Headers $createHeaders -Method Post -Body $newDoc

更新文档 #

需指定完整文档路径并携带ETag做并发校验：

$updateUri = "$cosmosEndpoint/dbs/$databaseId/colls/$containerId/docs/update-doc-001"
$updateHeaders = $headers.Clone()
$updateHeaders["Content-Type"] = "application/json"
$updateHeaders["x-ms-documentdb-etag"] = "\"your-doc-etag\"" # 从GET请求结果中获取ETag

$updatedDoc = @{
    id = "update-doc-001"
    otherProperty = "updated value"
} | ConvertTo-Json

Invoke-RestMethod -Uri $updateUri -Headers $updateHeaders -Method Put -Body $updatedDoc

关键注意事项 #

• 禁止添加任何分区键头（x-ms-partitionkey或x-ms-documentdb-partitionkey），虚拟分区键由后台自动维护，无需手动指定。
• 必须使用2021-05-15及以上版本的API，旧版本会错误强制要求分区键参数。
• 确保密钥拥有对应操作权限（如文档读写、元数据读取等），避免权限校验失败。

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