你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

修补文档

项目
08/05/2023

Azure Cosmos DB 是一种全球分布式多模型数据库，支持多个 API。本文介绍了适用于 Azure Cosmos DB 的 SQL API。

该 Patch Document 操作对单个文档中的特定文件/属性执行路径级更新。

请求

方法	请求 URI	说明
修补程序	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs/{id}	{databaseaccount} 是在订阅下创建的 Azure Cosmos DB 帐户的名称。 {db-id} 值是数据库的用户生成的名称/ID，而不是系统生成的 ID (rid) 。 {coll-id} 值是包含文档的集合的名称。 ID 是文档中 {id} 的值

标头

有关所有 Azure Cosmos DB 请求使用的标头，请参阅常见的 Azure Cosmos DB REST 请求标头。

标头	必需	类型	说明
x-ms-documentdb-partitionkey	可选	Array	要修补的文档的分区键值。当且仅当集合是使用 partitionKey 定义创建的时，必须包含。

正文

属性	必选	类型	说明
operations	必需	数组	Patch 支持应作为数组传递的单个或多个操作

单个操作

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

多个操作

{
   "operations":[
      {
         "op":"add",
         "path":"/Parents/0/ZipCode",
         "value":80000
      },
       {
      "op": "set",
       "path": "/Parents/0/FamilyName",
       "value": "Bob"
      }
   ]
}

条件修补操作

{
   "condition":"from c where c.Address.ZipCode ='98101' ",
   "operations":[
      {
         "op":"replace",
         "path":"/Address/ZipCode",
         "value":98107
      }
   ]
}

响应

返回已修补文档的正文。

标头

有关所有 Azure Cosmos DB 响应返回的标头，请参阅常见的 Azure Cosmos DB REST 响应标头。

属性	类型	说明
x-ms-request-charge	Number	操作使用的请求单位数。
x-ms-session-token	String	用于会话级别一致性的字符串令牌。客户端必须保存此值，并为会话一致性的后续读取请求设置此值。
Content-Location	String	正在传递的修补程序内容的 URL。

状态代码

下表列出了此操作返回的常见状态代码。有关状态代码的完整列表，请参阅 HTTP 状态代码。

HTTP 状态代码	说明
200 正常	操作成功。
400 错误的请求	JSON 正文无效。
412 前提失败	未满足指定的先决条件

正文

属性	说明
_摆脱	它是系统生成的属性。资源 ID (_rid) 是一个唯一标识符，也是按资源模型上的资源堆栈分层的标识符。它在内部用于文档资源的放置和导航。
_ts	它是系统生成的属性。它指定资源的上次更新时间戳。高值是一个时间戳。
_自我	它是系统生成的属性，具有资源的 URI。
_Etag	它是一个系统生成的属性，指定乐观并发控制所需的资源 etag 。
_附件	它是一个系统生成的属性，用于指定附件资源的可寻址路径。

{
    "id": "Andersen.1",
    "LastName": "Andersen",
    "Parents": [
        {
            "FamilyName": "Bob",
            "FirstName": "Thomas"
        },
        {
            "FamilyName": null,
            "FirstName": "Mary Kay"
        }
    ],
    "Children": [
        {
            "FamilyName": null,
            "FirstName": "Henriette Thaulow",
            "Gender": "female",
            "Grade": 5,
            "Pets": [
                {
                    "GivenName": "Fluffy"
                }
            ]
        }
    ],
    "Address": {
        "State": "WA",
        "County": "King",
        "City": "Seattle"
    },
    "IsRegistered": false,
    "_rid": "2pFqAMMTYY8BAAAAAAAAAA==",
    "_self": "dbs/2pFqAA==/colls/2pFqAMMTYY8=/docs/2pFqAMMTYY8BAAAAAAAAAA==/",
    "_etag": "\"00000000-0000-0000-d40e-691edfa901d7\"",
    "_attachments": "attachments/",
    "_ts": 1636313638
}

示例

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1  
x-ms-documentdb-partitionkey: ["Andersen"]  
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT  
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache  
User-Agent: Microsoft.Azure.DocumentDB/2.16.12  
x-ms-version: 2015-12-16  
Accept: application/json  
Host: querydemo.documents.azure.com  
Cookie: x-ms-session-token#0=602; x-ms-session-token=602  
Content-Length: calculated when request is sent  
Connection: keep-alive
  
{"operations":[{ "op" :"set", "path":"/Parents/0/FamilyName","value":"Bob" }]}

HTTP/1.1 200 OK  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json 
Content-Location : https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT  
etag: "00003200-0000-0000-0000-56f9e84d0000"  
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;  
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb/colls/testcoll  
x-ms-quorum-acked-lsn: 602  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 12.38  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668  
x-ms-session-token: 0:603  
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Tue, 29 Mar 2016 02:28:30 GMT  
  
{
    "id": "Andersen.1",
    "LastName": "Andersen",
    "Parents": [
        {
            "FamilyName": "Bob",
            "FirstName": "Thomas"
        },
        {
            "FamilyName": null,
            "FirstName": "Mary Kay"
        }
    ],
    "Children": [
        {
            "FamilyName": null,
            "FirstName": "Henriette Thaulow",
            "Gender": "female",
            "Grade": 5,
            "Pets": [
                {
                    "GivenName": "Fluffy"
                }
            ]
        }
    ],
    "Address": {
        "State": "WA",
        "County": "King",
        "City": "Seattle"
    },
    "IsRegistered": false,
    "_rid": "2pFqAMMTYY8BAAAAAAAAAA==",
    "_self": "dbs/2pFqAA==/colls/2pFqAMMTYY8=/docs/2pFqAMMTYY8BAAAAAAAAAA==/",
    "_etag": "\"00000000-0000-0000-d464-a585d94d01d7\"",
    "_attachments": "attachments/",
    "_ts": 1636350676
}

通过

修补文档

请求

标头

正文

单个操作

多个操作

条件修补操作

响应

标头

状态代码

正文

示例

另请参阅

其他资源