Gedeeltelijke documentupdate in Azure Cosmos DB

VAN TOEPASSING OP: NoSQL

De functie gedeeltelijke documentupdate van Azure Cosmos DB (ook wel patch-API genoemd) biedt een handige manier om een document in een container te wijzigen. Als u momenteel een document wilt bijwerken dat de client nodig heeft om het te lezen, voert u optimistische gelijktijdigheidscontroles (indien nodig) uit, werkt u het document lokaal bij en verzendt u het vervolgens via de kabel als een volledige api-aanroep vervangen.

De functie voor gedeeltelijke documentupdates verbetert deze ervaring aanzienlijk. De client kan alleen de gewijzigde eigenschappen/velden in een document verzenden zonder een volledige bewerking voor het vervangen van documenten uit te voeren. De belangrijkste voordelen van deze functie zijn:

• Verbeterde productiviteit van ontwikkelaars: biedt een handige API voor gebruiksgemak en de mogelijkheid om het document voorwaardelijk bij te werken.
• Prestatieverbeteringen: vermijdt extra CPU-cycli aan de clientzijde, vermindert end-to-end latentie en netwerkbandbreedte.
• Schrijfbewerkingen voor meerdere regio's: biedt ondersteuning voor automatische en transparante conflictoplossing met gedeeltelijke updates voor discrete paden binnen hetzelfde document.

Notitie

De bewerking gedeeltelijke documentupdate is gebaseerd op de JSON Patch RFC. Eigenschapsnamen in paden moeten de tekens / ~0 als en ~1, respectievelijk, escapen~.

Een voorbeeld van een JSON-doeldocument:

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

Een JSON Patch-document:

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

Het resulterende JSON-document:

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

Ondersteunde bewerkingen

Deze tabel bevat een overzicht van de bewerkingen die door deze functie worden ondersteund.

Notitie

doelpad verwijst naar een locatie in het JSON-document

Het type bewerking	Beschrijving
Toevoegen	Add voert een van de volgende handelingen uit, afhankelijk van het doelpad: • Als het doelpad een element aangeeft dat niet bestaat, wordt het toegevoegd. • Als het doelpad een element aangeeft dat al bestaat, wordt de waarde vervangen. • Als het doelpad een geldige matrixindex is, wordt er een nieuw element ingevoegd in de matrix op de opgegeven index. Hiermee worden bestaande elementen na het nieuwe element verplaatst. • Als de opgegeven index gelijk is aan de lengte van de matrix, wordt er een element aan de matrix toegevoegd. In plaats van een index op te geven, kunt u ook het - teken gebruiken. Het leidt er ook toe dat het element wordt toegevoegd aan de matrix. Opmerking: als u een index opgeeft die groter is dan de lengte van de matrix, resulteert dit in een fout.
Instellen	Set bewerking is vergelijkbaar met Add behalve met het gegevenstype Matrix. Als het doelpad een geldige matrixindex is, wordt het bestaande element op die index bijgewerkt.
Replace	Replace bewerking is vergelijkbaar met behalve Set dat het volgt strikte vervanging alleen semantiek. Als het doelpad een element of een matrix aangeeft die niet bestaat, resulteert dit in een fout.
Verwijderen	Remove voert een van de volgende handelingen uit, afhankelijk van het doelpad: • Als het doelpad een element aangeeft dat niet bestaat, resulteert dit in een fout. • Als het doelpad een element aangeeft dat al bestaat, wordt het verwijderd. • Als het doelpad een matrixindex is, wordt het verwijderd en worden alle elementen boven de opgegeven index één positie teruggezet. Opmerking: als u een index opgeeft die gelijk is aan of groter is dan de lengte van de matrix, treedt er een fout op.
Vermeerdering	Met deze operator wordt een veld verhoogd op basis van de opgegeven waarde. Het kan zowel positieve als negatieve waarden accepteren. Als het veld niet bestaat, wordt het veld gemaakt en ingesteld op de opgegeven waarde.
Verplaatsen	Deze operator verwijdert de waarde op een opgegeven locatie en voegt deze toe aan de doellocatie. Het bewerkingsobject MOET een 'from'-lid bevatten. Dit is een tekenreeks met een JSON-aanwijzerwaarde die verwijst naar de locatie in het doeldocument waaruit de waarde moet worden verplaatst. De locatie 'van' MOET bestaan om de bewerking te laten slagen. Als de padlocatie een object aangeeft dat niet bestaat, wordt het object gemaakt en wordt de waarde ingesteld die gelijk is aan de waarde op 'van' locatie •Als op de locatie 'pad' een object wordt voorgesteld dat al bestaat, wordt de waarde op de locatie 'pad' vervangen door de waarde op 'van' locatie •"Pad" kenmerk kan geen JSON-onderliggend element zijn van de JSON-locatie 'van'

Ondersteunde modi

Gedeeltelijke functie voor documentupdates ondersteunt de volgende bewerkingsmodi. Raadpleeg het document Aan de slag voor codevoorbeelden.

• Patch voor één document: u kunt één document patchen op basis van de id en de partitiesleutel. Het is mogelijk om meerdere patchbewerkingen uit te voeren op één document. De maximale limiet is 10 bewerkingen.

• Patch voor meerdere documenten: meerdere documenten binnen dezelfde partitiesleutel kunnen worden gepatcht als onderdeel van een transactie. Deze transactie met meerdere documenten wordt alleen doorgevoerd als alle bewerkingen slagen in de volgorde waarin ze worden beschreven. Als een bewerking mislukt, wordt de hele transactie teruggedraaid.

• Voorwaardelijke update: Voor de bovengenoemde modi is het ook mogelijk om een SQL-achtig filterpredicaat (bijvoorbeeld from c where c.taskNum = 3) toe te voegen, zodat de bewerking mislukt als niet aan de voorwaarde in het predicaat wordt voldaan.

• U kunt ook de bulk-API's van ondersteunde SDK's gebruiken om een of meer patchbewerkingen uit te voeren op meerdere documenten.

Overeenkomsten en verschillen

Laten we de overeenkomsten en verschillen tussen de ondersteunde modi vergelijken.

Toevoegen versus instellen

Set bewerking is vergelijkbaar met Add voor alle gegevenstypen, behalve Array. Een Add bewerking op een (geldige) index resulteert in het toevoegen van een element in de opgegeven index en eventuele bestaande elementen in de matrix worden verschoven na het bestaande element. Dit gedrag is in tegenstelling tot Set bewerking waarmee het bestaande element op de opgegeven index wordt bijgewerkt.

Toevoegen versus vervangen

Add met de bewerking wordt een eigenschap toegevoegd als deze nog niet bestaat (inclusief Array gegevenstype). Replace bewerking mislukt als de eigenschap niet bestaat (ook van toepassing op Array gegevenstype).

Instellen versus vervangen

Set bewerking voegt een eigenschap toe als deze nog niet bestaat (behalve als er een Array). Replace bewerking mislukt als de eigenschap niet bestaat (ook van toepassing op Array gegevenstype).

Notitie

Replace is een goede kandidaat waarbij de gebruiker verwacht dat sommige eigenschappen altijd aanwezig zijn en waarmee u dat kunt bevestigen/afdwingen.

REST API-verwijzing voor gedeeltelijke documentupdate

De Azure Cosmos DB REST API biedt programmatische toegang tot Azure Cosmos DB-resources voor het maken, opvragen en verwijderen van databases, documentverzamelingen en documenten. Naast het uitvoeren van insert-, replace-, delete-, read-, opsommings- en querybewerkingen op JSON-documenten in een verzameling, kunt u de HTTP-methode gebruiken voor de PATCH bewerking gedeeltelijke documentupdate. Raadpleeg de Azure Cosmos DB REST API-naslaginformatie voor meer informatie.

Hier ziet u bijvoorbeeld hoe de aanvraag eruitziet voor een set bewerking met behulp van gedeeltelijke documentupdate.

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

Conflictoplossing op documentniveau versus padniveau

Als uw Azure Cosmos DB-account is geconfigureerd met meerdere schrijfregio's, zijn conflicten en conflictoplossingsbeleid van toepassing op documentniveau, waarbij Last Write Wins (LWW) het standaardbeleid voor conflictoplossing is. Voor gedeeltelijke documentupdates detecteren patchbewerkingen in meerdere regio's conflicten op een gedetailleerder padniveau.

Conflictoplossing kan beter worden begrepen met een voorbeeld.

Stel dat u het volgende document hebt in Azure Cosmos DB:

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

Verschillende clients verlenen patchbewerkingen gelijktijdig in verschillende regio's:

• Set kenmerk /level aan platina
• Remove 67890 van /phone

Omdat patchaanvragen zijn gedaan voor niet-conflicterende paden in het document, worden deze aanvragen automatisch en transparant opgelost (in tegenstelling tot Last Writer Wins op documentniveau).

De client ziet het volgende document na conflictoplossing:

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

Notitie

Als dezelfde eigenschap van een document gelijktijdig wordt gepatcht in meerdere regio's, zijn de reguliere beleidsregels voor conflictoplossing van toepassing.

Feed wijzigen

Wijzigingenfeed in Azure Cosmos DB luistert naar een container voor eventuele wijzigingen en voert vervolgens documenten uit die zijn gewijzigd. Als u wijzigingenfeed gebruikt, ziet u alle updates voor documenten, inclusief gedeeltelijke en volledige documentupdates. Wanneer u items uit de wijzigingenfeed verwerkt, wordt het volledige document geretourneerd, zelfs als de update het resultaat was van een patchbewerking.

Zie Wijzigingenfeed in Azure Cosmos DB voor meer informatie over de wijzigingenfeed in Azure Cosmos DB.

Volgende stappen

• Meer informatie over hoe u aan de slag gaat met gedeeltelijke documentupdate met behulp van .NET, Java en Node
• Veelgestelde vragen over gedeeltelijke documentupdates