Teilaktualisierung von Dokumenten in Azure Cosmos DB

GILT FÜR: NoSQL

Das Azure Cosmos DB-Feature für die Teilaktualisierung von Dokumenten (auch „Patch-API“) bietet eine praktische Möglichkeit, Dokumente in einem Container zu bearbeiten. Um ein Dokument zu aktualisieren, muss der Client es derzeit lesen, (falls erforderlich) Überprüfungen der optimistischen Gleichzeitigkeitserkennung ausführen, das Dokument lokal aktualisieren und es dann über das Netzwerk als API-Aufruf zum Ersetzen des gesamten Dokuments senden.

Das Feature für die Teilaktualisierung von Dokumenten verbessert diesen Vorgang erheblich. Der Client kann nur die in einem Dokument geänderten Eigenschaften/Felder senden, ohne einen Vorgang zum vollständigen Ersetzen des Dokuments auszuführen. Zu den wichtigsten Vorteilen dieses Features zählen:

• Verbesserte Entwicklerproduktivität: Die praktische API ist benutzerfreundlich und bietet die Möglichkeit, das Dokument bedingt zu aktualisieren.
• Leistungsverbesserungen: Das Feature vermeidet zusätzliche CPU-Zyklen auf Clientseite, reduziert die End-to-End-Latenz und erhöht die Netzwerkbandbreite.
• Schreibvorgänge in mehreren Regionen: Das Feature unterstützt die automatische und transparente Konfliktlösung durch die Teilaktualisierung von diskreten Pfaden innerhalb desselben Dokuments.

Ein JSON-Beispielzieldokument:

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

Ein JSON-Patchdokument:

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

Das resultierende JSON-Dokument:

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

Unterstützte Vorgänge

In dieser Tabelle sind die Vorgänge zusammengefasst, die von dieser Funktion unterstützt werden.

Unterstützte Modi

Das Feature für die Teilaktualisierung von Dokumenten unterstützt die folgenden Betriebsmodi. Im Dokument zu den ersten Schritten finden Sie Codebeispiele.

• Patchen einzelner Dokumente: Sie können ein einzelnes Dokument basierend auf seiner ID und seinem Partitionsschlüssel patchen. Es ist möglich, mehrere Patchvorgänge für ein einzelnes Dokument auszuführen. Der Höchstwert liegt bei 10 Vorgängen.

• Patches von mehreren Dokumenten: Mehrere Dokumente innerhalb desselben Partitionsschlüssels können im Rahmen einer Transaktion gepatcht werden. Diese Mehrfachdokumenttransaktion wird nur dann committet, wenn alle Vorgänge in der beschriebenen Reihenfolge erfolgreich ausgeführt werden. Schlägt ein Vorgang fehl, wird für die gesamte Transaktion ein Rollback ausgeführt.

• Bedingte Aktualisierung: Für die oben genannten Modi ist es auch möglich, ein SQL-ähnliches Filterprädikat hinzuzufügen (z. B. from c where c.taskNum = 3), damit der Vorgang fehlschlägt, wenn die im Prädikat angegebene Vorbedingung nicht erfüllt wird.

• Sie können auch die Massen-APIs unterstützter SDKs verwenden, um mindestens einen Patchvorgang für mehrere Dokumente auszuführen.

Ähnlichkeiten und Unterschiede

Vergleichen wir die Gemeinsamkeiten und Unterschiede zwischen den unterstützten Modi.

„Add“ im Vergleich zu „Set“

Der Set-Vorgang ähnelt Add für alle Datentypen mit Ausnahme von Array. Ein Add-Vorgang an einem beliebigen (gültigen) Index führt dazu, dass am angegebenen Index ein Element hinzugefügt wird und dass alle vorhandenen Elemente im Array an Positionen nach dem vorhandenen Element verschoben werden. Dieses Verhalten steht im Gegensatz zu einem Set-Vorgang, bei dem das vorhandene Element am angegebenen Index aktualisiert wird.

„Add“ im Vergleich zu „Replace“

Ein Add-Vorgang fügt eine Eigenschaft hinzu, wenn sie noch nicht vorhanden ist (einschließlich des Datentyps Array). Der Replace-Vorgang schlägt fehl, wenn die Eigenschaft nicht vorhanden ist (dies gilt auch für den Datentyp Array).

„Set“ im Vergleich zu „Replace“

Ein Set-Vorgang fügt eine Eigenschaft hinzu, wenn sie noch nicht vorhanden ist (außer bei Array-Datentypen). Der Replace-Vorgang schlägt fehl, wenn die Eigenschaft nicht vorhanden ist (dies gilt auch für den Datentyp Array).

REST-API-Referenz für Teilaktualisierung von Dokumenten

Die Azure Cosmos DB REST-API bietet programmgesteuerten Zugriff auf Azure Cosmos DB-Ressourcen zum Erstellen, Abfragen und Löschen von Datenbanken, Dokumentsammlungen und Dokumenten. Sie können nicht nur Vorgänge zum Einfügen, Ersetzen, Löschen, Lesen, Enumerieren und Abfragen für JSON-Dokumente in einer Sammlung ausführen, sondern auch die HTTP-Methode PATCH für die Teilaktualisierung von Dokumenten verwenden. Weitere Informationen finden Sie in der Azure Cosmos DB REST-API-Referenz.

So sieht beispielsweise die Anforderung für einen set-Vorgang mit einer Teilaktualisierung des Dokuments aus.

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

Konfliktlösung auf Dokument- und Pfadebene im Vergleich

Wenn Ihr Azure Cosmos DB-Konto mit mehreren Schreibregionen konfiguriert ist, gelten Konflikt- und Konfliktlösungsrichtlinien auf Dokumentebene, bei denen das Prinzip „Letzter Schreibvorgang gewinnt“ (Last Write Wins, LWW) die Standardrichtlinie für die Konfliktlösung darstellt. Bei der Teilaktualisierung von Dokumenten erkennen und lösen Patchvorgänge in mehreren Regionen Konflikte auf einer tieferen Pfadebene.

Die Konfliktauflösung lässt sich anhand eines Beispiels besser verdeutlichen.

Angenommen, Sie verfügen über das folgende Dokument in Azure Cosmos DB:

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

Verschiedene Clients führen Patchvorgänge gleichzeitig in verschiedenen Regionen aus:

• Set attribute /level to platinum
• Remove 67890 from /phone

Da Patchanforderungen an Pfade innerhalb des Dokuments gestellt wurden, die keinen Konflikt verursachen, werden diese Konflikte in diesen Anforderungen automatisch und transparent aufgelöst (im Gegensatz zum LWW-Prinzip (Last Writer Wins) auf Dokumentebene).

Dem Client sieht nach der Konfliktlösung das folgende Dokument:

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

Änderungsfeed

Der Änderungsfeed in Azure Cosmos DB überwacht alle Änderungen in einem Container und gibt dann Dokumente aus, die geändert wurden. Mithilfe des Änderungsfeeds werden alle Updates für Dokumente angezeigt, einschließlich teilweiser und vollständiger Dokumentaktualisierungen. Wenn Sie Elemente aus dem Änderungsfeed verarbeiten, wird das vollständige Dokument auch dann zurückgegeben, wenn die Aktualisierung das Ergebnis eines Patchvorgangs war.

Weitere Informationen zum Änderungsfeed in Azure Cosmos DB finden Sie unter Änderungsfeed in Azure Cosmos DB.

Nächste Schritte

• Erfahren Sie, wie Sie mit der Teilaktualisierung von Dokumenten in .NET, Java und Node beginnen.
• Häufig gestellte Fragen zur Teilaktualisierung von Dokumenten