Korzystanie z usługi REST z klientem HttpClient

  • 5 min

Wiele nowoczesnych usług internetowych implementuje architekturę REST. Ta struktura umożliwia usłudze internetowej uwidacznienie operacji i danych za pośrednictwem serii dobrze zdefiniowanych punktów końcowych. Żądania wysyłane przez aplikacje klienckie do usługi internetowej REST w celu pobierania, modyfikowania lub tworzenia lub usuwania danych używają wstępnie zdefiniowanego zestawu zleceń. Usługa internetowa REST odpowiada na te żądania w standardowy sposób. Takie podejście ułatwia konstruowanie aplikacji klienckich.

Model REST jest oparty na protokole HTTP. Aplikacja .NET MAUI może wysyłać żądania do usługi internetowej REST przy użyciu HttpClient klasy . W tej lekcji dowiesz się HttpClient , jak używać jej do interakcji z usługą internetową REST.

Co to jest klasa HttpClient?

HttpClient to klasa platformy .NET, za pomocą którego aplikacja może wysyłać żądania HTTP i odbierać odpowiedzi HTTP z usługi internetowej REST. Zestaw identyfikatorów URI identyfikuje zasoby udostępniane przez usługę internetową. Identyfikator URI łączy adres usługi internetowej z nazwą zasobu dostępnego pod tym adresem.

Klasa HttpClient używa interfejsu API opartego na zadaniach na potrzeby wydajności i zapewnia dostęp do informacji w komunikatach żądań, takich jak nagłówki HTTP i kody stanu, a także treści komunikatów, które zawierają rzeczywiste dane wysyłane i odbierane.

Diagram showing how a client app uses an HttpClient object to send and receive HTTP messages and responses

Klasa HttpClient jest dostępna w System.Net.Http przestrzeni nazw. Aplikacja może utworzyć HttpClient obiekt przy użyciu konstruktora domyślnego:

using System.Net.Http;
...

var client = new HttpClient();

Wykonywanie operacji CRUD za pomocą obiektu HttpClient

Usługa internetowa REST umożliwia klientowi wykonywanie operacji względem danych za pomocą zestawu zleceń HTTP. Zadanie czasownika HTTP polega na wskazaniu żądanej akcji do wykonania w zasobie. Istnieje wiele zleceń HTTP, ale cztery najczęściej są to POST, GET, PUTi DELETE. Usługa może zaimplementować te czasowniki, aby umożliwić aplikacji klienckiej zarządzanie cyklem życia obiektów, wykonując operacje tworzenia, odczytu, aktualizacji i usuwania (CRUD) w następujący sposób:

  • Czasownik POST wskazuje, że chcesz utworzyć nowy zasób.

  • Czasownik GET wskazuje, że chcesz pobrać zasób.

  • Czasownik PUT wskazuje, że chcesz zaktualizować zasób.

  • Czasownik DELETE wskazuje, że chcesz usunąć zasób.

Diagram showing the basic CRUD operations that a REST service can implement, including get, post, put and delete.

Tworzenie nowego zasobu za pomocą klienta HttpClient

Aby utworzyć nowy zasób przy użyciu metody HttpClient, możesz użyć SendAsync metody przekazującej HttpRequestMessage go do obiektu.

Element HttpRequestMessage jest przeznaczony do modelowania żądania wysyłanego do usługi internetowej. Należy określić czasownik HTTP, adres URL usługi internetowej i wypełnić dowolny ładunek do wysłania HttpRequestMessage.Content za pośrednictwem właściwości .

HttpClient client = new HttpClient();

HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

Ten fragment kodu wykonuje następujące zadania:

  • Tworzy wystąpienie wywoływanego HttpClientklienta , którego używa do wysyłania komunikatu.
  • Tworzy wystąpienie o nazwie komunikatuHttpRequestMessage, którego używa do modelowania komunikatu. Komunikat ma czasownik HTTP i adres URL.
  • Ustawia Content właściwość HttpRequestMessage, używając JsonContent.Create funkcji . Ta funkcja automatycznie serializuje zmienną części w formacie JSON odpowiednią do wysyłania do usługi internetowej.
  • Wysyła komunikat przy użyciu HttpClient obiektu . Zwracany HttpResponseMessage jest element zawierający informacje, takie jak kod stanu i informacje zwracane przez usługę internetową.

Odczytywanie zasobu za pomocą obiektu HttpClient

Zasób z usługi internetowej można odczytać przy użyciu tej samej techniki, co wcześniej opisane, z wyjątkiem inicjowania elementu HttpRequestMessage za pomocą elementu HttpMethod.Get. Ma HttpClient jednak kilka metod wygody, które udostępniają skróty.

Aby odczytać zasób przy użyciu metody HTTPClient, użyj GetStringAsync metody , jak pokazano w następnym przykładzie:

HttpClient client = new HttpClient();

string text = await client.GetStringAsync("https://...");

Metoda GetStringAsync przyjmuje identyfikator URI, który odwołuje się do zasobu i zwraca odpowiedź jako ciąg. Odpowiedź ciągu to zasób żądany przez aplikację. Format danych odpowiedzi jest domyślny dla żądanej usługi, takiej jak JSON lub XML. Aplikacja może poinformować usługę internetową, że wymaga zwrócenia danych w określonym formacie przez dodanie nagłówka MediaTypeWithQualityHeaderValue . Jeśli na przykład aplikacja żąda wysłania danych z powrotem w formacie JSON, może użyć następującego kodu:

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

W tym przykładzie wynik jest zwracany jako ciąg i zawiera tylko treść komunikatu odpowiedzi. Aby uzyskać całą odpowiedź, w tym nagłówki, treść i kod stanu, wywołaj metodę GetAsync . Dane są zwracane jako HttpResponseMessage obiekt.

Aktualizowanie zasobu za pomocą klienta HttpClient

Aby zaktualizować zasób przy użyciu polecenia HttpClient, użyj inicjowanego HttpRequestMessage czasownika PUT . Poniższy kod jest podobny do tego, który jest wymagany do utworzenia nowego zasobu:

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);

message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

Uwaga

Podstawowa różnica między elementami POST i PUT to idempotencyjność. Jeśli powtarzasz to samo PUT żądanie kilka razy, ten sam zasób zostanie zaktualizowany o te same dane, a efekt jest taki sam, jak w przypadku wysłania żądania tylko raz. Jeśli wydasz to samo POST żądanie kilka razy, wynikiem będzie usługa REST tworząca wiele kopii zasobu.

Usuwanie zasobu za pomocą obiektu HttpClient

Aby usunąć zasób przy użyciu polecenia HttpClient, wywołaj SendAsync metodę z zainicjowanym HttpRequestMessage zleceniem DELETE :

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);

HttpResponseMessage response = await client.SendAsync(message);

Odpowiedź zawiera nagłówki, kod stanu i usunięty obiekt.

Obsługa odpowiedzi z żądania

Wszystkie żądania HTTP zwracają komunikat odpowiedzi. Dane w odpowiedzi zależą od tego, które zlecenie wysłała aplikacja. Na przykład treść odpowiedzi żądania HTTP GET zawiera dane żądanego zasobu.

Treść POST odpowiedzi żądania zwraca kopię utworzonego zasobu, ale treść PUT odpowiedzi żądania powinna być pusta.

Zawsze należy sprawdzać i obsługiwać kod stanu w komunikacie odpowiedzi. Jeśli ten kod stanu znajduje się w zakresie 200 (200, 201, 202 itd.), operacja zostanie uznana za udaną, chociaż dalsze informacje mogą być wymagane później.

Kod stanu w zakresie 300 wskazuje, że żądanie mogło zostać przekierowane przez usługę internetową do innego adresu, prawdopodobnie w wyniku przeniesienia zasobu do innej lokalizacji.

Kod stanu w zakresie 400 wskazuje błąd klienta lub aplikacji. Na przykład kod stanu 403 oznacza, że usługa internetowa wymaga uwierzytelnienia użytkownika, ale aplikacja tego nie zrobiła. Kod stanu 404 występuje, gdy aplikacja próbuje uzyskać dostęp do zasobu, który nie istnieje.

Kody stanu w zakresie 500 wskazują na błąd po stronie serwera, taki jak usługa jest niedostępna lub zbyt zajęta do obsługi żądania.

HttpResponseMessage Obiekt zwrócony przez żądanie przesłane za pośrednictwem HttpClient obiektu może abstrakcją znaczną złożoność obsługi różnych kodów stanu. Ten fragment kodu pokazuje, jak sprawdzić, czy kod stanu w komunikacie odpowiedzi wskazuje powodzenie i obsługuje kody stanu wskazujące jakiś błąd.

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
}

Test wiedzy

1.

Którego zlecenia HTTP używasz do tworzenia nowego zasobu w usłudze internetowej REST?

2.

Która metoda HttpResponseMessage klasy powinna zostać wywołana, aby sprawdzić, czy żądanie HTTP zakończyło się pomyślnie?"