JsonPatch w internetowym interfejsie API platformy ASP.NET Core

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

Instalacja pakietu

Obsługa poprawek JSON 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 JSON:

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

• Wywołaj polecenie AddNewtonsoftJson. Na przykład:

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

AddNewtonsoftJson Zastępuje domyślne System.Text.Jsonformatery danych wejściowych i wyjściowych używane do formatowania całej zawartości JSON. 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 w przypadku korzystania z pliku System.Text.Json

Formater System.Text.Jsondanych wejściowych oparty na protokole nie obsługuje poprawki JSON. Aby dodać obsługę poprawek JSON 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 żądania poprawek JSON.
• Istniejące System.Text.Jsonelementy wejściowe i formatujące przetwarzają wszystkie inne żądania i odpowiedzi w formacie JSON.

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.

Poprawka JSON

Poprawka JSON to format określający aktualizacje, które mają być stosowane do zasobu. Dokument poprawki JSON 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 dokumenty JSON reprezentują zasób, dokument poprawki JSON dla zasobu i wynik zastosowania operacji patch.

Przykład zasobu

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

Przykład poprawki JSON

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

W powyższym kodzie 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 poprzedniego dokumentu poprawki JSON:

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

Zmiany wprowadzone przez zastosowanie dokumentu poprawki JSON 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.

Poprawka JSON w ASP.NET Core

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

Kod metody akcji

W kontrolerze interfejsu API metoda akcji dla poprawki JSON:

• 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łówek: Content-Type: application/json-patch+json
• Treść: skopiuj i wklej jeden z przykładów dokumentów poprawek JSON z folderu projektu JSON .

Dodatkowe zasoby

• Specyfikacja metody PATCH IETF RFC 5789
• Specyfikacja poprawki JSON JSON IETF RFC 6902
• Wskaźnik JSON IETF RFC 6901
• Dokumentacja poprawki JSON. Zawiera linki do zasobów do tworzenia dokumentów poprawek JSON.
• kod źródłowy poprawki JSON platformy ASP.NET Core