Transakcyjne operacje wsadowe w usłudze Azure Cosmos DB

DOTYCZY: NoSQL

Wsad transakcyjny opisuje grupę operacji punktów, które muszą zakończyć się powodzeniem lub niepowodzeniem wraz z tym samym kluczem partycji w kontenerze. Operacje są definiowane, dodawane do partii, a partia jest wykonywana. Jeśli wszystkie operacje kończą się powodzeniem w kolejności, w której zostały opisane w transakcyjnej operacji wsadowej, transakcja zostanie zatwierdzona. Jeśli jednak jakakolwiek operacja zakończy się niepowodzeniem, cała transakcja zostanie wycofana.

Co to jest transakcja w usłudze Azure Cosmos DB

Transakcja w typowej bazie danych może być zdefiniowana jako sekwencja operacji wykonywanych jako pojedyncza jednostka logiczna pracy. Każda transakcja zapewnia gwarancje właściwości ACID (niepodzielność, spójność, izolacja, trwałość).

• Niepodzielność gwarantuje, że wszystkie operacje wykonywane wewnątrz transakcji są traktowane jako pojedyncza jednostka, a wszystkie z nich są zatwierdzane lub żadna z nich.
• Spójność zapewnia, że dane są zawsze w prawidłowym stanie między transakcjami.
• Izolacja gwarantuje, że żadne dwie transakcje nie zakłócają siebie — wiele systemów komercyjnych zapewnia wiele poziomów izolacji, które mogą być używane na podstawie potrzeb aplikacji.
• Trwałość gwarantuje, że każda zmiana zatwierdzona w bazie danych zawsze będzie obecna. Usługa Azure Cosmos DB obsługuje pełne transakcje zgodne ze standardem ACID z izolacją migawki dla operacji w ramach tego samego klucza partycji logicznej.

Transakcyjne operacje wsadowe i procedury składowane

Usługa Azure Cosmos DB obecnie obsługuje procedury składowane, które zapewniają również zakres transakcyjny operacji. Jednak transakcyjne operacje wsadowe oferują następujące korzyści:

• Opcja języka — transakcyjna partia jest obsługiwana w zestawie SDK i języku, z którym pracujesz, podczas gdy procedury składowane muszą być napisane w języku JavaScript.
• Przechowywanie wersji kodu — przechowywanie wersji kodu aplikacji i dołączanie go do potoku ciągłej integracji/ciągłego wdrażania jest znacznie bardziej naturalne niż organizowanie aktualizacji procedury składowanej i upewnienie się, że przerzucanie odbywa się we właściwym czasie. Ułatwia również wycofywanie zmian.
• Wydajność — mniejsze opóźnienie operacji równoważnych o maksymalnie 30% w porównaniu z wykonaniem procedury składowanej.
• Serializacja zawartości — każda operacja w partii transakcyjnej może używać niestandardowych opcji serializacji dla ładunku.

Jak utworzyć transakcyjną operację wsadową

.NET

Podczas tworzenia transakcyjnej operacji wsadowej rozpocznij od wystąpienia kontenera i wywołaj metodę CreateTransactionalBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey);

Następnie dodaj wiele operacji do partii:

Product bike = new (
    id: "68719520766",
    category: "road-bikes",
    name: "Chropen Road Bike"
);

batch.CreateItem<Product>(bike);

Part part = new (
    id: "68719519885",
    category: "road-bikes",
    name: "Tronosuros Tire",
    productId: bike.id
);

batch.CreateItem<Part>(part);

Na koniec wywołaj metodę ExecuteAsync w partii:

using TransactionalBatchResponse response = await batch.ExecuteAsync();

Po odebraniu odpowiedzi sprawdź, czy odpowiedź zakończyła się pomyślnie. Jeśli odpowiedź wskazuje powodzenie, wyodrębnij wyniki:

if (response.IsSuccessStatusCode)
{
    TransactionalBatchOperationResult<Product> productResponse;
    productResponse = response.GetOperationResultAtIndex<Product>(0);
    Product productResult = productResponse.Resource;

    TransactionalBatchOperationResult<Part> partResponse;
    partResponse = response.GetOperationResultAtIndex<Part>(1);
    Part partResult = partResponse.Resource;
}

Ważne

Jeśli wystąpi błąd, operacja, która zakończyła się niepowodzeniem, będzie mieć kod stanu odpowiadającego mu błędu. Wszystkie pozostałe operacje będą miały kod stanu 424 (zależność nie powiodła się). Jeśli operacja nie powiedzie się, ponieważ próbuje utworzyć element, który już istnieje, zostanie zwrócony kod stanu 409 (konflikt). Kod stanu umożliwia zidentyfikowanie przyczyny niepowodzenia transakcji.

Java

Podczas tworzenia transakcyjnej operacji wsadowej wywołaj metodę CosmosBatch.createCosmosBatch:

PartitionKey partitionKey = new PartitionKey("road-bikes");

CosmosBatch batch = CosmosBatch.createCosmosBatch(partitionKey);

Następnie dodaj wiele operacji do partii:

Product bike = new Product();
bike.setId("68719520766");
bike.setCategory("road-bikes");
bike.setName("Chropen Road Bike");

batch.createItemOperation(bike);

Part part = new Part();
part.setId("68719519885");
part.setCategory("road-bikes");
part.setName("Tronosuros Tire");
part.setProductId(bike.getId());

batch.createItemOperation(part);

Na koniec użyj wystąpienia kontenera, aby wywołać metodę executeCosmosBatch z partią:

CosmosBatchResponse response = container.executeCosmosBatch(batch);

Po odebraniu odpowiedzi sprawdź, czy odpowiedź zakończyła się pomyślnie. Jeśli odpowiedź wskazuje powodzenie, wyodrębnij wyniki:

if (response.isSuccessStatusCode())
{
    List<CosmosBatchOperationResult> results = response.getResults();
}

Ważne

Jeśli wystąpi błąd, operacja, która zakończyła się niepowodzeniem, będzie mieć kod stanu odpowiadającego mu błędu. Wszystkie pozostałe operacje będą miały kod stanu 424 (zależność nie powiodła się). Jeśli operacja nie powiedzie się, ponieważ próbuje utworzyć element, który już istnieje, zostanie zwrócony kod stanu 409 (konflikt). Kod stanu umożliwia zidentyfikowanie przyczyny niepowodzenia transakcji.

Python

Pobierz lub utwórz wystąpienie kontenera:

container = database.create_container_if_not_exists(id="batch_container",
                                                        partition_key=PartitionKey(path='/category'))

W języku Python operacje transakcyjne usługi Batch wyglądają bardzo podobnie do pojedynczych interfejsów API operacji i są krotkami zawierającymi (operation_type_string, args_tuple, batch_operation_kwargs_dictionary). Poniżej przedstawiono przykładowe elementy, które będą używane do zademonstrowania funkcji operacji wsadowych:

create_demo_item = {
    "id": "68719520766",
    "category": "road-bikes",
    "name": "Chropen Road Bike"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item1 = {
    "id": "68719519884",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item2 = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, assume that this item already exists in the container. 
# the item id will be used for read operation in the batch
read_demo_item3 = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tire",
    "productId": "68719520766"
}

# for demo, we'll upsert the item with id 68719519885
upsert_demo_item = {
    "id": "68719519885",
    "category": "road-bikes",
    "name": "Tronosuros Tire Upserted",
    "productId": "68719520768"
}

# for replace demo, we'll replace the read_demo_item2 with this item
replace_demo_item = {
    "id": "68719519886",
    "category": "road-bikes",
    "name": "Tronosuros Tire replaced",
    "productId": "68719520769"
}

# for replace with etag match demo, we'll replace the read_demo_item3 with this item
# The use of etags and if-match/if-none-match options allows users to run conditional replace operations
# based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
# matches the passed in value. For more on optimistic concurrency control, see the link below:
# https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
replace_demo_item_if_match_operation = {
    "id": "68719519887",
    "category": "road-bikes",
    "name": "Tronosuros Tireh",
    "wasReplaced": "Replaced based on etag match"
    "productId": "68719520769"
}

Przygotuj operacje do dodania do partii:

create_item_operation = ("create", (create_demo_item,), {})
read_item_operation = ("read", ("68719519884",), {})
delete_item_operation = ("delete", ("68719519885",), {})
upsert_item_operation = ("upsert", (upsert_demo_item,), {})
replace_item_operation = ("replace", ("68719519886", replace_demo_item), {})
replace_item_if_match_operation = ("replace",
                                       ("68719519887", replace_demo_item_if_match_operation),
                                       {"if_match_etag": container.client_connection.last_response_headers.get("etag")})

Dodaj operacje do partii:

batch_operations = [
        create_item_operation,
        read_item_operation,
        delete_item_operation,
        upsert_item_operation,
        replace_item_operation,
        replace_item_if_match_operation
    ]

Na koniec wykonaj partię:

try:
    # Run that list of operations
    batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key="road_bikes")
    # Batch results are returned as a list of item operation results - or raise a CosmosBatchOperationError if
    # one of the operations failed within your batch request.
    print("\nResults for the batch operations: {}\n".format(batch_results))
except exceptions.CosmosBatchOperationError as e:
        error_operation_index = e.error_index
        error_operation_response = e.operation_responses[error_operation_index]
        error_operation = batch_operations[error_operation_index]
        print("\nError operation: {}, error operation response: {}\n".format(error_operation, error_operation_response))
    # [END handle_batch_error]

Uwaga dotycząca używania operacji poprawek i operacji replace_if_match_etag w partii
Słownik kwargs operacji wsadowej jest ograniczony i przyjmuje tylko trzy różne wartości klucza. W przypadku używania poprawek warunkowych w partii użycie klucza filter_predicate jest dostępne dla operacji stosowania poprawek lub w przypadku używania tagów etag z dowolną operacją użycie kluczy if_match_etag/if_none_match_etag.

batch_operations = [
       ("replace", (item_id, item_body), {"if_match_etag": etag}),
       ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
   ]

Ważne

Jeśli wystąpi błąd, operacja, która zakończyła się niepowodzeniem, będzie mieć kod stanu odpowiadającego mu błędu. Wszystkie pozostałe operacje będą miały kod stanu 424 (zależność nie powiodła się). Jeśli operacja nie powiedzie się, ponieważ próbuje utworzyć element, który już istnieje, zostanie zwrócony kod stanu 409 (konflikt). Kod stanu umożliwia zidentyfikowanie przyczyny niepowodzenia transakcji.

Jak są wykonywane transakcyjne operacje wsadowe

Po wykonaniu transakcyjnej partii wszystkie operacje w usłudze Transactional Batch są grupowane, serializowane w jednym ładunku i wysyłane jako pojedyncze żądanie do usługi Azure Cosmos DB.

Usługa odbiera żądanie i wykonuje wszystkie operacje w zakresie transakcyjnym i zwraca odpowiedź przy użyciu tego samego protokołu serializacji. Ta odpowiedź jest powodzeniem lub niepowodzeniem i dostarcza pojedyncze odpowiedzi operacji na operację.

Zestaw SDK uwidacznia odpowiedź, aby zweryfikować wynik i opcjonalnie wyodrębnić każdy z wyników operacji wewnętrznych.

Ograniczenia

Obecnie istnieją dwa znane limity:

• Limit rozmiaru żądania usługi Azure Cosmos DB ogranicza rozmiar ładunku usługi Batch transakcyjnego, który nie przekracza 2 MB, a maksymalny czas wykonywania wynosi 5 sekund.
• Obecnie istnieje limit 100 operacji na transakcyjną usługę Batch, aby upewnić się, że wydajność jest zgodnie z oczekiwaniami i w ramach umów SLA.

Następne kroki

• Dowiedz się więcej o tym, co można zrobić za pomocą transactionalBatch

• Odwiedź nasze przykłady , aby uzyskać więcej sposobów korzystania z naszego zestawu .NET SDK usługi Azure Cosmos DB