JsonPatch w internetowym interfejsie API platformy ASP.NET Core

W tym artykule wyjaśniono, jak obsługiwać JSżądania ON Patch w internetowym interfejsie API platformy ASP.NET Core.

Instalacja pakietu

JSObsługa poprawek w internetowym interfejsie API platformy ASP.NET Core jest oparta i Newtonsoft.Json wymaga Microsoft.AspNetCore.Mvc.NewtonsoftJson pakietu NuGet. Aby włączyć obsługę poprawek w usłudze JSON:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Zainstaluj pakiet NuGet.

• Wywołaj polecenie AddNewtonsoftJson. Przykład:

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

AddNewtonsoftJsonZastępuje domyślne System.Text.Jsonformatery danych wejściowych i wyjściowych używane do formatowania całejJS zawartości WŁĄCZONEj. Ta metoda rozszerzenia jest zgodna z następującymi metodami rejestracji usługi MVC:

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch wymaga ustawienia nagłówka Content-Type na application/json-patch+json.

Dodawanie obsługi poprawki JSON Podczas korzystania z pliku System.Text.Json

Formater System.Text.Jsondanych wejściowych oparty na systemie nie obsługuje JSfunkcji ON Patch. Aby dodać obsługę JSfunkcji ON Patch przy użyciu polecenia Newtonsoft.Json, pozostawiając inne formatery danych wejściowych i wyjściowych bez zmian:

• Microsoft.AspNetCore.Mvc.NewtonsoftJson Zainstaluj pakiet NuGet.

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

Powyższy kod tworzy wystąpienie NewtonsoftJsonPatchInputFormatter obiektu i wstawia je jako pierwszy wpis w kolekcji MvcOptions.InputFormatters . Ta kolejność rejestracji gwarantuje, że:

• NewtonsoftJsonPatchInputFormatter przetwarza JSżądania stosowania poprawek.
• Istniejące System.Text.Json- oparte na danych wejściowych i formaterów przetwarzają wszystkie inne JSżądania i odpowiedzi ON.

Newtonsoft.Json.JsonConvert.SerializeObject Użyj metody , aby serializować element JsonPatchDocument.

PATCH HTTP request method (Metoda żądania HTTP PATCH)

Metody PUT i PATCH służą do aktualizowania istniejącego zasobu. Różnica między nimi polega na tym, że PUT zastępuje cały zasób, podczas gdy PATCH określa tylko zmiany.

JSW przypadku poprawki

JSON Patch to format określania aktualizacji, które mają być stosowane do zasobu. JSDokument ON Patch zawiera tablicę operacji. Każda operacja identyfikuje określony typ zmiany. Przykłady takich zmian obejmują dodanie elementu tablicy lub zastąpienie wartości właściwości.

Na przykład następujące JSdokumenty ON reprezentują zasób, JSdokument ON Patch dla zasobu i wynik zastosowania operacji Patch.

Przykład zasobu

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

JSPrzykład stosowania poprawki

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

W powyższym pliku JSON:

• Właściwość op wskazuje typ operacji.
• Właściwość path wskazuje element do zaktualizowania.
• Właściwość value udostępnia nową wartość.

Zasób po poprawce

Oto zasób po zastosowaniu powyższego JSdokumentu w ramach poprawki ON:

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

Zmiany wprowadzone przez zastosowanie JSdokumentu ON Patch do zasobu są niepodzielne. Jeśli jakakolwiek operacja na liście nie powiedzie się, nie zostanie zastosowana żadna operacja na liście.

Składnia XPath

Właściwość path obiektu operacji ma ukośniki między poziomami. Na przykład "/address/zipCode".

Indeksy oparte na zerach służą do określania elementów tablicy. Pierwszym elementem addresses tablicy będzie wartość /addresses/0. Na add końcu tablicy użyj łącznika (-), a nie numeru indeksu: /addresses/-.

Operacje

W poniższej tabeli przedstawiono obsługiwane operacje zdefiniowane w specyfikacji poprawki JSON:

Operacja	Uwagi
add	Dodaj właściwość lub element tablicy. Dla istniejącej właściwości: ustaw wartość.
remove	Usuń właściwość lub element tablicy.
replace	To samo, co remove następuje add w tej samej lokalizacji.
move	Tak samo jak remove ze źródła, a następnie add do miejsca docelowego przy użyciu wartości ze źródła.
copy	Tak samo jak add w przypadku lokalizacji docelowej przy użyciu wartości ze źródła.
test	Zwraca kod stanu powodzenia, jeśli wartość na path = podano value.

JSWł. poprawka w programie ASP.NET Core

Implementacja ASP.NET Core poprawki JSON Patch jest dostępna w pakiecie NuGet Microsoft.AspNetCore.JsonPatch .

Kod metody akcji

W kontrolerze interfejsu API metoda akcji dla JSpoprawki ON:

• Jest adnotacją z atrybutem HttpPatch .
• Akceptuje element JsonPatchDocument<TModel>, zazwyczaj z elementem [FromBody].
• Wywołuje ApplyTo(Object) dokument poprawki, aby zastosować zmiany.

Oto przykład:

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

Ten kod z przykładowej aplikacji działa z następującym 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; }
}

Przykładowa metoda akcji:

• Tworzy element Customer.
• Stosuje poprawkę.
• Zwraca wynik w treści odpowiedzi.

W rzeczywistej aplikacji kod pobiera dane z magazynu, takiego jak baza danych, i aktualizuje bazę danych po zastosowaniu poprawki.

Stan modelu

Powyższy przykład metody akcji wywołuje przeciążenie ApplyTo , które przyjmuje stan modelu jako jeden z jego parametrów. Dzięki tej opcji możesz otrzymywać komunikaty o błędach w odpowiedziach. W poniższym przykładzie przedstawiono treść odpowiedzi 400 Nieprawidłowe żądanie dla test operacji:

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

Obiekty dynamiczne

Poniższy przykład metody akcji pokazuje, jak zastosować poprawkę do obiektu dynamicznego:

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

    return Ok(obj);
}

Operacja dodawania

• Jeśli path wskazuje element tablicy: wstawia nowy element przed elementem określonym przez path.
• Jeśli path wskazuje właściwość: ustawia wartość właściwości.
• Jeśli path wskazuje na nieistnieną lokalizację:
  • Jeśli zasób do stosowania poprawek jest obiektem dynamicznym: dodaje właściwość.
  • Jeśli zasób do stosowania poprawek jest obiektem statycznym: żądanie kończy się niepowodzeniem.

Poniższy przykładowy dokument poprawki ustawia wartość CustomerName i dodaje Order obiekt na końcu Orders tablicy.

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

Operacja usuwania

• Jeśli path wskazuje element tablicy: usuwa element.
• Jeśli path wskazuje właściwość:
  • Jeśli zasób do poprawki jest obiektem dynamicznym: usuwa właściwość .
  • Jeśli zasób do poprawki jest obiektem statycznym:
    • Jeśli właściwość ma wartość null: ustawia ją na wartość null.
    • Jeśli właściwość jest niemożliwa do wartości null, ustawia ją na default<T>wartość .

Następujące przykładowe poprawki dokumentów ustawiają wartość CustomerName null i usuwają Orders[0]element :

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

Operacja zastępowania

Ta operacja jest funkcjonalnie taka sama jak remove po nim .add

Poniższy przykładowy dokument poprawki ustawia wartość CustomerName i zastępuje Orders[0]element nowym Order obiektem:

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

Operacja przenoszenia

• Jeśli path wskazuje element tablicy: kopiuje from element do lokalizacji path elementu, a następnie uruchamia operację remove na elemecie from .
• Jeśli path wskazuje właściwość: kopiuje wartość from właściwości do path właściwości, a następnie uruchamia operację remove na from właściwości.
• Jeśli path wskazuje na nieistnieną właściwość:
  • Jeśli zasób do stosowania poprawek jest obiektem statycznym: żądanie kończy się niepowodzeniem.
  • Jeśli zasób do stosowania poprawek jest obiektem dynamicznym: kopiuje from właściwość do lokalizacji wskazanej przez pathelement , uruchamia operację remove na from właściwości .

Następujący przykładowy dokument poprawki:

• Kopiuje wartość Orders[0].OrderName do CustomerName.
• Ustawia Orders[0].OrderName wartość null.
• Przechodzi Orders[1] do przed Orders[0].

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

Operacja kopiowania

Ta operacja jest funkcjonalnie taka sama jak move operacja bez ostatniego remove kroku.

Następujący przykładowy dokument poprawki:

• Kopiuje wartość Orders[0].OrderName do CustomerName.
• Wstawia kopię Orders[1] przed elementem Orders[0].

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

Operacja testowa

Jeśli wartość w lokalizacji wskazanej przez path jest inna niż wartość podana w valueelemecie , żądanie zakończy się niepowodzeniem. W takim przypadku całe żądanie PATCH kończy się niepowodzeniem, nawet jeśli wszystkie inne operacje w dokumencie poprawki zakończyłyby się powodzeniem.

Operacja test jest często używana do zapobiegania aktualizacji w przypadku konfliktu współbieżności.

Następujący przykładowy dokument poprawki nie ma wpływu, jeśli początkowa wartość CustomerName to "Jan", ponieważ test kończy się niepowodzeniem:

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

Uzyskiwanie kodu

Wyświetl lub pobierz kod przykładowy. (Jak pobrać).

Aby przetestować przykład, uruchom aplikację i wyślij żądania HTTP przy użyciu następujących ustawień:

• URL: http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• Metoda HTTP: PATCH
• Nagłówka: Content-Type: application/json-patch+json
• Treść: skopiuj i wklej jeden z JSprzykładów dokumentów poprawek ON z JSfolderu projektu ON .

Dodatkowe zasoby

• Specyfikacja metody PATCH IETF RFC 5789
• Specyfikacja poprawki IETF RFC 6902 JSON Patch
• Wskaźnik IETF RFC 6901 JSON Pointer
• JSDokumentacja dotycząca poprawek w usłudze ON Patch. Zawiera linki do zasobów na potrzeby tworzenia JSdokumentów w usłudze ON Patch.
• kod źródłowy ASP.NET Core JSON Patch