Aracılığıyla paylaş

Azure Cosmos DB kısmi belge güncelleştirmesini kullanmaya başlama

  • Şunlara uygulanır: ✅ NoSQL

Bu makalede .NET, Java ve Node SDK'ları ile kısmi belge güncelleştirmesinin nasıl kullanılacağını gösteren örnekler sağlanmaktadır. Ayrıca karşılaşabileceğiniz yaygın hataları da açıklar.

Bu makale, aşağıdaki senaryolar için kod örneklerine bağlantı sağlar:

  • Tek bir yama işlemi gerçekleştirme
  • Birden çok düzeltme eki işlemini birleştirin
  • Filtre önermesine dayalı koşullu yama söz dizimini kullan.
  • İşlemin bir parçası olarak yama işlemini çalıştırma

Prerequisites

Kısmi belge güncelleştirmesini kullanma

Azure Cosmos DB .NET v3 SDK'sında kısmi belge güncelleştirmesi (Patch API) desteği 3.23.0 ve sonraki sürümlerde kullanılabilir. Paketi NuGet galerisinden indirebilirsiniz.

Note

GitHub'daki .NET v3 örnekleri deposunda tam bir kısmi belge güncelleştirme örneği bulun.

  • Tek bir düzeltme eki işlemi yapın:

    ItemResponse<Product> response = await container.PatchItemAsync<Product>(
    id: "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: new[] {
        PatchOperation.Replace("/price", 355.45)
    }
);

Product updated = response.Resource;

  • Birden çok yama işlemini birleştirin.

    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: "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: operations
);

  • Filtre önermesine göre koşullu yama söz dizimini kullanın.

    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: "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
    partitionKey: new PartitionKey("road-bikes"),
    patchOperations: operations,
    requestOptions: options
);

  • Düzeltme eki işlemini bir işlemin parçası olarak çalıştırın:

    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: "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
    patchOperations: operations,
    requestOptions: options
);
batch.PatchItem(
    id: "f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
    patchOperations: operations,
    requestOptions: options
);

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

Sunucu tarafı programlama desteği

Kısmi belge güncelleştirme işlemleri saklı yordamlar, tetikleyiciler ve kullanıcı tanımlı işlevler kullanılarak sunucu tarafında da yürütülebilir .

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

Note

öğesinin tanımını validateOptionsAndCallback GitHub'daki .js DocDbWrapperScript'te bulabilirsiniz.

Düzeltme eki işlemi için örnek saklı yordam:

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

Troubleshooting

Bu özelliği kullanırken karşılaşabileceğiniz bazı yaygın hatalar şunlardır:

Hata iletisi Description
Geçersiz düzeltme eki isteği: Düzeltme eki belirtiminin söz dizimini denetleyin. Patch işlemi söz dizimi geçersiz. Daha fazla bilgi edinmek için belirtim bölümüne bakın.
Geçersiz düzeltme eki isteği: Sistem özelliği SYSTEM_PROPERTY düzeltilemez. _id, _ts, _etag, _rid gibi sistem tarafından oluşturulan özellikler bir düzeltme eki işlemi kullanılarak değiştirilemez. Daha fazla bilgi edinmek için bkz. kısmi belge güncelleştirmesi hakkında SSS.
Düzeltme eki işlemlerinin sayısı 10'u aşamaz. Tek bir yama tanımına en fazla 10 yama işlemi eklenebilir. Daha fazla bilgi edinmek için bkz. kısmi belge güncelleştirmesi hakkında SSS.
İşlem(PATCH_OPERATION_INDEX): İşlem yapılacak dizin(ARRAY_INDEX) dizi sınırlarının dışında. Yama yapılacak dizi öğesinin dizini sınırların dışında.
İşlem(PATCH_OPERATION_INDEX)): Değiştirilecek düğümler,PATH işlemde daha önce kaldırıldı. Yama yapmak istediğiniz yol mevcut değil.
İşlem(PATCH_OPERATION_INDEX): Kaldırılacak düğüm(PATH) mevcut değil. Not: İşlemde daha önce kaldırılmış da olabilir.  Yama yapmak istediğiniz yol mevcut değil.
İşlem(PATCH_OPERATION_INDEX): Değiştirilecek düğüm(PATH) mevcut değil. Yama yapmak istediğiniz yol mevcut değil.
İşlem(PATCH_OPERATION_INDEX): Node(PATH) bir sayı değildir. Artırma işlemi yalnızca tamsayı ve kayan değer üzerinde çalışabilir. Daha fazla bilgi için bkz . Desteklenen işlemler.
İşlem(PATCH_OPERATION_INDEX): Ekleme işlemi yalnızca var olan bir düğümün alt nesnesini (dizi veya nesne) oluşturabilir ve özyinelemeli olarak yol oluşturamaz; dışında hiçbir yol bulunamadı: PATH. Çocuk yollar bir nesne veya dizi düğümüne eklenebilir. Ayrıca, n. çocuğu oluşturmak için, n-1. çocuğun mevcut olması gerekir.
İşlem(PATCH_OPERATION_INDEX): Verilen işlem yalnızca var olan bir düğümün alt nesnesini (dizi veya nesne) oluşturabilir ve özyinelemeli olarak yol oluşturamaz; dışında hiçbir yol bulunamadı: PATH. Çocuk yollar bir nesne veya dizi düğümüne eklenebilir. Ayrıca, n. çocuğu oluşturmak için, n-1. çocuğun mevcut olması gerekir.

Sonraki adım

  • Last updated on