Applicare patch a un documento

Articolo
08/05/2023

Azure Cosmos DB è un database multimodello distribuito a livello globale con supporto per più API. Questo articolo illustra l'API SQL per Azure Cosmos DB.

L'operazione Patch Document esegue aggiornamenti a livello di percorso a file/proprietà specifici in un singolo documento.

Richiesta

Metodo	URI richiesta	Descrizione
PATCH	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs/{id}	{databaseaccount} è il nome dell'account Azure Cosmos DB creato nella sottoscrizione. Il valore {db-id} è il nome/ID generato dall'utente del database, non l'ID generato dal sistema (rid). Il valore {coll-id} è il nome della raccolta che contiene il documento. L'ID è il valore di {id} nel documento

Intestazioni

Vedere Intestazioni di richiesta REST comuni di Azure Cosmos DB per le intestazioni usate da tutte le richieste di Azure Cosmos DB.

Intestazione	Obbligatoria	Tipo	Descrizione
x-ms-documentdb-partitionkey	Facoltativo	Array	Valore della chiave di partizione per il documento da applicare alle patch. Deve essere incluso se e solo se la raccolta viene creata con una definizione partitionKey .

Corpo

Proprietà	Obbligatoria	Tipo	Descrizione
Operazioni	Necessario	Array	Patch supporta operazioni singole o multiple che devono essere passate come matrice

Singola operazione

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

Più operazioni

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

Operazione di patch condizionale

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

Risposta

Restituisce il corpo del documento con patch.

Intestazioni

Vedere Intestazioni di risposta REST comuni di Azure Cosmos DB per le intestazioni restituite da tutte le risposte di Azure Cosmos DB.

Proprietà	Type	Descrizione
x-ms-request-charge	Number	Numero di unità richiesta utilizzate dall'operazione.
x-ms-session-token	string	Token stringa usato con coerenza a livello di sessione. I client devono salvare questo valore e impostarlo per le successive richieste di lettura per la coerenza della sessione.
Content-Location	string	URL del contenuto della patch passato.

Codici di stato

La seguente tabella elenca i codici di stato comuni restituiti da questa operazione. Per un elenco completo dei codici di stato, vedere Codici di stato HTTP.

Codice di stato HTTP	Descrizione
200 - OK	L'operazione è stata completata.
400 - Richiesta non valida	Il corpo JSON non è valido.
412 - Condizione preliminare non riuscita	La condizione preliminare specificata non viene soddisfatta

Corpo

Proprietà	Descrizione
_liberarsi	Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco gerarchico anche per ogni stack di risorse nel modello di risorse. Viene usato internamente per il posizionamento e l'esplorazione della risorsa documento.
_Ts	Si tratta di una proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp.
_stesso	Si tratta di una proprietà generata dal sistema con URI per la risorsa.
_Etag	Si tratta di una proprietà generata dal sistema che specifica l'etag della risorsa necessaria per il controllo della concorrenza ottimistica.
_Allegati	Si tratta di una proprietà generata dal sistema che specifica il percorso indirizzabile per la risorsa allegati.

{
    "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
}

Esempio

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
}

Condividi tramite

Applicare patch a un documento

Richiesta

Intestazioni

Corpo

Singola operazione

Più operazioni

Operazione di patch condizionale

Risposta

Intestazioni

Codici di stato

Corpo

Esempio

Vedere anche

Risorse aggiuntive