Aggiornamento parziale dei documenti in Azure Cosmos DB

SI APPLICA A: NoSQL

La funzionalità di aggiornamento parziale dei documenti di Azure Cosmos DB (nota anche come API Patch) offre un modo pratico per modificare un documento in un contenitore. Attualmente, per aggiornare un documento, il client deve leggerlo, eseguire verifiche di controllo della concorrenza ottimistica (se necessario), aggiornare il documento in locale e quindi inviarlo tramite rete come documento intero di chiamata API di sostituzione.

La funzionalità di aggiornamento parziale dei documenti migliora significativamente questa esperienza. Il client può inviare solo le proprietà o i campi modificati di un documento senza eseguire un'operazione di sostituzione completa del documento. I principali vantaggi offerti da questa funzionalità includono:

• Miglioramento della produttività degli sviluppatori: fornisce un'API pratica per facilitare l'uso e la possibilità di aggiornare in modo condizionale il documento.
• Miglioramenti delle prestazioni: evita cicli di CPU aggiuntivi sul lato client, riduce la latenza end-to-end e la larghezza di banda di rete.
• Scritture in più aree: supporta la risoluzione automatica e trasparente dei conflitti con aggiornamenti parziali su percorsi discreti all'interno dello stesso documento.

Nota

L'operazione di aggiornamento parziale dei documenti si basa sull'RFC patch JSON. I nomi delle proprietà nei percorsi devono eseguire l'escape dei caratteri ~ e / rispettivamente come ~0 e ~1.

Documento JSON di destinazione di esempio:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Documento di patch JSON:

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

Documento JSON risultante:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Operazioni supportate

Questa tabella riepiloga le operazioni supportate da questa funzionalità.

Nota

Il percorso di destinazione fa riferimento a una posizione all'interno del documento JSON

Tipo di operazione	Descrizione
Aggiunta	A seconda dell'ambiente di destinazione, Add esegue una delle operazioni seguenti: • Se il percorso di destinazione specifica un elemento che non esiste, viene aggiunto. • Se il percorso di destinazione specifica un elemento già esistente, il relativo valore viene sostituito. • Se il percorso di destinazione è un indice di matrice valido, viene inserito un nuovo elemento nella matrice in corrispondenza dell'indice specificato. In questo modo, gli elementi esistenti vengono spostati dopo il nuovo elemento. • Se l'indice specificato è uguale alla lunghezza della matrice, aggiunge un elemento alla matrice. Anziché specificare un indice, è anche possibile usare il carattere -. Comporta anche l'aggiunta dell'elemento accodato alla matrice. Nota: se si specifica un indice superiore alla lunghezza della matrice, viene generato un errore.
Set	L'operazioneSet è simile a Add ad eccezione del tipo di dati della matrice. Se il percorso di destinazione è un indice di matrice valido, viene aggiornato l'elemento esistente in corrispondenza dell'indice.
Sostituzione	L'operazione Replace è simile a Set, ad eccezione del fatto che segue rigorosamente la sostituzione soltanto della semantica. Nel caso in cui il percorso di destinazione specifichi un elemento o una matrice che non esiste, viene generato un errore.
Rimuovi	A seconda dell'ambiente di destinazione, Remove esegue una delle operazioni seguenti: • Se il percorso di destinazione specifica un elemento che non esiste, viene generato un errore. • Se il percorso di destinazione specifica un elemento già esistente, viene rimosso. • Se il percorso di destinazione è un indice di matrice, viene eliminato e tutti gli elementi sopra l'indice specificato vengono spostati indietro di una posizione. Nota: se si specifica un indice pari o superiore alla lunghezza della matrice, viene generato un errore.
Incremento valore Identity	Questo operatore esegue l'incremento di un campo in base al valore specificato. Può accettare valori positivi e negativi. Se il campo non esiste, crea il campo e lo imposta sul valore specificato.
Sposta	Questo operatore rimuove il valore da una posizione specificata e lo aggiunge alla posizione di destinazione. L'oggetto dell'operazione DEVE contenere un membro "from", ovvero una stringa contenente un valore del puntatore JSON che fa riferimento alla posizione nel documento di destinazione da cui spostare il valore. Il percorso "from" DEVE esistere affinché l'operazione venga completata correttamente. Se la posizione "path" suggerisce un oggetto che non esiste, crea l'oggetto e imposta il valore uguale al valore in corrispondenza della posizione "from" •Se la posizione "path" suggerisce un oggetto già esistente, sostituirà il valore nella posizione "path" con il valore nella posizione "from" •L'attributo "path" non può essere un elemento figlio di JSON del percorso JSON "from"

Modalità supportate

La funzionalità di aggiornamento parziale dei documenti supporta le modalità di funzionamento seguenti. Per esempi di codice, vedere il documento Guida introduttiva.

• Patch a documento singolo: è possibile applicare patch a un singolo documento in base all'ID e alla chiave di partizione. È possibile eseguire più operazioni di patch in un singolo documento. Il limite massimo è di 10 operazioni.

• Patch a più documenti: è possibile applicare patch a più documenti all'interno della stessa chiave di partizione come parte di una transazione. Questa transazione multi-documento viene sottoposta a commit solo se tutte le operazioni hanno esito positivo nell'ordine in cui sono descritte. Se un'operazione non riesce, viene eseguito il rollback dell'intera transazione.

• Aggiornamento condizionale: per queste modalità, è possibile aggiungere un predicato di filtro simile a SQL (ad esempio from c where c.taskNum = 3), in modo che l'operazione abbia esito negativo se la precondizione specificata nel predicato non viene soddisfatta.

• È anche possibile usare le API in blocco degli SDK supportati per eseguire una o più operazioni patch su più documenti.

Analogie e differenze

Vediamo un confronto delle analogie e delle differenze tra le modalità supportate.

Aggiunta e definizione a confronto

L'operazioneSet è simile a Add per tutti i tipi di dati ad eccezione di Array. Un'operazione di Add in qualsiasi indice (valido) comporta l'aggiunta di un elemento in corrispondenza dell'indice specificato e qualsiasi elemento esistente nella matrice finisce per spostarsi dopo l'elemento esistente. Questo comportamento è diverso da quello dell'operazione Set, che aggiorna l'elemento esistente in corrispondenza dell'indice specificato.

Aggiunta e sostituzione a confronto

L'operazione Add aggiunge una proprietà se non esiste già (incluso il tipo di dati Array). L'operazione Replace ha esito negativo se la proprietà non esiste (si applica anche al tipo di dati Array).

Definizione e sostituzione a confronto

L'operazione Set aggiunge una proprietà se non esiste già (tranne che in presenza del tipo di dati Array). L'operazione Replace ha esito negativo se la proprietà non esiste (si applica anche al tipo di dati Array).

Nota

Replace è una buona soluzione quando l'utente si aspetta che alcune delle proprietà siano sempre presenti e consente di asserire/imporre tale condizione.

Informazioni di riferimento sulle API REST per l'aggiornamento parziale dei documenti

L'API REST di Azure Cosmos DB offre l'accesso programmatico alle risorse di Azure Cosmos DB per creare, eseguire query ed eliminare database, documenti e raccolte di documenti. Oltre a eseguire operazioni di inserimento, sostituzione, eliminazione, lettura, enumerazione e query su documenti JSON in una raccolta, è possibile usare il metodo HTTP PATCH per l'operazione di aggiornamento parziale dei documenti. Per informazioni dettagliate, vedere le informazioni di riferimento sull'API REST di Azure Cosmos DB.

Ad esempio, ecco come si presenta la richiesta per un'operazione di set usando l'aggiornamento parziale dei documenti.

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

Risoluzione dei conflitti a livello di documento e a livello di percorso a confronto

Se l'account Azure Cosmos DB è configurato con più aree di scrittura, i conflitti e i criteri di risoluzione dei conflitti sono applicabili a livello di documento, con l'opzione di priorità ultima scrittura (LWW) come criterio di risoluzione dei conflitti predefinito. Per gli aggiornamenti parziali dei documenti, le operazioni di patch in più aree rilevano e risolvono i conflitti a livello di percorso più granulare.

È possibile comprendere meglio la risoluzione dei conflitti con un esempio.

Si supponga di avere il documento seguente in Azure Cosmos DB:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Client diversi emettono le operazioni patch contemporaneamente tra aree diverse:

• Attributo Set /level a platino
• 67890 Remove da /phone

Poiché le richieste di patch sono state effettuate a percorsi non in conflitto all'interno del documento, queste richieste vengono risolte automaticamente e in modo trasparente (anziché a livello di documento con l'opzione di priorità ultima scrittura).

Il client visualizzerà il documento seguente dopo la risoluzione dei conflitti:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Nota

Nel caso in cui la stessa proprietà di un documento venga applicata contemporaneamente a patch in più aree, si applicano i normali criteri di risoluzione dei conflitti.

Feed delle modifiche

Il feed di modifiche in Azure Cosmos DB ascolta un contenitore per eventuali modifiche e quindi restituisce i documenti modificati. Usando il feed di modifiche, vengono visualizzati tutti gli aggiornamenti ai documenti, inclusi gli aggiornamenti parziali e completi dei documenti. Quando si elaborano elementi dal feed di modifiche, viene restituito il documento completo anche se l'aggiornamento è il risultato di un'operazione di patch.

Per altre informazioni sul feed di modifiche in Azure Cosmos DB, vedere Feed di modifiche in Azure Cosmos DB.

Passaggi successivi

• Informazioni su come iniziare a utilizzare l'aggiornamento parziale dei documenti con .NET, Java e Node
• Domande frequenti sull'aggiornamento parziale dei documenti