Využívání služby REST pomocí HttpClient
Mnoho moderních webových služeb implementuje architekturu REST. Tato struktura umožňuje webové službě zveřejnit operace a data prostřednictvím řady dobře definovaných koncových bodů. Požadavky, které klientské aplikace odesílají do webové služby REST za účelem načtení, úpravy nebo vytvoření nebo odstranění dat, používají předdefinovanou sadu sloves. Webová služba REST na tyto požadavky reaguje standardním způsobem. Tento přístup usnadňuje vytváření klientských aplikací.
Model REST je založený na protokolu HTTP. Aplikace .NET MAUI může odesílat požadavky do webové služby REST pomocí HttpClient třídy. V této lekci se dozvíte, HttpClient jak ho používat k interakci s webovou službou REST.
Co je třída HttpClient?
HttpClient je třída .NET, kterou může aplikace použít k odesílání požadavků HTTP a přijímání odpovědí HTTP z webové služby REST. Sada identifikátorů URI identifikuje prostředky, které webová služba zveřejňuje. Identifikátor URI kombinuje adresu webové služby s názvem prostředku dostupného na této adrese.
Třída HttpClient používá k výkonu rozhraní API založené na úlohách a poskytuje přístup k informacím v zprávách požadavků, jako jsou hlavičky HTTP a stavové kódy, a také těla zpráv obsahující skutečná data, která se odesílají a přijímají.
Třída HttpClient je k dispozici v System.Net.Http oboru názvů. Aplikace může vytvořit HttpClient objekt pomocí výchozího konstruktoru:
using System.Net.Http;
...
var client = new HttpClient();
Provádění operací CRUD s objektem HttpClient
Webová služba REST umožňuje klientovi provádět operace s daty prostřednictvím sady příkazů HTTP. Úloha příkazu HTTP označuje požadovanou akci, která se má provést u prostředku. Existuje mnoho příkazů HTTP, ale čtyři nejběžnější jsou POST, GET, PUTa DELETE. Služba může implementovat tyto příkazy, aby klientská aplikace mohla spravovat životní cyklus objektů provedením operací Create, Read, Update a Delete (CRUD), a to následujícím způsobem:
Příkaz
POSToznačuje, že chcete vytvořit nový prostředek.Příkaz
GEToznačuje, že chcete načíst prostředek.Příkaz
PUToznačuje, že chcete aktualizovat prostředek.Příkaz
DELETEoznačuje, že chcete odstranit prostředek.
Vytvoření nového prostředku pomocí HttpClient
Chcete-li vytvořit nový prostředek pomocí HttpClient, můžete použít metodu SendAsync předání objektu HttpRequestMessage .
Cílem HttpRequestMessage je modelovat požadavek odeslaný do webové služby. Zadáte příkaz HTTP, adresu URL webové služby a naplníte libovolnou datovou část, kterou chcete odeslat prostřednictvím HttpRequestMessage.Content vlastnosti.
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Tento fragment kódu provádí následující úlohy:
- Vytvoří instanci zvanou
HttpClientklient , kterou používá k odeslání zprávy. - Vytvoří instanci volanou
HttpRequestMessagezprávu , kterou používá k modelování zprávy. Zpráva obsahuje příkaz HTTP a adresu URL. ContentNastaví vlastnostHttpRequestMessage, pomocíJsonContent.Createfunkce. Tato funkce automaticky serializuje proměnnou části do formátu JSON vhodného pro odeslání do webové služby.- Odešle zprávu pomocí objektu
HttpClient. JeHttpResponseMessagevrácena, která obsahuje informace, jako je stavový kód a informace vrácené webovou službou.
Čtení prostředku pomocí HttpClient
Prostředek z webové služby můžete číst pomocí stejné techniky jako dříve popsané, s výjimkou inicializace HttpRequestMessage pomocí .HttpMethod.Get Existuje HttpClient však několik metod usnadnění, které poskytují klávesové zkratky.
Pokud chcete číst prostředek pomocí HTTPClient, použijte GetStringAsync metodu, jak je znázorněno v následujícím příkladu:
HttpClient client = new HttpClient();
string text = await client.GetStringAsync("https://...");
Metoda GetStringAsync přebírá identifikátor URI, který odkazuje na prostředek a vrací odpověď jako řetězec. Řetězcová odpověď je prostředek, který aplikace požadovala. Formát dat odpovědí je výchozí pro požadovanou službu, například JSON nebo XML. Aplikace může webové službě sdělit, že data musí být vrácena v určitém formátu přidáním hlavičky MediaTypeWithQualityHeaderValue . Pokud například aplikace požaduje, aby se data posílala zpět ve formátu JSON, může použít následující kód:
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
V tomto příkladu se výsledek vrátí jako řetězec a obsahuje pouze text zprávy odpovědi. Pokud chcete získat celou odpověď včetně hlaviček, textu a stavového kódu, zavolejte metodu GetAsync . Data se vrátí jako HttpResponseMessage objekt.
Aktualizace prostředku pomocí HttpClient
Pokud chcete aktualizovat prostředek pomocí HttpClientpříkazu PUT, použijte HttpRequestMessage inicializovaný příkaz PUT . Následující kód je podobný kódu, který se vyžaduje k vytvoření nového prostředku:
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Poznámka:
Základní rozdíl mezi POST a PUT je idempotentní. Pokud stejný požadavek několikrát zopakujete PUT , stejný prostředek se aktualizuje se stejnými daty a efekt bude stejný jako v případě, že se požadavek odeslal pouze jednou. Pokud několikrát vydáte stejný POST požadavek, výsledkem bude služba REST, která vytvoří více kopií prostředku.
Odstranění prostředku pomocí HttpClient
Pokud chcete odstranit prostředek pomocí HttpClientpříkazu DELETE, volání SendAsync s HttpRequestMessage inicializovaným příkazem DELETE :
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);
HttpResponseMessage response = await client.SendAsync(message);
Odpověď obsahuje hlavičky, stavový kód a odstraněný objekt.
Zpracování odpovědí z požadavku
Všechny požadavky HTTP vrátí zprávu odpovědi. Data v odpovědi závisí na tom, které příkazy aplikace odeslala. Text odpovědi požadavku HTTP GET například obsahuje data požadovaného prostředku.
Text POST odpovědi požadavku vrátí kopii vytvořeného prostředku, ale text PUT odpovědi požadavku by měl být prázdný.
Stavový kód byste měli vždy zkontrolovat a zpracovat ve zprávě odpovědi. Pokud je tento stavový kód v rozsahu 200 (200, 201, 202 atd.), považuje se operace za úspěšnou, i když další informace mohou být vyžadovány později.
Stavový kód v rozsahu 300 značí, že žádost mohla být přesměrovaná webovou službou na jinou adresu, pravděpodobně v důsledku přesunu prostředku do jiného umístění.
Stavový kód v rozsahu 400 označuje chybu klienta nebo aplikace. Stavový kód 403 například znamená, že webová služba vyžaduje ověření uživatele, ale aplikace to neudělala. Stavový kód 404 nastane, když se aplikace pokusí získat přístup k prostředku, který neexistuje.
Stavové kódy v rozsahu 500 značí chybu na straně serveru, jako je nedostupnost služby nebo příliš zaneprázdněná pro zpracování požadavku.
Objekt HttpResponseMessage vrácený požadavkem odeslaným prostřednictvím objektu HttpClient může abstraktovat většinu složitosti zpracování různých stavových kódů. Tento fragment kódu ukazuje, jak ověřit, že stavový kód ve zprávě odpovědi indikuje úspěch, a zpracovat stavové kódy, které označují určitý druh selhání.
static readonly HttpClient client = new HttpClient();
...
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
{
//... Initiate the HttpRequest
HttpResponseMessage response = await client.SendAsync(msg);
response.EnsureSuccessStatusCode(); // Check that the status code is in the 200 range. Throw an HttpRequestException if not
string responseBody = await response.Content.ReadAsStringAsync();
... // Handle the response
}
catch(HttpRequestException e)
{
... // Handle any status codes that indicate an error.
// The status code is available in the field e.StatusCode
}