asp.net-web-api
Negocjacja treści interfejsu API sieci Web ASP.NET
Szukaj…
ASP.NET Web API Negocjacja treści Podstawowe informacje
Negocjację treści można zdefiniować jako proces wyboru najlepszej reprezentacji dla danego zasobu. Negocjacja treści oznacza, że klient i serwer mogą negocjować między nimi, aby klient mógł uzyskać dane zgodnie z wymaganym formatem.
Istnieją trzy punkty, od których zależy Internet,
- Zasób
- Wskaźnik do zasobu (URL)
- Reprezentacja zasobów
Trzeci punkt jest ważniejszy niż pozostałe dwa, ponieważ wszystko działa na podstawie tego, jak możemy zobaczyć zasób. Możemy reprezentować zasób w dwóch formatach.
- Format XML (Extensible Markup Language)
- Format JSON (JavaScript Object Notation)
Jednym ze standardów usługi RESTful jest to, że klient powinien mieć możliwość decydowania, w jakim formacie chce odpowiedzi w JSON lub XML. Żądanie wysyłane do serwera zawiera nagłówek Accept. Za pomocą nagłówka Akceptuj klient może określić format odpowiedzi.
Na przykład,
Accept: application/xml zwraca wynik w formacie XML
Accept: application/json zwraca wynik w formacie JSON
W zależności od wartości nagłówka Akceptuj w żądaniu serwer wysyła odpowiedź. Nazywa się to negocjowaniem treści.
Co dzieje się za sceną, gdy żądamy danych w określonym formacie?
Kontroler interfejsu API sieci Web ASP.NET generuje dane, które chcemy wysłać do klienta, i przekazuje je do potoku interfejsu API sieci Web, który następnie szuka nagłówka Accept klienta. Następnie wybierz odpowiedni formatator do sformatowania danych.
Ponieważ interfejs API sieci Web ASP.NET jest znacznie rozszerzalny, możemy również określić wiele wartości nagłówka akceptacji w nagłówku żądania.
Accept: application/xml,application/json
W powyższym przypadku serwer wybiera pierwszy formatator, który sformatuje dane odpowiedzi.
Możemy również określić współczynnik jakości w nagłówku accept. W takim przypadku serwer wybiera format o wyższym współczynniku jakości.
Accept: application/json;q=0.8,application/xml;q=0.5
Jeśli nie określimy żadnego nagłówka Accept, serwer domyślnie wybiera formatator JSON.
Gdy odpowiedź jest wysyłana do klienta w żądanym formacie, zauważ, że nagłówek Content-Type odpowiedzi jest ustawiony na odpowiednią wartość. Na przykład, jeśli klient zażądał application/xml , serwer wysyła dane w formacie XML, a także ustawia Content-Type=application/xml .
Formaterery są używane przez serwer zarówno dla komunikatów żądań, jak i odpowiedzi. Gdy klient wysyła żądanie do serwera, ustawiamy nagłówek Content-Type na odpowiednią wartość, aby poinformować serwer o formacie przesyłanych danych.
Na przykład, jeśli klient wysyła dane JSON, nagłówek Content-Type jest ustawiony na application/json . Serwer wie, że ma do czynienia z danymi JSON, więc używa formatera JSON do konwersji danych JSON na typ .NET. Podobnie, gdy odpowiedź jest wysyłana z serwera do klienta, w zależności od wartości nagłówka Accept, odpowiedni formater jest używany do konwersji typu .NET na JSON, XML itp.
Przykład różnych typów formatu odpowiedzi:
application / json:
{
"Email": "sample string 1",
"HasRegistered": true,
"LoginProvider": "sample string 3"
}
application / xml:
<UserInfoViewModel xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/WebApiDemo.Models">
<Email>sample string 1</Email>
<HasRegistered>true</HasRegistered>
<LoginProvider>sample string 3</LoginProvider>
</UserInfoViewModel>
Nowoczesne aplikacje internetowe mogą dostarczać dane w różnych językach i formatach. Jeśli więc opracujemy nasz interfejs API, aby objąć nim globalnych użytkowników na całym świecie, negocjacje treści są istotne.
Negocjacja treści w interfejsie API sieci Web
Zrozumienie koncepcji
Aby zrozumieć negocjowanie treści w interfejsie API sieci Web, ważne jest zrozumienie terminu Resource .
W Internecie wszelkie informacje, do których mamy dostęp, mogą być nazywane HTTP resource . W sieci znajduje się ogromna ilość materiałów, które mają różne typy treści, takie jak dokumenty HTML, obrazy, wideo, audio, pliki wykonywalne, arkusze kalkulacyjne itp. Możemy uzyskać dowolny zasób, wysyłając żądanie http do identyfikatora zasobu. Odpowiedź HTTP na żądanie zwraca zasób, a także określa typ zawartości, also known as media type .
Aby uzyskać dostęp do dowolnego zasobu, klient może wysłać żądanie HTTP, podając określone zasoby i zasoby czasownika http. Oprócz tego klient może również określić typ akceptacji, czyli format treści, której szuka użytkownik. „Typ akceptacji” może być zdefiniowany w nagłówkach żądania HTTP jako nagłówek “accept” .
Serwer następnie sprawdza nagłówek „accept” z żądań i zwraca odpowiedź w określonym formacie, jeśli jest dostępny. Pamiętaj, że serwer może zwrócić odpowiedź tylko w żądanej reprezentacji, jeśli jest dostępna . Jeśli żądana reprezentacja nie jest dostępna, zwraca zasób w domyślnej reprezentacji. Dlatego nazywa się to negocjowaniem treści.
Praktyczny przykład
Jako przykład załóżmy, że wysyłasz zapytanie na http://example.com/customer/1 w celu uzyskania informacji o kliencie o identyfikatorze 1. Jeśli nie podasz nagłówka „accept” w żądaniu, serwer zwróci domyślną reprezentację tego zasobu.
Załóżmy, że serwer może zwrócić informacje o kliencie w json and xml both . Teraz to klient musi określić wymagany format informacji o kliencie w nagłówku „accept” w żądaniu. Wartością nagłówka “accept” może być “application/json” dla reprezentacji json lub “text/xml” dla reprezentacji xml. Serwer zwróci wówczas odpowiedź zgodnie z żądanym formatem.
Jeśli żądanym formatem jest „text / html”, który nie jest obsługiwany przez ten host (jak w tym przykładzie), wówczas simply return the resource in the default format . Odpowiedź HTTP zawiera nagłówek “content-type” który informuje klienta o formacie zasobu.
Należy pamiętać, że nawet w przypadku, gdy żądana reprezentacja zasobu nie jest dostępna, domyślna reprezentacja zasobu jest nadal zwracana.
Dlatego nazywa się to negocjowaniem treści .
Klient negocjuje reprezentację odpowiedzi, jednak jeśli nie jest ona dostępna, otrzymuje odpowiedź domyślną.
Jak skonfigurować w interfejsie API sieci Web
W interfejsie API sieci Web negocjację treści można skonfigurować w klasie WebAPIConfig jako
config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new System.Net.Http.Headers.MediaTypeHeaderValue("text/html"));
Możesz również zastąpić domyślną negocjację treści w interfejsie API sieci Web, implementując interfejs IContentNegotiator i jego metodę Negotiate, a następnie konfigurując go w wierszu potoku żądania interfejsu API sieci Web w pliku WebAPI.config, jak poniżej:
GlobalConfiguration.Configuration.Services.Replace(typeof(IContentNegotiator), new CustomContentNegotiator());
Poniżej przedstawiono przykładową implementację metody Negotiate.
public class CustomContentNegotiator : DefaultContentNegotiator
{
public override ContentNegotiationResult Negotiate(Type type, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
{
var result = new ContentNegotiationResult(new JsonMediaTypeFormatter(), new MediaTypeHeaderValue("application/json"));
return result;
}