ASP.NET Core web API'de JSON Patch'in desteklenmesi

Bu makalede, ASP.NET Core web API'sinde JSON Düzeltme Eki isteklerinin nasıl işleneceğini açıklanmaktadır.

ASP.NET Core web API'de JSON Yaması desteği, System.Text.Json serileştirmesine dayanır ve Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet paketini gerektirir.

JSON Patch standardı nedir?

JSON Patch standardı:

• JSON belgesine uygulanacak değişiklikleri açıklamaya yönelik standart bir biçimdir.

• RFC 6902'de tanımlanır ve JSON kaynaklarında kısmi güncelleştirmeler gerçekleştirmek için RESTful API'lerinde yaygın olarak kullanılır.

• Aşağıdakiler gibi bir JSON belgesini değiştiren işlem dizisini açıklar:

  • add
  • remove
  • replace
  • move
  • copy
  • test

Web uygulamalarında JSON Patch genellikle bir kaynağın kısmi güncelleştirmelerini gerçekleştirmek için PATCH işleminde kullanılır. İstemciler, bir güncelleştirme için kaynağın tamamını göndermek yerine yalnızca değişiklikleri içeren bir JSON Düzeltme Eki belgesi gönderebilir. Yama yapmak, yük boyutunu azaltır ve verimliliği artırır.

JSON Düzeltme Eki standardına genel bakış için bkz. jsonpatch.com.

ASP.NET Core web API'de JSON Patch'in desteklenmesi

ASP.NET Core web API'sindeki JSON Düzeltme Eki desteği, .NET 10'dan başlayarak System.Text.Json serileştirmeyi temel alır. Microsoft.AspNetCore.JsonPatch, System.Text.Json serileştirmesine dayalı olarak uygulanır. Bu özellik:

• Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet paketini gerektirir.
• Modern .NET uygulamalarıyla uyumlu olan System.Text.Json kitaplığı, .NET için optimize edilmiştir.
• Eski Newtonsoft.Jsontabanlı uygulamaya kıyasla daha iyi performans ve azaltılmış bellek kullanımı sağlar. Eski Newtonsoft.Jsontabanlı uygulama hakkında daha fazla bilgi için bu makalenin .NET 9 sürümüne bakın.

Note

Microsoft.AspNetCore.JsonPatch serileştirmesine dayalı System.Text.Json uygulaması, eski Newtonsoft.Json tabanlı uygulamanın doğrudan bir ikamesi değildir. gibi ExpandoObjectdinamik türleri desteklemez.

Important

JSON Patch standardının doğal güvenlik riskleri vardır. Bu riskler JSON Patch standardına bağlı olduğundan, ASP.NET Core uygulaması doğal güvenlik risklerini azaltmaya çalışmaz. JSON Patch belgesinin hedef nesneye uygulanmasının güvenli olduğundan emin olmak geliştiricinin sorumluluğundadır. Daha fazla bilgi için Güvenlik Risklerini Azaltma bölümüne bakın.

JSON Düzeltme Eki desteğini System.Text.Json ile etkinleştirin

JSON Yaması desteğini System.Text.Json etkinleştirmek için Microsoft.AspNetCore.JsonPatch.SystemTextJson NuGet paketini yükleyin.

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson

Bu paket, JsonPatchDocument<TModel> sınıfını, TModel türü nesneler için JSON Patch belgesini temsil etmek üzere ve System.Text.Json kullanılarak JSON Patch belgelerinin seri hale getirilmesi ve seri durumdan çıkarılması için özel mantığı sağlar. JsonPatchDocument<TModel> sınıfının anahtar yöntemi, düzeltme eki işlemlerini ApplyTo(Object) türündeki bir hedef nesneye uygulayan TModel yöntemidir.

JSON Patch uygulayan Minimal API PATCH uç noktası

Minimal API'de JSON Patch için PATCH uç noktası:

• Yolu tanımlamak için kullanır MapPatch .
• Bir JsonPatchDocument<TModel> parametreyi kabul eder.
• Değişiklikleri uygulamak için yama belgesinde ApplyTo(Object) çağırır.

Örnek Minimal API PATCH uç noktası

group.MapPatch("/{id}", async Task<Results<Ok<Customer>,ValidationProblem,NotFound<ProblemDetails>>> (AppDb db, string id,
    JsonPatchDocument<Customer> patchDoc) =>
{
    var customer = await db.Customers.Include(c => c.Orders).FirstOrDefaultAsync(c => c.Id == id);
    if (customer is null)
    {
        return TypedResults.NotFound<ProblemDetails>(new ());
    }
    if (patchDoc != null)
    {
        Dictionary<string, string[]>? errors = null;
        patchDoc.ApplyTo(customer, jsonPatchError =>
            {
                errors ??= new ();
                var key = jsonPatchError.AffectedObject.GetType().Name;
                if (!errors.ContainsKey(key))
                {
                    errors.Add(key, new string[] { });
                }
                errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
            });

        if (errors != null)
        {
            return TypedResults.ValidationProblem(errors);
        }

        // Only save if there are no errors
        await db.SaveChangesAsync();
    }

    return TypedResults.Ok(customer);
})
.Accepts<JsonPatchDocument<Customer>>("application/json-patch+json");

Örnek uygulamadaki bu kod aşağıdakilerle Customer ve Order modelleriyle çalışır:

using System.ComponentModel.DataAnnotations;

namespace App.Models;

public class Customer
{
    public string Id { get; set; }
    public string? Name { get; set; }
    public string? Email { get; set; }
    public string? PhoneNumber { get; set; }
    public string? Address { get; set; }
    public List<Order>? Orders { get; set; }
    public Customer()
    {
        Id = Guid.NewGuid().ToString();
    }
}

namespace App.Models;

public class Order
{
    public string Id { get; set; }
    public DateTime? OrderDate { get; set; }
    public DateTime? ShipDate { get; set; }
    public decimal TotalAmount { get; set; }

    public Order()
    {
        Id = Guid.NewGuid().ToString();
    }
}

Örnek PATCH uç noktasının temel adımları:

• Müşteriyi Alma:
  • Uç nokta, sağlanan Customeröğesini kullanarak veritabanından AppDb bir id nesne alır.
  • Hiçbir Customer nesnesi bulunmazsa, TypedResults.NotFound() aracılığıyla 404 Not Found yanıtı döndürür.
• JSON Düzeltme Eki Uygula:
  • ApplyTo(Object) yöntemi, patchDoc içindeki JSON Patch işlemlerini alınan Customer nesnesine uygular.
  • Düzeltme eki uygulaması sırasında geçersiz işlemler veya çakışmalar gibi hatalar oluşursa, hata işleme temsilcisi bunları yakalar. Bu temsilci, hata iletilerini etkilenen nesnenin tür adıyla anahtarlanmış bir sözlükte toplar.
• Doğrulama hatalarını döndürme:
  • Hata işleme temsilcisi düzeltme eki uygulaması sırasında hataları yakalarsa, uç nokta aracılığıyla ValidationProblemhata ayrıntılarını içeren bir TypedResults.ValidationProblem(errors) yanıt döndürür.
• Güncelleştirilmiş Müşteriyi kaydedin ve iade edin:
  • Düzeltme eki hata olmadan başarıyla uygulanırsa, değişiklikler veritabanına kaydedilir ve uç nokta aracılığıyla Customergüncelleştirilmiş TypedResults.Ok(customer) nesneyi döndürür.

Örnek hata yanıtı

Aşağıdaki örnek, belirtilen yol geçersiz olduğunda JSON Patch işlemi için doğrulama sorunu yanıtının gövdesini gösterir:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Customer": [
      "The target location specified by path segment 'foobar' was not found."
    ]
  }
}

Nesneye JSON Düzeltme Eki belgesi uygulama

Aşağıdaki örnekler, JSON Patch belgesini bir nesneye uygulamak için ApplyTo(Object) yönteminin nasıl kullanılacağını göstermektedir.

Örnek: Bir JsonPatchDocument<TModel> nesneye uygulayın

Aşağıdaki örnekte gösterilmiştir:

• add, replaceve remove işlemleri.
• İç içe geçmiş özelliklerde işlemler.
• Diziye yeni öğe ekleme.
• JSON yama belgesinde JSON Dize Enum Dönüştürücüsü kullanma.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com",
    PhoneNumbers = [new() {Number = "123-456-7890", Type = PhoneNumberType.Mobile}],
    Address = new Address
    {
        Street = "123 Main St",
        City = "Anytown",
        State = "TX"
    }
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/FirstName", "value": "Jane" },
    { "op": "remove", "path": "/Email"},
    { "op": "add", "path": "/Address/ZipCode", "value": "90210" },
    { "op": "add", "path": "/PhoneNumbers/-", "value": { "Number": "987-654-3210",
                                                                "Type": "Work" } }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document
patchDoc!.ApplyTo(person);

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

Önceki örnekte güncelleştirilmiş nesnenin aşağıdaki çıkışı elde edilir:

{
    "firstName": "Jane",
    "lastName": "Doe",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "TX",
        "zipCode": "90210"
    },
    "phoneNumbers": [
        {
            "number": "123-456-7890",
            "type": "Mobile"
        },
        {
            "number": "987-654-3210",
            "type": "Work"
        }
    ]
}

ApplyTo(Object) yöntemi, işleme System.Text.Json kurallarını ve seçeneklerini, aşağıdaki seçenekler tarafından denetlenen davranış da dahil olmak üzere, JsonPatchDocument<TModel> için geçerli olan kurallar ve seçenekleri izler.

• JsonNumberHandling: Sayısal özelliklerin dizelerden okunup okunmadığı.
• PropertyNameCaseInsensitive: Özellik adlarının büyük/küçük harfe duyarlı olup olmadığı.

System.Text.Json ve yeni JsonPatchDocument<TModel> uygulaması arasındaki ana farklar:

• Hedef nesnenin bildirilmiş türü değil, çalışma zamanındaki türü, hangi özellikleri ApplyTo(Object) yamanacağını belirler.
• System.Text.Json seri durumdan çıkarma, uygun özellikleri tanımlamak için bildirilen türe dayanır.

Örnek: Hata işleme ile JsonPatchDocument'i uygulama

JSON Düzeltme Eki belgesi uygulanırken çeşitli hatalar oluşabilir. Örneğin, hedef nesne belirtilen özelliğe sahip olmayabilir veya belirtilen değer özellik türüyle uyumsuz olabilir.

JSON Patch , belirtilen bir değerin test hedef özelliğe eşit olup olmadığını denetleyen işlemi destekler. Aksi takdirde bir hata döndürür.

Aşağıdaki örnekte bu hataların düzgün bir şekilde nasıl işleneceğini gösterilmektedir.

Important

ApplyTo(Object) yöntemine aktarılan nesne doğrudan değiştirilir. İşlemlerden herhangi biri başarısız olursa, değişiklikleri atmak çağırıcının sorumluluğundadır.

// Original object
var person = new Person {
    FirstName = "John",
    LastName = "Doe",
    Email = "johndoe@gmail.com"
};

// Raw JSON patch document
string jsonPatch = """
[
    { "op": "replace", "path": "/Email", "value": "janedoe@gmail.com"},
    { "op": "test", "path": "/FirstName", "value": "Jane" },
    { "op": "replace", "path": "/LastName", "value": "Smith" }
]
""";

// Deserialize the JSON patch document
var patchDoc = JsonSerializer.Deserialize<JsonPatchDocument<Person>>(jsonPatch);

// Apply the JSON patch document, catching any errors
Dictionary<string, string[]>? errors = null;
patchDoc!.ApplyTo(person, jsonPatchError =>
    {
        errors ??= new ();
        var key = jsonPatchError.AffectedObject.GetType().Name;
        if (!errors.ContainsKey(key))
        {
            errors.Add(key, new string[] { });
        }
        errors[key] = errors[key].Append(jsonPatchError.ErrorMessage).ToArray();
    });
if (errors != null)
{
    // Print the errors
    foreach (var error in errors)
    {
        Console.WriteLine($"Error in {error.Key}: {string.Join(", ", error.Value)}");
    }
}

// Output updated object
Console.WriteLine(JsonSerializer.Serialize(person, serializerOptions));

Önceki örnekte aşağıdaki çıkış elde edilir:

Error in Person: The current value 'John' at path 'FirstName' is not equal 
to the test value 'Jane'.
{
    "firstName": "John",
    "lastName": "Smith",              <<< Modified!
    "email": "janedoe@gmail.com",     <<< Modified!
    "phoneNumbers": []
}

Güvenlik risklerini azaltma

Paketi kullanırken Microsoft.AspNetCore.JsonPatch.SystemTextJson olası güvenlik risklerini anlamak ve azaltmak kritik önem taşır. Aşağıdaki bölümlerde JSON Düzeltme Eki ile ilişkili tanımlanan güvenlik riskleri özetlenmiştir ve paketin güvenli kullanımını sağlamak için önerilen risk azaltmaları sağlanır.

Important

Bu, kapsamlı bir tehdit listesi değildir. Uygulama geliştiricileri, uygulamaya özgü kapsamlı bir liste belirlemek ve gerektiğinde uygun risk azaltmaları bulmak için kendi tehdit modeli incelemelerini yapmalıdır. Örneğin, koleksiyonları düzeltme eki işlemlerine sunan uygulamalar, bu işlemlerin koleksiyonun başına öğe eklemesi veya kaldırması durumunda algoritmasal karmaşıklık saldırıları olasılığını göz önünde bulundurmalıdır.

JSON Patch işlevselliğini uygulamalarıyla tümleştirirken güvenlik risklerini en aza indirmek için geliştiriciler şunları yapmalıdır:

• Kendi uygulamaları için kapsamlı tehdit modelleri çalıştırın.
• Tanımlanan tehditleri ele alın.
• Aşağıdaki bölümlerde önerilen azaltmaları izleyin.

Bellek amplifikasyonu yoluyla Hizmet Reddi (DoS)

• Senaryo: Kötü amaçlı istemci, büyük nesne grafiklerini birden çok kez çoğaltan ve aşırı bellek tüketimine yol açan bir copy işlem gönderir.
• Etki: Hizmet kesintilerine neden olan olası Out-Of-Memory (OOM) koşulları.
• Mitigation:
  • ** ApplyTo(Object) çağırmadan önce gelen JSON Patch belgelerini boyut ve yapı açısından doğrulayın.
  • Doğrulamanın uygulamaya özgü olması gerekir, ancak örnek bir doğrulama aşağıdakine benzer olabilir:

public void Validate(JsonPatchDocument<T> patch)
{
    // This is just an example. It's up to the developer to make sure that
    // this case is handled properly, based on the app needs.
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count()
                              > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException();
    }
}

İş mantığının kötüye kullanılması

• Senaryo: Yama işlemleri, iş kısıtlamalarını ihlal ederek alanları örtük sabit değerlerle (örneğin, iç bayraklar, kimlikler veya hesaplanan alanlar) işleyebilir.
• Etki: Veri bütünlüğü sorunları ve istenmeyen uygulama davranışı.
• Mitigation:
  • Değiştirilmesi güvenli olan açıkça tanımlanmış özelliklerle POCO'ları (Düz Eski CLR Nesneleri) kullanın.
    • Hedef nesnede hassas veya güvenlik açısından kritik özellikleri ortaya çıkarmaktan kaçının.
    • POCO nesnesi kullanılmıyorsa, işlemleri uyguladıktan sonra yaması yapılmış nesneyi doğrulayarak iş kurallarının ve değişmezlerin ihlal edilmediğinden emin olun.

Kimlik doğrulaması ve yetkilendirme

• Senaryo: Kimliği doğrulanmamış veya yetkisiz istemciler kötü amaçlı JSON Düzeltme Eki istekleri gönderir.
• Etki: Hassas verileri değiştirmek veya uygulama davranışını kesintiye uğratmak için yetkisiz erişim.
• Mitigation:
  • Uygun kimlik doğrulama ve yetkilendirme mekanizmalarını kullanarak JSON Düzeltme Eki isteklerini kabul eden uç noktaları koruyun.
  • Erişimi güvenilen istemcilere veya uygun izinlere sahip kullanıcılara kısıtlayın.

Kodu alın

Örnek kodu görüntüleyin veya indirme. (Nasıl indirilir).

Örneği test etmek için uygulamayı çalıştırın ve eklenen .http dosyayı kullanarak HTTP istekleri gönderin.

Ek kaynaklar

• IETF RFC 5789 PATCH yöntemi belirtimi
• IETF RFC 6902 JSON Patch spesifikasyonu
• IETF RFC 6901 JSON İşaretçisi
• ASP.NET Core JSON Düzeltme Eki kaynak kodu