Transakcyjne operacje grupowe w usłudze Azure Cosmos DB

2025-07-08

DOTYCZY: NoSQL

Partia transakcyjna opisuje grupę operacji punktowych, które muszą zakończyć się powodzeniem lub niepowodzeniem z takim samym kluczem partycji w obrębie kontenera. 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 i albo wszystkie są zatwierdzone, albo żadna nie jest.
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ą migawkową dla operacji w ramach tego samego klucza partycji logicznej.

Operacje wsadowe oraz procedury utrwalone w transakcjach

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ęzykowa — transakcyjna partia jest obsługiwana w SDK i języku, z którego korzystasz, podczas gdy procedury składowane muszą być napisane w języku JavaScript.
Wersjonowanie kodu — wersjonowanie kodu aplikacji i wdrażanie go do potoku CI/CD jest znacznie bardziej naturalne niż organizowanie aktualizacji procedury składowanej i upewnienie się, że przełączenie 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 danych.

Jak utworzyć operację transakcyjną zbiorczą

Podczas tworzenia transakcyjnej operacji wsadowej rozpocznij od instancji 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 (niepowodzenie zależności). 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.

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

Pobierz lub utwórz instancję 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:
# /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 pakietu.

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ę zadań:

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 patchowania i operacji replace_if_match_etag w operacjach wsadowych
Słownik kwargs operacji wsadowej jest ograniczony i przyjmuje tylko trzy różne wartości klucza. W przypadku chęci użycia poprawek warunkowych w partii dostępne jest użycie klucza filter_predicate dla operacji stosowania poprawek. Jeśli chcesz użyć etykiet etag z dowolną operacją, dostępne jest również 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

Podczas tworzenia transakcyjnej operacji wsadowej wywołaj metodę NewTransactionalBatch.

pk := azcosmos.NewPartitionKeyString("road-bikes")

batch := container.NewTransactionalBatch(pk)

Następnie dodaj wiele operacji do partii:

type Bike struct {
	ID       string `json:"id"`
	Category string `json:"category"`
	Name     string `json:"name"`
}

bike := Bike{ID: "68719520766", Category: "road-bikes", Name: "Chropen Road Bike"}
bikeItem, _ := json.Marshal(bike)

batch.CreateItem(bikeItem, nil)

type BikePart struct {
	ID        string `json:"id"`
	Category  string `json:"category"`
	Name      string `json:"name"`
	ProductID string `json:"productID"`
}

part := BikePart{ID: "68719519885", Category: "road-bikes", Name: "Tronosuros Tire", ProductID: bike.ID}
bikePartItem, _ := json.Marshal(part)

batch.CreateItem(bikePartItem, nil)

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

resp, _ := container.ExecuteTransactionalBatch(context.Background(), batch, nil)

if resp.Success {
	// execute conditional logic
}

Ważne

Jak są wykonywane transakcyjne operacje wsadowe

Po wykonaniu transakcyjnej partii, wszystkie operacje w transakcyjnej partii są grupowane, serializowane w jeden pakiet danych 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ź może być sukcesem lub porażką i dostarcza indywidualne odpowiedzi dla każdej operacji.

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 transakcyjny Batch, aby zapewnić, że wydajność jest zgodna z oczekiwaniami i odpowiada standardom SLA.

Następny krok

TransactionalBatch użytkowanie

Udostępnij za pośrednictwem

Transakcyjne operacje grupowe w usłudze Azure Cosmos DB

Co to jest transakcja w usłudze Azure Cosmos DB

Operacje wsadowe oraz procedury utrwalone w transakcjach

Jak utworzyć operację transakcyjną zbiorczą

Jak są wykonywane transakcyjne operacje wsadowe

Ograniczenia

Następny krok

Opinia

Dodatkowe zasoby