Částečná aktualizace dokumentu ve službě Azure Cosmos DB

  • Platí pro: ✅ NoSQL

Funkce částečné aktualizace dokumentů azure Cosmos DB, označovaná také jako rozhraní PATCH API, poskytuje pohodlný způsob, jak upravit dokument v kontejneru. Pokud chcete aktualizovat dokument, musí si ho klient přečíst, provést kontroly optimistického řízení souběžnosti (v případě potřeby), aktualizovat dokument místně a pak ho odeslat přes drát jako celé volání rozhraní API Nahradit dokument.

Tato funkce částečné aktualizace dokumentu výrazně zlepšuje toto prostředí. Klient může v dokumentu odesílat pouze změněné vlastnosti nebo pole, aniž by museli provádět úplnou operaci nahrazení dokumentu. Mezi klíčové výhody této funkce patří:

  • Vylepšená produktivita vývojářů: Poskytuje pohodlné rozhraní API pro snadné použití a možnost podmíněné aktualizace dokumentu.
  • Vylepšení výkonu: Vyhýbá se nadbytečným cyklům CPU na straně klienta, což snižuje latenci end-to-end a spotřebu síťové šířky pásma.
  • Zápisy do více oblastí: Podporuje automatické a transparentní řešení konfliktů s částečnými aktualizacemi na oddělených cestách v rámci stejného dokumentu.

Note

Operace částečné aktualizace dokumentu je založena na JSON Patch RFC. Názvy vlastností v cestách musí escapovat znaky ~ a / jako ~0 a ~1, v tomto pořadí.

Příklad cílového dokumentu JSON:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

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

Výsledný dokument JSON:

{
  "id": "eeeeeeee-4444-5555-6666-ffffffffffff",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Podporované operace

Tato tabulka shrnuje operace podporované touto funkcí.

Note

cílová cesta odkazuje na umístění v dokumentu JSON.

Typ operace Description
Přidat Add provede jednu z následujících operací v závislosti na cílové cestě:
• Pokud cílová cesta určuje prvek, který neexistuje, přidá se.
• Pokud cílová cesta určuje prvek, který již existuje, jeho hodnota se nahradí.
• Pokud je cílová cesta platným indexem pole, vloží se do pole v zadaném indexu nový prvek. Tím se stávající prvky posunou za nový prvek.
• Pokud je zadaný index roven délce pole, připojí prvek k matici. Místo zadávání indexu - můžete také použít znak. Výsledkem je také připojení elementu k poli.
Poznámka: Zadání indexu většího než délka pole způsobí chybu.
Set Set je podobný jako Add kromě datového typu pole. Pokud je cílová cesta platným indexem pole, aktualizuje se existující prvek v tomto indexu.
Nahradit Replace je podobný Set, kromě toho, že se řídí důslednou sémantikou pouze nahrazení. V případě, že cílová cesta určuje prvek nebo pole, které neexistuje, dojde k chybě.
Remove Remove provede jednu z následujících operací v závislosti na cílové cestě:
• Pokud cílová cesta určuje prvek, který neexistuje, dojde k chybě.
• Pokud cílová cesta určuje prvek, který již existuje, je odebrán.
• Pokud je cílová cesta indexem pole, odstraní se a všechny prvky nad zadaným indexem se posunou o jednu pozici zpět.
Poznámka: Zadání indexu, který je roven nebo větší než délka pole, by vedlo k chybě.
Increment Tento operátor zvýší pole o zadanou hodnotu. Může přijímat kladné i záporné hodnoty. Pokud pole neexistuje, vytvoří pole a nastaví ho na zadanou hodnotu.
Move Tento operátor odebere hodnotu v zadaném umístění a přidá ji do cílového umístění. Objekt operace MUSÍ obsahovat člena "from", což je řetězec s hodnotou ukazatele JSON, který odkazuje na umístění v cílovém dokumentu, odkud se hodnota přemístí. Aby byla operace úspěšná, musí existovat umístění „from“. Pokud umístění "cesta" navrhne objekt, který neexistuje, vytvoří objekt a nastaví hodnotu rovnu hodnotě v umístění "from".
•Pokud umístění "path" navrhne objekt, který již existuje, nahradí hodnotu v umístění "path" hodnotou v umístění "from".
•Atribut "path" nemůže být podřízeným prvkem JSON objektu JSON "from".

Podporované režimy

Funkce částečné aktualizace dokumentu podporuje následující režimy provozu. Příklady kódu najdete v dokumentu Začínáme .

  • Oprava dokumentu: Jeden dokument můžete opravit podle jeho ID a klíče oddílu. V jednom dokumentu je možné provést několik operací oprav. Maximální limit je 10 operací.

  • Oprava více dokumentů: Více dokumentů ve stejném klíči oddílu lze opravit jako součást transakce. Tato transakce s více dokumenty je potvrzena pouze v případě, že všechny operace budou úspěšné v pořadí, v jakém jsou popsány. Pokud jakákoli operace selže, vrátí se celá transakce zpět.

  • Podmíněná aktualizace: U dříve zmíněných režimů je také možné přidat predikát filtru podobné SQL (například from c where c.taskNum = 3), aby operace selhala, pokud předběžná podmínka zadaná v predikátu není splněná.

  • Můžete také použít hromadná rozhraní API podporovaných sad SDK ke spuštění jedné nebo více operací oprav na více dokumentech.

Podobnosti a rozdíly

Pojďme porovnat podobnosti a rozdíly mezi podporovanými režimy.

Přidat vs. Nastavit

Operace Set je podobná Add pro všechny datové typy s výjimkou Array. Operace Add v libovolném (platném) indexu způsobí přidání elementu v zadaném indexu a všechny existující prvky v poli se nakonec posunou za existující prvek. Toto chování je na rozdíl od Set operace, která aktualizuje existující prvek v zadaném indexu.

Přidání vs. Nahrazení

Operace Add přidá vlastnost, pokud ještě neexistuje (včetně Array datového typu). Replace operace selže, pokud vlastnost neexistuje (platí i pro Array datový typ).

Nastavení vs. nahrazení

Operace Set přidá vlastnost, pokud ještě neexistuje (s výjimkou případu, kdy existuje Array). Replace operace selže, pokud vlastnost neexistuje (platí i pro Array datový typ).

Note

Replace je vhodným kandidátem, kde uživatel očekává, že některé vlastnosti budou vždy přítomné a umožní vám to uplatnit nebo vynutit.

Referenční informace k rozhraní REST API pro částečnou aktualizaci dokumentu

Rozhraní REST API služby Azure Cosmos DB poskytuje programový přístup k prostředkům služby Azure Cosmos DB pro vytváření, dotazování a odstraňování databází, kolekcí dokumentů a dokumentů. Kromě provádění operací vložení, nahrazení, odstranění, čtení, výčtu a dotazování na dokumenty JSON v kolekci můžete použít metodu PATCH HTTP pro částečnou operaci aktualizace dokumentu. Podrobnosti najdete v referenčních informacích k rozhraní REST API služby Azure Cosmos DB.

Zde je příklad, jak vypadá požadavek pro operaci set využívající částečnou aktualizaci dokumentu.

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

Řešení konfliktů na úrovni dokumentu versus na úrovni cesty

Pokud je váš účet služby Azure Cosmos DB nakonfigurovaný s několika oblastmi zápisu, konflikty a zásady řešení konfliktů se uplatňují na úrovni dokumentu, přičemž výchozí zásadou řešení konfliktů je zásada "Poslední zápis vítězí" (LWW). V případě částečných aktualizací dokumentů operace oprav na více oblastech rozpoznají a vyřeší konflikty na podrobnější úrovni cest.

Řešení konfliktů je možné lépe pochopit pomocí příkladu.

Předpokládejme, že máte v Azure Cosmos DB následující dokument:

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

Různí klienti vydávají operace oprav souběžně napříč různými oblastmi:

  • Setpřiřadit /level k platině
  • Remove 67890 z /phone

Diagram znázorňující řešení konfliktů v souběžných operacích částečné aktualizace ve více oblastech

Vzhledem k tomu, že požadavky na aktualizace byly provedeny na nekonfliktní cesty v dokumentu, tyto žádosti se automaticky a transparentně vyřeší (na rozdíl od situace, kdy by rozhodoval poslední zápis na úrovni dokumentu).

Po vyřešení konfliktů se zobrazí následující dokument:

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

Note

V případě, že se stejná vlastnost dokumentu současně opravuje napříč několika oblastmi, platí běžné zásady řešení konfliktů.

Změna kanálu

Kanál příchozích změn ve službě Azure Cosmos DB monitoruje kontejner pro jakékoli změny a následně zobrazí dokumenty, které byly změněny. Pomocí kanálu změn uvidíte všechny aktualizace dokumentů, včetně částečných i úplných aktualizací dokumentů. Při zpracování položek z kanálu změn se celý dokument vrátí i v případě, že aktualizace byla výsledkem operace opravy.

Další informace o kanálu změn ve službě Azure Cosmos DB najdete v tématu Kanál změn ve službě Azure Cosmos DB.

Další kroky

  • Last updated on