JsonPatch ve webovém rozhraní API ASP.NET Core

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

Instalace balíčku

JSPodpora ON Patch ve webovém rozhraní API ASP.NET Core je založená Newtonsoft.Json a vyžaduje Microsoft.AspNetCore.Mvc.NewtonsoftJson balíček NuGet. JSPovolení podpory opravy ON:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Nainstalujte balíček NuGet.

• Zavolejte AddNewtonsoftJson. Příklad:

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

AddNewtonsoftJsonnahrazuje výchozí System.Text.Jsonvstupní a výstupní formátovací moduly založené na vstupu a výstupu, které se používají pro formátování veškeréhoJS obsahu ON. Tato metoda rozšíření je kompatibilní s následujícími metodami registrace služby MVC:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch vyžaduje nastavení hlavičky Content-Type na application/json-patch+json.

Přidání podpory pro JSON Patch při použití System.Text.Json

Vstupní System.Text.Jsonformátovací modul založený na technologii ON Patch nepodporuje JS. Pokud chcete přidat podporu on JSPatch using Newtonsoft.Json, zatímco ostatní vstupní a výstupní formátovací moduly beze změny:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Nainstalujte balíček NuGet.

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

Předchozí kód vytvoří instanci NewtonsoftJsonPatchInputFormatter a vloží ji jako první položku v kolekci MvcOptions.InputFormatters . Toto pořadí registrace zajišťuje, že:

• NewtonsoftJsonPatchInputFormatter zpracovává JSpožadavky NA opravu.
• System.Text.JsonStávající vstupní a formátovací moduly zpracovávají všechny ostatní JSpožadavky a odpovědi ON.

Newtonsoft.Json.JsonConvert.SerializeObject Použití metody serializace JsonPatchDocument.

Metoda požadavku HTTP PATCH

Metody PUT a PATCH slouží k aktualizaci existujícího prostředku. Rozdíl mezi nimi spočívá v tom, že PUT nahrazuje celý prostředek, zatímco patch určuje pouze změny.

JSON Patch

JSON Patch je formát pro určení aktualizací, které se mají použít u prostředku. Dokument JSON Patch obsahuje pole operací. Každá operace identifikuje konkrétní typ změny. Mezi příklady takových změn patří přidání prvku pole nebo nahrazení hodnoty vlastnosti.

Například následující JSdokumenty ON představují prostředek, JSdokument ON Patch pro prostředek a výsledek použití operací opravy.

Příklad prostředku

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

JSPříklad opravy ON

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

Ve výše uvedeném kódu JSON:

• Vlastnost op označuje typ operace.
• Vlastnost path označuje prvek, který se má aktualizovat.
• Vlastnost value poskytuje novou hodnotu.

Prostředek po opravě

Tady je prostředek po použití předchozího JSdokumentu ON Patch:

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

Změny provedené použitím JSdokumentu ON Patch na prostředek jsou atomické. Pokud jakákoli operace v seznamu selže, nepoužije se žádná operace v seznamu.

Syntaxe cesty

Vlastnost cesty objektu operace má lomítka mezi úrovněmi. Například, "/address/zipCode".

Indexy založené na nule slouží k určení prvků pole. První prvek pole addresses by byl na /addresses/0. Chcete-li add na konec pole, použijte místo čísla /addresses/-indexu spojovník (-) .

Operace

Následující tabulka uvádí podporované operace definované ve JSspecifikaci ON Patch:

Operace	Poznámky
add	Přidejte vlastnost nebo prvek pole. Pro existující vlastnost: nastavte hodnotu.
remove	Odeberte vlastnost nebo prvek pole.
replace	Stejné jako remove následované add na stejném místě.
move	Stejné jako remove ze zdroje, za nímž následuje add cíl s použitím hodnoty ze zdroje.
copy	Stejné jako add cíl s použitím hodnoty ze zdroje.
test	Vrátí stavový kód úspěchu, pokud hodnota at path = poskytnuta value.

JSON Patch in ASP.NET Core

Základní implementace on JSPatch ASP.NET je k dispozici v balíčku NuGet Microsoft.AspNetCore.JsonPatch .

Kód metody akce

V kontroleru rozhraní API metoda akce on JSPatch:

• Je opatřen poznámkami atributem HttpPatch .
• Přijímá , JsonPatchDocument<TModel>obvykle s [FromBody].
• Zavolá ApplyTo(Object) dokument opravy, aby změny použil.

Tady je příklad:

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

Tento kód z ukázkové aplikace funguje s následujícím Customer modelem:

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

Ukázková metoda akce:

• Vytvoří .Customer
• Použije opravu.
• Vrátí výsledek v textu odpovědi.

V reálné aplikaci by kód načetl data z úložiště, jako je databáze, a po instalaci opravy databázi aktualizoval.

Stav modelu

Předchozí příklad metody akce volá přetížení ApplyTo , které přebírá stav modelu jako jeden z jeho parametrů. Pomocí této možnosti můžete v odpovědích zobrazit chybové zprávy. Následující příklad ukazuje text odpovědi 400 Chybný požadavek pro test operaci:

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

Dynamické objekty

Následující příklad metody akce ukazuje, jak použít opravu na dynamický objekt:

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

    return Ok(obj);
}

Operace přidání

• Pokud path odkazuje na prvek pole: vloží nový prvek před prvek určený path.
• Pokud path odkazuje na vlastnost: nastaví hodnotu vlastnosti.
• Pokud path odkazuje na neexistující umístění:
  • Pokud je prostředek k opravě dynamickým objektem: přidá vlastnost.
  • Pokud je prostředek, který se má opravit, statický objekt: požadavek selže.

Následující ukázkový dokument opravy nastaví hodnotu CustomerName a přidá Order objekt na konec Orders pole.

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

Operace odebrání

• Pokud path odkazuje na prvek pole: odebere prvek.
• Pokud path odkazuje na vlastnost:
  • Pokud je prostředek k opravě dynamickým objektem: odebere vlastnost.
  • Pokud je prostředek k opravě statický objekt:
    • Pokud je vlastnost nullable: nastaví ji na hodnotu null.
    • Pokud vlastnost není nullable, nastaví ji na default<T>.

Následující ukázkový dokument opravy nastaví CustomerName hodnotu null a odstraní Orders[0]:

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

Operace nahrazení

Tato operace je funkčně stejná jako následná remove operace add.

Následující ukázkový dokument opravy nastaví hodnotu CustomerName a nahradí Orders[0]novým Order objektem:

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

Operace přesunutí

• Pokud path odkazuje na prvek pole: zkopíruje from element do umístění elementu path , pak spustí remove operaci prvku from .
• Pokud path odkazuje na vlastnost: zkopíruje hodnotu from vlastnosti do path vlastnosti, pak spustí remove operaci vlastnosti from .
• Pokud path odkazuje na neexistující vlastnost:
  • Pokud je prostředek, který se má opravit, statický objekt: požadavek selže.
  • Pokud prostředek k opravě je dynamický objekt: zkopíruje from vlastnost do umístění označeného path, pak spustí remove operaci s from vlastností.

Následující ukázkový dokument opravy:

• Zkopíruje hodnotu Orders[0].OrderName do CustomerName.
• Nastaví Orders[0].OrderName na hodnotu null.
• Přejde Orders[1] na před Orders[0].

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

Operace kopírování

Tato operace je funkčně stejná jako move operace bez posledního remove kroku.

Následující ukázkový dokument opravy:

• Zkopíruje hodnotu Orders[0].OrderName do CustomerName.
• Vloží kopii Orders[1] před Orders[0].

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

Testovací operace

Pokud se hodnota v umístění označeném path hodnotou liší od hodnoty zadané v value, požadavek selže. V takovém případě celý požadavek PATCH selže i v případě, že by všechny ostatní operace v dokumentu opravy jinak proběhly úspěšně.

Operace test se běžně používá k zabránění aktualizaci, když dojde ke konfliktu souběžnosti.

Následující ukázkový dokument opravy nemá žádný vliv, pokud je počáteční hodnota CustomerName "John", protože test selže:

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

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 s následujícím nastavením:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metoda HTTP: PATCH
• Záhlaví: Content-Type: application/json-patch+json
• Text: Zkopírujte a vložte jednu z JSukázek dokumentu opravy ON ze JSsložky projektu ON .

Další prostředky

• Specifikace metody IETF RFC 5789 PATCH
• Specifikace IETF RFC 6902 JSON Patch
• IETF RFC 6901 JSON Pointer
• JSDokumentace ke službě ON Patch Obsahuje odkazy na prostředky pro vytváření JSdokumentů ON Patch.
• zdrojový kód ASP.NET Core JSON Patch