Bagikan melalui

Mulai menggunakan pembaruan dokumen parsial Azure Cosmos DB

  • Berlaku untuk: ✅ NoSQL

Artikel ini menyediakan contoh yang menggambarkan cara menggunakan pembaruan dokumen parsial dengan .NET, Java, dan Node SDK. Ini juga menjelaskan kesalahan umum yang mungkin Anda temui.

Artikel ini menautkan ke sampel kode untuk skenario berikut:

  • Jalankan operasi patch tunggal
  • Menggabungkan beberapa operasi patch
  • Menggunakan sintaks patch kondisional berdasarkan predikat filter
  • Menjalankan operasi patch sebagai bagian dari transaksi

Prerequisites

  • Akun Azure Cosmos DB yang sudah ada.
    • Jika Anda memiliki langganan Azure, buat akun baru.
    • Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.

Menggunakan pembaruan dokumen parsial

Dukungan untuk pembaruan dokumen parsial (Patch API) di Azure Cosmos DB .NET v3 SDK tersedia di versi 3.23.0 dan yang lebih baru. Anda dapat mengunduh paket dari galeri NuGet.

Note

Temukan sampel pembaruan dokumen parsial lengkap di repositori sampel .NET v3 di GitHub.

  • Jalankan operasi patch tunggal:

    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;

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

  • Gunakan sintaks patch kondisional berdasarkan predikat filter:

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

  • Jalankan operasi patch sebagai bagian dari transaksi:

    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;

Dukungan untuk pemrograman sisi server

Operasi pembaruan dokumen parsial juga dapat dijalankan di sisi server dengan menggunakan prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna.

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

Temukan definisi validateOptionsAndCallback dalam .js DocDbWrapperScript di GitHub.

Contoh prosedur tersimpan untuk operasi 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.");
}

Troubleshooting

Berikut adalah beberapa kesalahan umum yang mungkin Anda temui saat menggunakan fitur ini:

Pesan kesalahan Description
Permintaan patch tidak valid: periksa sintaks spesifikasi patch. Sintaks operasi patch bersifat tidak valid. Untuk mempelajari lebih lanjut, lihat spesifikasinya.
Permintaan patch tidak valid: Tidak dapat melakukan patch properti sistem SYSTEM_PROPERTY. Properti yang dihasilkan sistem seperti _id, _ts, _etag, _rid tidak dapat dimodifikasi menggunakan operasi patch. Untuk mempelajari selengkapnya, lihat FAQ pembaruan dokumen parsial.
Jumlah operasi patch tidak boleh melebihi 10. Ada batas 10 operasi patch yang dapat ditambahkan dalam satu spesifikasi patch. Untuk mempelajari selengkapnya, lihat FAQ pembaruan dokumen parsial.
Untuk Operasi(PATCH_OPERATION_INDEX): Indeks(ARRAY_INDEX) yang akan dioperasikan berada di luar batas array. Indeks elemen array yang akan di-patch berada di luar batas.
Untuk Operasi(PATCH_OPERATION_INDEX)): Node(PATH) yang akan diganti dihapus sebelumnya dalam transaksi. Jalur yang Anda coba patch tidak ada.
Untuk Operasi(PATCH_OPERATION_INDEX): Node(PATH) yang akan dihapus tidak ditemukan. Catatan: mungkin juga telah dihapus sebelumnya dalam transaksi.  Jalur yang Anda coba patch tidak ada.
For Operation(PATCH_OPERATION_INDEX): Node(PATH) yang akan diganti tidak ada. Jalur yang Anda coba patch tidak ada.
Untuk Operasi(PATCH_OPERATION_INDEX): Simpul(PATH) bukan berupa angka. Operasi peningkatan hanya dapat bekerja pada bilangan bulat dan bilangan pecahan. Untuk informasi selengkapnya, lihat Operasi yang didukung.
Untuk Operasi(PATCH_OPERATION_INDEX): Penambahan operasi hanya dapat membuat objek turunan dari simpul yang sudah ada (array atau objek) dan tidak dapat membuat jalur secara rekursif, tidak ada jalur yang ditemukan di luar:PATH. Jalur anak dapat ditambahkan ke node jenis objek atau array. Selain itu, untuk membuat anak ke-n, anak ke-n-1 harus sudah ada.
Untuk Operasi(PATCH_OPERATION_INDEX): Operasi yang diberikan hanya dapat membuat objek anak dari simpul (array atau objek) yang ada dan tidak dapat membuat jalur secara rekursif, tidak ada jalur yang ditemukan di luar: PATH. Jalur anak dapat ditambahkan ke node jenis objek atau array. Selain itu, untuk membuat anak ke-n, anak ke-n-1 harus sudah ada.

Langkah selanjutnya

  • Last updated on