JsonPatch di API web ASP.NET Core

Artikel ini menjelaskan cara menangani permintaan JSON Patch di API web ASP.NET Core.

Penginstalan paket

Dukungan JSON Patch di API web ASP.NET Core didasarkan pada Newtonsoft.Json dan memerlukan Microsoft.AspNetCore.Mvc.NewtonsoftJson paket NuGet. Untuk mengaktifkan dukungan JSON Patch:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Instal paket NuGet.

• Panggil AddNewtonsoftJson. Contohnya:

  var builder = WebApplication.CreateBuilder(args);
  
  builder.Services.AddControllers()
      .AddNewtonsoftJson();
  
  var app = builder.Build();
  
  app.UseHttpsRedirection();
  
  app.UseAuthorization();
  
  app.MapControllers();
  
  app.Run();
  

AddNewtonsoftJson menggantikan pemformat input dan output berbasis default System.Text.Jsonyang digunakan untuk memformat semua konten JSON. Metode ekstensi ini kompatibel dengan metode pendaftaran layanan MVC berikut:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch memerlukan pengaturan Content-Type header ke application/json-patch+json.

Menambahkan dukungan untuk JSON Patch saat menggunakan System.Text.Json

Formatter System.Text.Jsoninput berbasis tidak mendukung JSON Patch. Untuk menambahkan dukungan untuk JSON Patch menggunakan Newtonsoft.Json, sambil membiarkan pemformat input dan output lainnya tidak berubah:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Instal paket NuGet.

• Perbarui Program.cs:

  using JsonPatchSample;
  using Microsoft.AspNetCore.Mvc.Formatters;
  
  var builder = WebApplication.CreateBuilder(args);
  
  builder.Services.AddControllers(options =>
  {
      options.InputFormatters.Insert(0, MyJPIF.GetJsonPatchInputFormatter());
  });
  
  var app = builder.Build();
  
  app.UseHttpsRedirection();
  
  app.UseAuthorization();
  
  app.MapControllers();
  
  app.Run();
  

  using Microsoft.AspNetCore.Mvc;
  using Microsoft.AspNetCore.Mvc.Formatters;
  using Microsoft.Extensions.Options;
  
  namespace JsonPatchSample;
  
  public static class MyJPIF
  {
      public static NewtonsoftJsonPatchInputFormatter GetJsonPatchInputFormatter()
      {
          var builder = new ServiceCollection()
              .AddLogging()
              .AddMvc()
              .AddNewtonsoftJson()
              .Services.BuildServiceProvider();
  
          return builder
              .GetRequiredService<IOptions<MvcOptions>>()
              .Value
              .InputFormatters
              .OfType<NewtonsoftJsonPatchInputFormatter>()
              .First();
      }
  }
  

Kode sebelumnya membuat instans NewtonsoftJsonPatchInputFormatter dan menyisipkannya sebagai entri pertama dalam MvcOptions.InputFormatters koleksi. Urutan pendaftaran ini memastikan bahwa:

• NewtonsoftJsonPatchInputFormatter memproses permintaan Patch JSON.
• Input dan formatter berbasis yang ada System.Text.Jsonmemproses semua permintaan dan respons JSON lainnya.

Newtonsoft.Json.JsonConvert.SerializeObject Gunakan metode untuk membuat JsonPatchDocumentserialisasi .

Metode permintaan HTTP PATCH

Metode PUT dan PATCH digunakan untuk memperbarui sumber daya yang ada. Perbedaannya adalah PUT menggantikan seluruh sumber daya, sementara PATCH hanya menentukan perubahan.

JSON Patch

JSON Patch adalah format untuk menentukan pembaruan yang akan diterapkan ke sumber daya. Dokumen JSON Patch memiliki array operasi. Setiap operasi mengidentifikasi jenis perubahan tertentu. Contoh perubahan tersebut termasuk menambahkan elemen array atau mengganti nilai properti.

Misalnya, dokumen JSON berikut mewakili sumber daya, dokumen Patch JSON untuk sumber daya, dan hasil penerapan operasi Patch.

Contoh sumber daya

{
  "customerName": "John",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    }
  ]
}

Contoh patch JSON

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Dalam JSON sebelumnya:

• Properti op menunjukkan jenis operasi.
• Properti path menunjukkan elemen yang akan diperbarui.
• Properti value menyediakan nilai baru.

Sumber daya setelah patch

Berikut adalah sumber daya setelah menerapkan dokumen Patch JSON sebelumnya:

{
  "customerName": "Barry",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    },
    {
      "orderName": "Order2",
      "orderType": null
    }
  ]
}

Perubahan yang dilakukan dengan menerapkan dokumen JSON Patch ke sumber daya adalah atomik. Jika ada operasi dalam daftar yang gagal, tidak ada operasi dalam daftar yang diterapkan.

Sintaksis jalur

Properti jalur objek operasi memiliki garis miring antar level. Contohnya,"/address/zipCode".

Indeks berbasis nol digunakan untuk menentukan elemen array. Elemen pertama dari addresses array akan berada di /addresses/0. Untuk add ke akhir array, gunakan tanda hubung (-) daripada nomor indeks: /addresses/-.

Operasional

Tabel berikut ini memperlihatkan operasi yang didukung seperti yang didefinisikan dalam spesifikasi Patch JSON:

Operasi	Catatan
add	Tambahkan elemen properti atau array. Untuk properti yang ada: tetapkan nilai.
remove	Menghapus elemen properti atau array.
replace	Sama seperti remove diikuti oleh add di lokasi yang sama.
move	Sama seperti remove dari sumber diikuti oleh add ke tujuan menggunakan nilai dari sumber.
copy	Sama seperti add tujuan menggunakan nilai dari sumber.
test	Mengembalikan kode status keberhasilan jika nilai di path = disediakan value.

Patch JSON di ASP.NET Core

Implementasi ASP.NET Core dari JSON Patch disediakan dalam paket NuGet Microsoft.AspNetCore.JsonPatch .

Kode metode tindakan

Dalam pengontrol API, metode tindakan untuk JSON Patch:

• Diannotasikan dengan HttpPatch atribut .
• JsonPatchDocument<TModel>Menerima , biasanya dengan [FromBody].
• ApplyTo(Object) Panggilan pada dokumen patch untuk menerapkan perubahan.

Berikut contohnya:

[HttpPatch]
public IActionResult JsonPatchWithModelState(
    [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    if (patchDoc != null)
    {
        var customer = CreateCustomer();

        patchDoc.ApplyTo(customer, ModelState);

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        return new ObjectResult(customer);
    }
    else
    {
        return BadRequest(ModelState);
    }
}

Kode dari aplikasi sampel ini berfungsi dengan model berikut Customer :

namespace JsonPatchSample.Models;

public class Customer
{
    public string? CustomerName { get; set; }
    public List<Order>? Orders { get; set; }
}

namespace JsonPatchSample.Models;

public class Order
{
    public string OrderName { get; set; }
    public string OrderType { get; set; }
}

Metode tindakan sampel:

• Membangun sebuah Customer.
• Menerapkan patch.
• Mengembalikan hasil dalam isi respons.

Dalam aplikasi nyata, kode akan mengambil data dari penyimpanan seperti database dan memperbarui database setelah menerapkan patch.

Status model

Contoh metode tindakan sebelumnya memanggil kelebihan beban ApplyTo yang mengambil status model sebagai salah satu parameternya. Dengan opsi ini, Anda bisa mendapatkan pesan kesalahan sebagai respons. Contoh berikut menunjukkan isi respons Permintaan Buruk 400 untuk test operasi:

{
  "Customer": [
    "The current value 'John' at path 'customerName' != test value 'Nancy'."
  ]
}

Objek dinamis

Contoh metode tindakan berikut menunjukkan cara menerapkan patch ke objek dinamis:

[HttpPatch]
public IActionResult JsonPatchForDynamic([FromBody]JsonPatchDocument patch)
{
    dynamic obj = new ExpandoObject();
    patch.ApplyTo(obj);

    return Ok(obj);
}

Operasi tambahkan

• Jika path menunjuk ke elemen array: menyisipkan elemen baru sebelum elemen yang ditentukan oleh path.
• Jika path menunjuk ke properti: mengatur nilai properti.
• Jika path menunjuk ke lokasi yang tidak ada:
  • Jika sumber daya yang akan di-patch adalah objek dinamis: menambahkan properti.
  • Jika sumber daya untuk di-patch adalah objek statis: permintaan gagal.

Contoh dokumen patch berikut mengatur nilai CustomerName dan menambahkan Order objek ke akhir Orders array.

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Operasi hapus

• Jika path menunjuk ke elemen array: menghapus elemen .
• Jika path menunjuk ke properti:
  • Jika sumber daya untuk patch adalah objek dinamis: menghapus properti .
  • Jika sumber daya untuk di-patch adalah objek statis:
    • Jika properti nullable: mengaturnya ke null.
    • Jika properti tidak dapat diubah ke null, atur ke default<T>.

Contoh kumpulan CustomerName dokumen patch berikut ke null dan hapus Orders[0]:

[
  {
    "op": "remove",
    "path": "/customerName"
  },
  {
    "op": "remove",
    "path": "/orders/0"
  }
]

Operasi ganti

Operasi ini secara fungsional sama remove dengan diikuti oleh add.

Contoh dokumen patch berikut menetapkan nilai CustomerName dan mengganti Orders[0]dengan objek baru Order :

[
  {
    "op": "replace",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "replace",
    "path": "/orders/0",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

Operasi pemindahan

• Jika path menunjuk ke elemen array: menyalin from elemen ke lokasi path elemen, maka menjalankan remove operasi pada from elemen .
• Jika path menunjuk ke properti: menyalin nilai from properti ke path properti, maka menjalankan remove operasi pada from properti .
• Jika path menunjuk ke properti yang tidak ada:
  • Jika sumber daya untuk di-patch adalah objek statis: permintaan gagal.
  • Jika sumber daya untuk patch adalah objek dinamis: menyalin from properti ke lokasi yang remove ditunjukkan oleh path, maka menjalankan operasi pada from properti .

Contoh dokumen patch berikut:

• Menyalin nilai Orders[0].OrderName ke CustomerName.
• Orders[0].OrderName Mengatur ke null.
• Orders[1] Pindah ke sebelum Orders[0].

[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operasi salin

Operasi ini secara fungsional sama move dengan operasi tanpa langkah terakhir remove .

Contoh dokumen patch berikut:

• Menyalin nilai Orders[0].OrderName ke CustomerName.
• Menyisipkan salinan Orders[1] sebelum Orders[0].

[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

Operasi pengujian

Jika nilai di lokasi yang ditunjukkan oleh path berbeda dari nilai yang disediakan dalam value, permintaan gagal. Dalam hal ini, seluruh permintaan PATCH gagal bahkan jika semua operasi lain dalam dokumen patch akan berhasil.

Operasi test ini umumnya digunakan untuk mencegah pembaruan ketika ada konflik konkurensi.

Contoh dokumen patch berikut tidak berpengaruh jika nilai CustomerName awal adalah "John", karena pengujian gagal:

[
  {
    "op": "test",
    "path": "/customerName",
    "value": "Nancy"
  },
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  }
]

Mendapatkan kode

Melihat atau mengunduh kode sampel. (Cara mengunduh).

Untuk menguji sampel, jalankan aplikasi dan kirim permintaan HTTP dengan pengaturan berikut:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metode HTTP: PATCH
• Header: Content-Type: application/json-patch+json
• Isi: Salin dan tempel salah satu sampel dokumen patch JSON dari folder proyek JSON .

Sumber Daya Tambahan:

• Spesifikasi metode IETF RFC 5789 PATCH
• Spesifikasi IETF RFC 6902 JSON Patch
• IETF RFC 6901 JSON Pointer
• Dokumentasi Patch JSON. Menyertakan tautan ke sumber daya untuk membuat dokumen JSON Patch.
• ASP.NET kode sumber Core JSON Patch