Udostępnij za pośrednictwem

Wprowadzenie do częściowej aktualizacji dokumentu usługi Azure Cosmos DB

  • Artykuł

DOTYCZY: NoSQL

Ten artykuł zawiera przykłady ilustrujące sposób używania częściowej aktualizacji dokumentu z zestawami SDK platformy .NET, Java i node. Opisano w nim również typowe błędy, które mogą wystąpić.

Ten artykuł zawiera linki do przykładów kodu dla następujących scenariuszy:

  • Uruchamianie pojedynczej operacji stosowania poprawek
  • Łączenie wielu operacji poprawek
  • Używanie składni poprawki warunkowej na podstawie predykatu filtru
  • Uruchamianie operacji stosowania poprawek w ramach transakcji

Wymagania wstępne

Obsługa częściowej aktualizacji dokumentu (interfejs API poprawek) w zestawie SDK platformy .NET w wersji 3 usługi Azure Cosmos DB jest dostępna od wersji 3.23.0. Możesz pobrać go z galerii NuGet.

Uwaga

Znajdź kompletny przykład częściowej aktualizacji dokumentu w repozytorium przykładów platformy .NET w wersji 3 w witrynie GitHub.

  • Uruchom pojedynczą operację stosowania poprawek:

    ItemResponse<Product> response = await container.PatchItemAsync<Product>(
    id: "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: new[] {
        PatchOperation.Replace("/price", 355.45)
    }
);

Product updated = response.Resource;

  • Łączenie wielu operacji poprawek:

    List<PatchOperation> operations = new ()
{
    PatchOperation.Add("/color", "silver"),
    PatchOperation.Remove("/used"),
    PatchOperation.Increment("/price", 50.00),
    PatchOperation.Add("/tags/-", "featured-bikes")
};

ItemResponse<Product> response = await container.PatchItemAsync<Product>(
    id: "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: operations
);

  • Użyj składni poprawki warunkowej na podstawie predykatu filtru:

    PatchItemRequestOptions options = new()
{
    FilterPredicate = "FROM products p WHERE p.used = false"
};

List<PatchOperation> operations = new ()
{
    PatchOperation.Replace($"/price", 100.00),
};

ItemResponse<Product> response = await container.PatchItemAsync<Product>(
    id: "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: operations,
    requestOptions: options
);

  • Uruchom operację stosowania poprawek w ramach transakcji:

    TransactionalBatchPatchItemRequestOptions options = new()
{
    FilterPredicate = "FROM products p WHERE p.used = false"
};

List<PatchOperation> operations = new ()
{
    PatchOperation.Add($"/new", true),
    PatchOperation.Remove($"/used")
};

TransactionalBatch batch = container.CreateTransactionalBatch(
    partitionKey: new PartitionKey("road-bikes")
);
batch.PatchItem(
    id: "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
    patchOperations: operations,
    requestOptions: options
);
batch.PatchItem(
    id: "892f609b-8885-44df-a9ed-cce6c0bd2b9e",
    patchOperations: operations,
    requestOptions: options
);

TransactionalBatchResponse response = await batch.ExecuteAsync();
bool success = response.IsSuccessStatusCode;

Obsługa programowania po stronie serwera

Operacje częściowej aktualizacji dokumentu można również wykonywać po stronie serwera przy użyciu procedur składowanych, wyzwalaczy i funkcji zdefiniowanych przez użytkownika.

this.patchDocument = function (documentLink, patchSpec, options, callback) {
    if (arguments.length < 2) {
        throw new Error(ErrorCodes.BadRequest, sprintf(errorMessages.invalidFunctionCall, 'patchDocument', 2, arguments.length));
    }
    if (patchSpec === null || !(typeof patchSpec === "object" || Array.isArray(patchSpec))) {
        throw new Error(ErrorCodes.BadRequest, errorMessages.patchSpecMustBeObjectOrArray);
    }

    var documentIdTuple = validateDocumentLink(documentLink, false);
    var collectionRid = documentIdTuple.collId;
    var documentResourceIdentifier = documentIdTuple.docId;
    var isNameRouted = documentIdTuple.isNameRouted;

    patchSpec = JSON.stringify(patchSpec);
    var optionsCallbackTuple = validateOptionsAndCallback(options, callback);

    options = optionsCallbackTuple.options;
    callback = optionsCallbackTuple.callback;

    var etag = options.etag || '';
    var indexAction = options.indexAction || '';

    return collectionObjRaw.patch(
        collectionRid,
        documentResourceIdentifier,
        isNameRouted,
        patchSpec,
        etag,
        indexAction,
        function (err, response) {
            if (callback) {
                if (err) {
                    callback(err);
                } else {
                    callback(undefined, JSON.parse(response.body), response.options);
                }
            } else {
                if (err) {
                    throw err;
                }
            }
        }
    );
};

Uwaga

Znajdź definicję validateOptionsAndCallback w .js DocDbWrapperScript w witrynie GitHub.

Przykładowa procedura składowana dla operacji stosowania poprawek:

function patchDemo() {
    var doc = {
        "id": "exampleDoc",
        "fields": {
            "field1": "exampleString",
            "field2": 20,
            "field3": 40
        }
    };
    
    var isAccepted = __.createDocument(__.getSelfLink(), doc, (err, doc) => {
        if (err) {
            throw err;
        }
        else {
            getContext().getResponse().setBody("Example document successfully created.");
            
            var patchSpec = [
                { "op": "add", "path": "/fields/field1", "value": "newExampleString" },
                { "op": "remove", "path": "/fields/field2" },
                { "op": "incr", "path": "/fields/field3", "value": 10 }
            ];
            
            var isAccepted = __.patchDocument(doc._self, patchSpec, (err, doc) => {
                if (err) {
                    throw err;
                }
                else {
                    getContext().getResponse().appendBody(" Example document successfully patched.");
                }
            });
            
            if (!isAccepted) throw new Error("Patch wasn't accepted");
        }
    });

    if (!isAccepted) throw new Error("Create wasn't accepted.");
}

Rozwiązywanie problemów

Poniżej przedstawiono niektóre typowe błędy, które mogą wystąpić podczas korzystania z tej funkcji:

Komunikat o błędzie Opis
Nieprawidłowe żądanie poprawki: sprawdź składnię specyfikacji poprawki. Składnia operacji patch jest nieprawidłowa. Aby uzyskać więcej informacji, zobacz specyfikację częściowej aktualizacji dokumentu.
Nieprawidłowe żądanie poprawki: nie można zastosować poprawek właściwości SYSTEM_PROPERTYsystemu . Właściwości generowane przez system, takie jak _id, _ts, _rid _etagnie są modyfikowalne przy użyciu operacji stosowania poprawek. Aby uzyskać więcej informacji, zobacz Częściowa aktualizacja dokumentu — często zadawane pytania.
Liczba operacji poprawek nie może przekraczać 10. Istnieje limit 10 operacji poprawek, które można dodać w jednej specyfikacji poprawki. Aby uzyskać więcej informacji, zobacz Częściowa aktualizacja dokumentu — często zadawane pytania.
W przypadku operacji(PATCH_OPERATION_INDEX): indeks(ARRAY_INDEX) do działania jest poza granicami tablicy. Indeks elementu tablicy, który ma zostać poprawiony, jest poza granicami.
W przypadku operacji()): element Node(PATCH_OPERATION_INDEXPATH) do zastąpienia został usunięty wcześniej w transakcji. Ścieżka, którą próbujesz zastosować poprawki, nie istnieje.
W przypadku operacji (PATCH_OPERATION_INDEX): węzełPATH() do usunięcia jest nieobecny. Uwaga: mogła zostać również usunięta wcześniej w transakcji.  Ścieżka, którą próbujesz zastosować poprawki, nie istnieje.
W przypadku operacji (): element Node(PATCH_OPERATION_INDEXPATH) do zastąpienia jest nieobecny. Ścieżka, którą próbujesz zastosować poprawki, nie istnieje.
W przypadku operacji(): Node(PATCH_OPERATION_INDEXPATH) nie jest liczbą. Operacja przyrostu może działać tylko na liczbach całkowitych i zmiennoprzecinkowych. Aby uzyskać więcej informacji, zobacz: Obsługiwane operacje.
W przypadku operacji (PATCH_OPERATION_INDEX): Operacja dodawania może utworzyć tylko obiekt podrzędny istniejącego węzła (tablicy lub obiektu) i nie może utworzyć ścieżki rekursywnie, nie można odnaleźć ścieżki poza: PATH. Ścieżki podrzędne można dodać do typu obiektu lub węzła tablicy. Ponadto, aby utworzyć nth podrzędne, n-1element podrzędny powinien być obecny.
W przypadku operacji (PATCH_OPERATION_INDEX): Dana operacja może utworzyć tylko obiekt podrzędny istniejącego węzła (tablicy lub obiektu) i nie może utworzyć ścieżki rekursywnie, nie można odnaleźć ścieżki poza: PATH. Ścieżki podrzędne można dodać do typu obiektu lub węzła tablicy. Ponadto, aby utworzyć nth podrzędne, n-1element podrzędny powinien być obecny.

Następne kroki