Condividi tramite

Attività iniziai dell’aggiornamento parziale dei documenti di Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL

Questo articolo fornisce esempi che descrivono come usare l'aggiornamento parziale dei documenti con .NET, Java e Node SDK. Inoltre descrive gli errori comuni che potrebbero verificarsi.

Questo articolo include collegamenti a esempi di codice per gli scenari seguenti:

  • Eseguire una singola operazione di patch
  • Combinare più operazioni di patch
  • Usare la sintassi delle patch condizionale in base al predicato di filtro
  • Eseguire l'operazione patch come parte di una transazione

Prerequisiti

Il supporto per l'aggiornamento parziale dei documenti (API Patch) in Azure Cosmos DB .NET v3 SDK è disponibile a partire dalla versione 3.23.0. È possibile scaricarlo dalla raccolta NuGet.

Nota

Trovare un campione completo di Aggiornamento dei documenti parziale nel repository di campioni .NET v3 in GitHub.

  • Eseguire una singola operazione di patch:

    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;

  • Combinare più operazioni di patch:

    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
);

  • Usare la sintassi delle patch condizionale in base al predicato di filtro:

    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
);

  • Eseguire l'operazione patch come parte di una transazione:

    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;

Supporto per la programmazione lato server

Le operazioni di aggiornamento parziale dei documenti possono essere eseguite anche sul lato server usando stored procedure, trigger e funzioni definite dall'utente.

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;
                }
            }
        }
    );
};

Nota

Trovare la definizione di validateOptionsAndCallback in .js DocDbWrapperScript in GitHub.

Stored procedure di esempio per l'operazione patch:

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.");
}

Risoluzione dei problemi

Ecco alcuni errori comuni che potrebbero verificarsi durante l'uso di questa funzionalità:

Messaggio di errore Descrizione
Richiesta patch non valida: controllare la sintassi della specifica della patch. La sintassi dell'operazione di patch non è valida. Per altre informazioni, vedere specifica dell'aggiornamento parziale dei documenti.
Richiesta patch non valida: non è possibile applicare patch alla proprietà di sistema SYSTEM_PROPERTY. Le proprietà generate dal sistema quali _id,_ts, _etag e _rid non sono modificabili tramite un'operazione di patch. Per altre informazioni, vedere Domande frequenti sull'aggiornamento parziale dei documenti.
Non è possibile superare 10 operazioni patch. È previsto un limite di 10 operazioni di patch che è possibile aggiungere in una singola specifica di patch. Per altre informazioni, vedere Domande frequenti sull'aggiornamento parziale dei documenti.
Per Operazione(PATCH_OPERATION_INDEX): indice(ARRAY_INDEX) su cui operare è fuori dai limiti di array. L'indice dell'elemento di matrice cui applicare la patch è fuori intervallo.
Per Operazione(PATCH_OPERATION_INDEX)): nodo(PATH) da sostituire è stato rimosso in precedenza nella transazione. Il percorso cui si sta tentando di applicare patch non esiste.
Per Operazione(PATCH_OPERATION_INDEX): nodo(PATH) da rimuovere è assente. Nota: potrebbe anche essere stato rimosso in precedenza nella transazione.  Il percorso cui si sta tentando di applicare patch non esiste.
Per Operazione(PATCH_OPERATION_INDEX): nodo(PATH) da sostituire è assente. Il percorso cui si sta tentando di applicare patch non esiste.
Per Operazione(PATCH_OPERATION_INDEX): nodo(PATH) non è un numero. L'operazione di incremento può funzionare solo su integer e float. Per altre informazioni, vedere Operazioni supportate.
Per Operazione(PATCH_OPERATION_INDEX): Add Operation può creare solo un oggetto figlio di un nodo esistente (array o oggetto) e non può creare il percorso in modo ricorsivo, nessun percorso trovato oltre: PATH. I percorsi figlio possono essere aggiunti a un tipo di nodo oggetto o matrice. Inoltre, per creare il n° figlio, deve essere presente il n-1° figlio.
Per Operazione(PATCH_OPERATION_INDEX): l'operazione specificata può creare solo un oggetto figlio di un nodo esistente (matrice o oggetto) e non può creare il percorso in modo ricorsivo, nessun percorso trovato oltre: PATH. I percorsi figlio possono essere aggiunti a un tipo di nodo oggetto o matrice. Inoltre, per creare il n° figlio, deve essere presente il n-1° figlio.

Passaggi successivi