Podpora oprav JSON ve webovém rozhraní API ASP.NET Core

Tento článek vysvětluje, jak zpracovávat požadavky opravy JSON ve webovém rozhraní API ASP.NET Core.

Podpora oprav JSON ve webovém rozhraní API ASP.NET Core je založená na System.Text.Json serializaci a vyžaduje Microsoft.AspNetCore.JsonPatch.SystemTextJson balíček NuGet.

Co je standard JSON Patch?

Standard opravy JSON:

• Je standardní formát pro popis změn, které se mají použít u dokumentu JSON.

• Je definován v RFC 6902 a je široce používán v rozhraníCH RESTful API k provádění částečných aktualizací prostředků JSON.

• Popisuje posloupnost operací, které upravují dokument JSON, například:

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

Ve webových aplikacích se JSON Patch běžně používá v operaci PATCH k provádění částečných aktualizací prostředků. Místo odeslání celého prostředku pro aktualizaci můžou klienti odeslat dokument JSON Patch obsahující pouze změny. Patchování snižuje velikost přenášených dat a zlepšuje efektivitu.

Přehled standardu JSON Patch najdete na jsonpatch.com.

Podpora oprav JSON ve webovém rozhraní API ASP.NET Core

Podpora JSON Patch ve webovém API ASP.NET Core je založena na serializaci pomocí System.Text.Json, počínaje verzí .NET 10. Implementuje Microsoft.AspNetCore.JsonPatch na základě serializace System.Text.Json. Tato funkce:

• Microsoft.AspNetCore.JsonPatch.SystemTextJson Vyžaduje balíček NuGet.
• V souladu s moderními postupy .NET využívá knihovnu System.Text.Json , která je optimalizovaná pro .NET.
• Poskytuje lepší výkon a snížené využití paměti v porovnání s implementací založenou na starší Newtonsoft.Jsonverzi. Další informace o starší Newtonsoft.Jsonimplementaci naleznete v verzi tohoto článku pro .NET 9.

Note

Implementace Microsoft.AspNetCore.JsonPatch založená na System.Text.Json serializaci není náhradou za starší implementaci založenou na Newtonsoft.Json. Nepodporuje dynamické typy, například ExpandoObject.

Important

Standard JSON Patch má vlastní bezpečnostní rizika. Vzhledem k tomu, že tato rizika jsou součástí standardu JSON Patch, implementace ASP.NET Core se nepokouší zmírnit vlastní rizika zabezpečení. Je zodpovědností vývojáře, aby se zajistilo, že dokument Opravy JSON je bezpečný pro cílový objekt. Další informace najdete v části Omezení rizik zabezpečení .

Povolit podporu JSON Patch s využitím System.Text.Json

Chcete-li povolit podporu pro JSON Patch, nainstalujte balíček NuGet System.Text.JsonMicrosoft.AspNetCore.JsonPatch.SystemTextJson.

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson

Tento balíček poskytuje JsonPatchDocument<TModel> třídu představující dokument JSON Patch pro objekty typu TModel a vlastní logiky pro serializaci a deserializaci dokumentů JSON Patch pomocí System.Text.Json. Klíčovou metodou JsonPatchDocument<TModel> třídy je ApplyTo(Object), která aplikuje operace opravy na cílový objekt typu TModel.

Minimální koncový bod PATCH rozhraní API, který používá opravu JSON

V minimálním rozhraní API koncový bod PATCH pro opravu JSON:

• Slouží MapPatch k definování trasy.
• Přijímá parametr JsonPatchDocument<TModel>.
• Zavolá ApplyTo(Object) na dokumentu záplaty, aby se změny použily.

Příklad endpointu PATCH rozhraní Minimal API

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

Tento kód z ukázkové aplikace funguje s následujícími Customer modely a Order modely:

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

Klíčové kroky ukázkového koncového bodu PATCH:

• Načtení zákazníka:
  • Koncový bod načte z databáze AppDb objekt Customer na základě zadaného id.
  • Pokud nebyl nalezen žádný Customer objekt, vrátí 404 Not Found odpověď prostřednictvím TypedResults.NotFound().
• Použít opravu JSON:
  • Metoda ApplyTo(Object) aplikuje operace JSON Patch z patchDoc na načtený objekt Customer.
  • Pokud během aplikace oprav dojde k chybám, jako jsou neplatné operace nebo konflikty, delegát zpracování chyb je zachytí. Tento delegát shromažďuje chybové zprávy do slovníku s klíčem typu ovlivněného objektu.
• Vrátit chyby validace:
  • Pokud delegát zpracování chyb zaznamenává jakékoli chyby během aplikace opravy, koncový bod vrátí ValidationProblem odpověď obsahující podrobnosti o chybě prostřednictvím TypedResults.ValidationProblem(errors).
• Uložte a vraťte aktualizovaného zákazníka:
  • Pokud se oprava úspěšně použije bez chyb, změny se uloží do databáze a koncový bod vrátí aktualizovaný Customer objekt prostřednictvím TypedResults.Ok(customer).

Příklad odpovědi na chybu

Následující příklad ukazuje tělo odpovědi problému s validací pro operaci JSON Patch, pokud je zadaná cesta neplatná:

{
  "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."
    ]
  }
}

Použití dokumentu opravy JSON u objektu

Následující příklady ukazují, jak použít metodu ApplyTo(Object) k použití dokumentu JSON Patch na objekt.

Příklad: Aplikujte JsonPatchDocument<TModel> na objekt

Následující příklad ukazuje:

• Operace add, replace a remove.
• Operace s vnořenými vlastnostmi
• Přidání nové položky do pole
• Použití převaděče výčtu řetězců JSON v dokumentu opravy JSON

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

Předchozí příklad vede k následujícímu výstupu aktualizovaného objektu:

{
    "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"
        }
    ]
}

Metoda ApplyTo(Object) obecně dodržuje konvence a možnosti System.Text.Json zpracování JsonPatchDocument<TModel>, včetně chování řízeného následujícími možnostmi:

• JsonNumberHandling: Určuje, zda jsou číselné vlastnosti načteny z řetězců.
• PropertyNameCaseInsensitive: Zda názvy vlastností rozlišují velká a malá písmena.

Hlavní rozdíly mezi System.Text.Json a novou JsonPatchDocument<TModel> implementací:

• Typ modulu runtime cílového objektu, nikoli deklarovaný typ, určuje, které vlastnosti ApplyTo(Object) se opravují.
• System.Text.Json deserializace spoléhá na deklarovaný typ pro identifikaci způsobilých vlastností.

Příklad: Použití jsonPatchDocument se zpracováním chyb

Při použití dokumentu opravy JSON může dojít k různým chybám. Například cílový objekt nemusí mít zadanou vlastnost nebo zadaná hodnota může být nekompatibilní s typem vlastnosti.

JSON Patch podporuje test operaci, která kontroluje, jestli se zadaná hodnota rovná cílové vlastnosti. Pokud ne, vrátí chybu.

Následující příklad ukazuje, jak tyto chyby řádně zpracovat.

Important

Objekt předaný ApplyTo(Object) metodě je změněn na místě. Volající zodpovídá za zahození změn v případě selhání jakékoli operace.

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

Výsledkem předchozího příkladu je následující výstup:

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": []
}

Zmírnění rizik zabezpečení

Při používání Microsoft.AspNetCore.JsonPatch.SystemTextJson balíčku je důležité pochopit a zmírnit potenciální rizika zabezpečení. Následující části popisují identifikovaná bezpečnostní rizika spojená s opravou JSON a poskytují doporučená omezení rizik pro zajištění zabezpečeného používání balíčku.

Important

Nejedná se o vyčerpávající seznam hrozeb. Vývojářiaplikacích aplikací musí provádět vlastní kontroly modelu hrozeb, aby mohli podle potřeby určit komplexní seznam specifických pro konkrétní aplikaci a podle potřeby přijít s vhodnými omezeními rizik. Například aplikace, které zpřístupňují kolekce operacím oprav, by měly zvážit potenciál útoků na algoritmickou složitost, pokud tyto operace vloží nebo odeberou prvky na začátku kolekce.

Aby vývojáři mohli minimalizovat rizika zabezpečení při integraci funkcí oprav JSON do svých aplikací, měli by:

• Spusťte komplexní modely hrozeb pro své vlastní aplikace.
• Vyřešte zjištěné hrozby.
• Postupujte podle doporučených omezení rizik v následujících částech.

Odepření služby (DoS) prostřednictvím amplifikace paměti

• Scénář: Škodlivý klient odešle operaci, která několikrát duplikuje copy grafy velkých objektů, což vede k nadměrné spotřebě paměti.
• Dopad: Možné podmínkyOf-Memory (OOM), které mohou způsobit přerušení služeb.
• Mitigation:
  • Před voláním ApplyTo(Object)ověřte příchozí dokumenty JSON Patch pro velikost a strukturu .
  • Ověření musí být specifické pro aplikaci, ale ukázkové ověření může vypadat nějak takto:

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

Narušení obchodní logiky

• Scénář: Operace oprav můžou manipulovat s poli s implicitními invarianty (například s interními příznaky, ID nebo vypočítanými poli), porušením obchodních omezení.
• Dopad: Problémy s integritou dat a nezamýšlené chování aplikací
• Mitigation:
  • Použijte objekty POCOs (Plain Old CLR) s explicitně definovanými vlastnostmi, které jsou bezpečné k úpravě.
    • Vyhněte se zveřejnění citlivých nebo kritických vlastností zabezpečení v cílovém objektu.
    • Pokud se objekt POCO nepoužívá, ověřte po použití operací opravený objekt, abyste zajistili, že nedojde k porušení obchodních pravidel a invariantů.

Autentizace a autorizace

• Scénář: Neověřené nebo neautorizované klienty odesílají škodlivé požadavky na opravu JSON.
• Dopad: Neoprávněný přístup k úpravě citlivých dat nebo narušení chování aplikace
• Mitigation:
  • Chraňte koncové body, které přijímají požadavky JSON Patch, pomocí správných mechanismů ověřování a autorizace.
  • Omezte přístup k důvěryhodným klientům nebo uživatelům s příslušnými oprávněními.

Získání kódu

Zobrazení nebo stažení vzorového kódu (postup stahování).

Ukázku otestujete spuštěním aplikace a odesláním požadavků HTTP pomocí zahrnutého .http souboru.

Dodatečné zdroje

• Specifikace metody IETF RFC 5789 PATCH
• Specifikace JSON Patch IETF RFC 6902
• IETF RFC 6901 JSON Pointer
• zdrojový kód opravy JSON pro ASP.NET Core