Częściowa aktualizacja dokumentu w usłudze Azure Cosmos DB

Artykuł
08/15/2024

DOTYCZY: NoSQL

Funkcja częściowej aktualizacji dokumentu usługi Azure Cosmos DB (znana również jako interfejs API poprawek) zapewnia wygodny sposób modyfikowania dokumentu w kontenerze. Obecnie, aby zaktualizować dokument, który klient musi go odczytać, wykonaj optymistyczne kontrole kontroli współbieżności (w razie potrzeby), zaktualizuj dokument lokalnie, a następnie wyślij go za pośrednictwem przewodu jako całego dokumentu Zastąp wywołanie interfejsu API.

Funkcja częściowej aktualizacji dokumentu znacznie poprawia to środowisko. Klient może wysyłać tylko zmodyfikowane właściwości/pola w dokumencie bez wykonywania pełnej operacji zastępowania dokumentu. Najważniejsze zalety tej funkcji obejmują:

Większa produktywność deweloperów: zapewnia wygodny interfejs API umożliwiający łatwe używanie i możliwość warunkowego aktualizowania dokumentu.
Ulepszenia wydajności: pozwala uniknąć dodatkowych cykli procesora CPU po stronie klienta, zmniejsza całkowite opóźnienia i przepustowość sieci.
Zapisy w wielu regionach: obsługuje automatyczne i przezroczyste rozwiązywanie konfliktów z częściowymi aktualizacjami ścieżek dyskretnych w tym samym dokumencie.

Uwaga

Operacja aktualizacji dokumentu częściowego jest oparta na dokumencie RFC poprawki JSON. Nazwy właściwości w ścieżkach muszą mieć odpowiednio znaki ~ i i ~0 / ~1.

Przykładowy docelowy dokument JSON:

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

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

Wynikowy dokument JSON:

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

Obsługiwane operacje

Ta tabela zawiera podsumowanie operacji obsługiwanych przez tę funkcję.

Uwaga

ścieżka docelowa odwołuje się do lokalizacji w dokumencie JSON

Typ operacji	opis
Dodaj	`Add` wykonuje jedną z następujących czynności, w zależności od ścieżki docelowej: • Jeśli ścieżka docelowa określa element, który nie istnieje, zostanie dodany. • Jeśli ścieżka docelowa określa element, który już istnieje, jego wartość zostanie zamieniona. • Jeśli ścieżka docelowa jest prawidłowym indeksem tablicy, nowy element zostanie wstawiony do tablicy w określonym indeksie. Spowoduje to przesunięcie istniejących elementów po nowym elemercie. • Jeśli określony indeks jest równy długości tablicy, dołącza element do tablicy. Zamiast określać indeks, można również użyć `-` znaku . Powoduje to również dołączanie elementu do tablicy. Uwaga: określenie indeksu większego niż długość tablicy powoduje wystąpienie błędu.
Zestaw	`Set` operacja jest podobna do `Add` z wyjątkiem typu danych Tablica. Jeśli ścieżka docelowa jest prawidłowym indeksem tablicy, istniejący element w tym indeksie jest aktualizowany.
Replace	`Replace` operacja jest podobna do tej, z tą różnicą, że `Set` jest zgodna z rygorystyczną zamianą tylko semantyki. Jeśli ścieżka docelowa określa element lub tablicę, która nie istnieje, powoduje błąd.
Usuń	`Remove` wykonuje jedną z następujących czynności, w zależności od ścieżki docelowej: • Jeśli ścieżka docelowa określa element, który nie istnieje, powoduje błąd. • Jeśli ścieżka docelowa określa element, który już istnieje, zostanie usunięty. • Jeśli ścieżka docelowa jest indeksem tablicy, zostanie usunięta, a wszystkie elementy powyżej określonego indeksu zostaną przesunięte z powrotem na jedną pozycję. Uwaga: określenie indeksu równego lub większego niż długość tablicy spowoduje wystąpienie błędu.
Wzrost	Ten operator zwiększa pole o określoną wartość. Może zaakceptować zarówno wartości dodatnie, jak i ujemne. Jeśli pole nie istnieje, tworzy pole i ustawia je na określoną wartość.
Przesuń	Ten operator usuwa wartość w określonej lokalizacji i dodaje ją do lokalizacji docelowej. Obiekt operacji MUSI zawierać element członkowski "from", który jest ciągiem zawierającym wartość wskaźnika JSON odwołującą się do lokalizacji w dokumencie docelowym w celu przeniesienia wartości z. Lokalizacja "from" MUSI istnieć, aby operacja zakończyła się pomyślnie. Jeśli lokalizacja "path" sugeruje obiekt, który nie istnieje, utworzy obiekt i ustawi wartość równą wartości w lokalizacji "from" •Jeśli lokalizacja "path" sugeruje obiekt, który już istnieje, zastąpi wartość w lokalizacji "path" wartością w lokalizacji "from" •Atrybut "Ścieżka" nie może być elementem podrzędnym JSON lokalizacji JSON "from"

Obsługiwane tryby

Funkcja częściowej aktualizacji dokumentu obsługuje następujące tryby operacji. Zapoznaj się z dokumentem Wprowadzenie , aby zapoznać się z przykładami kodu.

Poprawka pojedynczego dokumentu: możesz zastosować poprawkę pojedynczego dokumentu na podstawie jego identyfikatora i klucza partycji. Istnieje możliwość wykonania wielu operacji poprawek w jednym dokumencie. Maksymalny limit to 10 operacji.
Poprawka z wieloma dokumentami: wiele dokumentów w ramach tego samego klucza partycji można zastosować poprawki w ramach transakcji. Ta transakcja z wieloma dokumentami jest zatwierdzana tylko wtedy, gdy wszystkie operacje kończą się powodzeniem w podanej kolejności. Jeśli jakakolwiek operacja zakończy się niepowodzeniem, cała transakcja zostanie wycofana.
Aktualizacja warunkowa: w przypadku wyżej wymienionych trybów można również dodać predykat filtru przypominający SQL (na przykład from c where c.taskNum = 3), tak aby operacja nie powiodła się, jeśli warunek wstępny określony w predykacie nie jest spełniony.
Możesz również użyć zbiorczych interfejsów API obsługiwanych zestawów SDK, aby wykonać co najmniej jedną operację poprawek na wielu dokumentach.

Podobieństwa i różnice

Porównajmy podobieństwa i różnice między obsługiwanymi trybami.

Dodawanie i ustawianie

Set operacja jest podobna do Add dla wszystkich typów danych z wyjątkiem Array. Add Operacja w dowolnym indeksie (prawidłowym) powoduje dodanie elementu w określonym indeksie, a wszystkie istniejące elementy w tablicy kończą się przesunięciem po istniejącym elemenie. To zachowanie jest w przeciwieństwie do Set operacji, która aktualizuje istniejący element w określonym indeksie.

Dodawanie i zastępowanie

Add operacja dodaje właściwość, jeśli jeszcze nie istnieje (w tym Array typ danych). Replace operacja kończy się niepowodzeniem, jeśli właściwość nie istnieje (dotyczy Array również typu danych).

Ustawianie i zastępowanie

Set operacja dodaje właściwość, jeśli jeszcze nie istnieje (z wyjątkiem sytuacji, gdy istnieje Array). Replace operacja kończy się niepowodzeniem, jeśli właściwość nie istnieje (dotyczy Array również typu danych).

Uwaga

Replace jest dobrym kandydatem, w którym użytkownik oczekuje, że niektóre właściwości będą zawsze obecne i umożliwiają asercję/wymuszanie tego.

Dokumentacja interfejsu API REST dotycząca częściowej aktualizacji dokumentu

Interfejs API REST usługi Azure Cosmos DB zapewnia programowy dostęp do zasobów usługi Azure Cosmos DB w celu tworzenia, wykonywania zapytań i usuwania baz danych, kolekcji dokumentów i dokumentów. Oprócz wykonywania operacji wstawiania, zastępowania, usuwania, odczytu, wyliczania i wykonywania zapytań na dokumentach JSON w kolekcji można użyć PATCH metody HTTP dla operacji częściowej aktualizacji dokumentu. Aby uzyskać szczegółowe informacje, zapoznaj się z dokumentacją interfejsu API REST usługi Azure Cosmos DB.

Na przykład poniżej przedstawiono, jak wygląda żądanie dla set operacji przy użyciu częściowej aktualizacji 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"
    }
  ]
}

Rozwiązywanie konfliktów na poziomie dokumentu a na poziomie ścieżki

Jeśli twoje konto usługi Azure Cosmos DB jest skonfigurowane z wieloma regionami zapisu, zasady rozwiązywania konfliktów i konfliktów mają zastosowanie na poziomie dokumentu, a ustawienie Last Write Wins (LWW) jest domyślnymi zasadami rozwiązywania konfliktów. W przypadku aktualizacji częściowych dokumentów operacje poprawek w wielu regionach wykrywają i rozwiązują konflikty na bardziej szczegółowym poziomie ścieżki.

Rozwiązanie konfliktów można lepiej zrozumieć przy użyciu przykładu.

Załóżmy, że masz następujący dokument w usłudze Azure Cosmos DB:

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

Różni klienci wystawiają operacje poprawek współbieżnie w różnych regionach:

Setatrybut platynowy /level
Remove 67890 od /phone

Ponieważ żądania poprawek zostały wykonane do ścieżek innych niż konflicting w dokumencie, te żądania są rozwiązywane automatycznie i w sposób niewidoczny (w przeciwieństwie do ostatniego zapisywania wygrywa na poziomie dokumentu).

Po rozwiązaniu konfliktu klient zobaczy następujący dokument:

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

Uwaga

Jeśli ta sama właściwość dokumentu jest jednocześnie stosowana w wielu regionach, stosowane są regularne zasady rozwiązywania konfliktów.

Źródło zmian

Źródło zmian w usłudze Azure Cosmos DB nasłuchuje kontenera pod kątem zmian, a następnie zwraca zmienione dokumenty. Przy użyciu zestawienia zmian są wyświetlane wszystkie aktualizacje dokumentów, w tym aktualizacje częściowych i pełnych dokumentów. Podczas przetwarzania elementów ze zestawienia zmian pełny dokument jest zwracany nawet wtedy, gdy aktualizacja była wynikiem operacji poprawki.

Aby uzyskać więcej informacji na temat zestawienia zmian w usłudze Azure Cosmos DB, zobacz Zestawienie zmian w usłudze Azure Cosmos DB.

Następne kroki

Dowiedz się, jak rozpocząć pracę z częściową aktualizacją dokumentów przy użyciu programów .NET, Java i Node
Często zadawane pytania dotyczące częściowej aktualizacji dokumentu

Udostępnij za pośrednictwem

Częściowa aktualizacja dokumentu w usłudze Azure Cosmos DB

Obsługiwane operacje

Obsługiwane tryby

Podobieństwa i różnice

Dodawanie i ustawianie

Dodawanie i zastępowanie

Ustawianie i zastępowanie

Dokumentacja interfejsu API REST dotycząca częściowej aktualizacji dokumentu

Rozwiązywanie konfliktów na poziomie dokumentu a na poziomie ścieżki

Źródło zmian

Następne kroki

Opinia

Dodatkowe zasoby