Använda en REST-tjänst med HttpClient

  • 5 minuter

Många moderna webbtjänster implementerar REST-arkitekturen. Den här strukturen gör det möjligt för en webbtjänst att exponera åtgärder och data via en serie väldefinierade slutpunkter. Begäranden som klientappar skickar till en REST-webbtjänst för att hämta, ändra eller skapa eller ta bort data använder en fördefinierad uppsättning verb. En REST-webbtjänst svarar på dessa begäranden på ett standardiserat sätt. Den här metoden gör det enklare att skapa klientappar.

REST-modellen bygger på HTTP-protokollet. Ett .NET MAUI-program kan skicka begäranden till en REST-webbtjänst med hjälp HttpClient av klassen . I den här lektionen får du lära dig mer om HttpClient och hur du använder den för att interagera med en REST-webbtjänst.

Vad är klassen HttpClient?

HttpClient är en .NET-klass som en app kan använda för att skicka HTTP-begäranden och ta emot HTTP-svar från en REST-webbtjänst. En uppsättning URI:er identifierar de resurser som webbtjänsten exponerar. En URI kombinerar adressen till webbtjänsten med namnet på en resurs som är tillgänglig på den adressen.

Klassen HttpClient använder ett aktivitetsbaserat API för prestanda och ger dig åtkomst till information i begärandemeddelanden, till exempel HTTP-huvuden och statuskoder, samt meddelandeorgan som innehåller faktiska data som skickas och tas emot.

Diagram som visar hur en klientapp använder ett HttpClient-objekt för att skicka och ta emot HTTP-meddelanden och svar

Klassen HttpClient är tillgänglig i System.Net.Http namnområdet. En app kan skapa ett HttpClient objekt med hjälp av standardkonstruktorn:

using System.Net.Http;
...

var client = new HttpClient();

Utföra CRUD-åtgärder med ett HttpClient-objekt

En REST-webbtjänst gör det möjligt för en klient att utföra åtgärder mot data via en uppsättning HTTP-verb. HTTP-verbets jobb är att ange önskad åtgärd som ska utföras på en resurs. Det finns många HTTP-verb, men de fyra vanligaste är POST, GET, PUToch DELETE. En tjänst kan implementera dessa verb för att göra det möjligt för ett klientprogram att hantera livscykeln för objekt genom att utföra CRUD-åtgärder (Create, Read, Update och Delete) enligt följande:

  • Verbet POST anger att du vill skapa en ny resurs.

  • Verbet GET anger att du vill hämta en resurs.

  • Verbet PUT anger att du vill uppdatera en resurs.

  • Verbet DELETE anger att du vill ta bort en resurs.

Diagram som visar de grundläggande CRUD-åtgärder som en REST-tjänst kan implementera, inklusive get, post, put and delete.

Skapa en ny resurs med HttpClient

Om du vill skapa en ny resurs med hjälp HttpClientav kan du använda metoden SendAsync som skickar den till ett HttpRequestMessage objekt.

HttpRequestMessage Är avsedd att modellera den begäran som skickas till webbtjänsten. Du anger HTTP-verbet, webbtjänstens URL och fyller i alla nyttolaster som ska skickas via egenskapen HttpRequestMessage.Content .

HttpClient client = new HttpClient();

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

HttpResponseMessage response = await client.SendAsync(message);

Det här kodfragmentet utför följande uppgifter:

  • Den skapar en instans av HttpClient den anropade klienten som den använder för att skicka ett meddelande.
  • Den skapar en instans av HttpRequestMessage det anropade meddelandet som används för att modellera meddelandet. Meddelandet har HTTP-verbet och URL:en.
  • Den anger Content egenskapen för HttpRequestMessage, med hjälp JsonContent.Create av funktionen . Den funktionen serialiserar automatiskt delvariabeln till JSON som är lämplig för att skicka till webbtjänsten.
  • Meddelandet skickas med hjälp av HttpClient objektet. En HttpResponseMessage returneras som innehåller information som statuskod och information som returneras av webbtjänsten.

Läsa en resurs med HttpClient

Du kan läsa en resurs från en webbtjänst med samma teknik som tidigare beskrivits, förutom att HttpRequestMessage initiera med en HttpMethod.Get. Har dock HttpClient ett par bekvämlighetsmetoder som ger genvägar.

Om du vill läsa en resurs med hjälp HTTPClientav använder du GetStringAsync metoden som du ser i nästa exempel:

HttpClient client = new HttpClient();

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

Metoden GetStringAsync tar en URI som refererar till resursen och returnerar ett svar som en sträng. Strängsvaret är den resurs som appen begärde. Formatet för svarsdata är standard för den begärda tjänsten, till exempel JSON eller XML. En app kan tala om för webbtjänsten att den kräver att data returneras i ett visst format genom att lägga till MediaTypeWithQualityHeaderValue rubriken. Om appen till exempel begär att data skickas tillbaka i JSON-format kan den använda följande kod:

HttpClient client = new HttpClient();

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

I det här exemplet returneras resultatet som en sträng och innehåller bara svarsmeddelandetexten. Anropa metoden för att hämta hela svaret, inklusive rubriker, brödtext och statuskod GetAsync . Data returneras som ett HttpResponseMessage objekt.

Uppdatera en resurs med HttpClient

Om du vill uppdatera en resurs med hjälp HttpClientav använder du en HttpRequestMessage initierad med ett PUT-verb . Följande kod liknar den som krävs för att skapa en ny resurs:

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

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

HttpResponseMessage response = await client.SendAsync(message);

Kommentar

Den grundläggande skillnaden mellan POST och PUT är idempotens. Om du upprepar samma PUT begäran flera gånger uppdateras samma resurs med samma data och effekten är densamma som om begäran bara hade skickats en gång. Om du utfärdar samma POST begäran flera gånger blir resultatet att REST-tjänsten skapar flera kopior av resursen.

Ta bort en resurs med HttpClient

Om du vill ta bort en resurs med hjälp HttpClientav anropar SendAsync du med en HttpRequestMessage initierad med ett DELETE-verb :

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

HttpResponseMessage response = await client.SendAsync(message);

Svaret innehåller rubriker, statuskod och borttagna objekt.

Hantera svar från en begäran

Alla HTTP-begäranden returnerar ett svarsmeddelande. Data i svaret beror på vilket verb appen skickade. Svarstexten i en HTTP-begäran GET innehåller till exempel data för den begärda resursen.

Svarstexten i en POST begäran returnerar en kopia av resursen som skapades, men svarstexten för en PUT begäran ska vara tom.

Du bör alltid kontrollera och hantera statuskoden i svarsmeddelandet. Om den här statuskoden ligger i intervallet 200 (200, 201, 202 och så vidare) anses åtgärden ha lyckats, även om ytterligare information kan krävas senare.

En statuskod i 300-intervallet anger att begäran kan ha omdirigerats av webbtjänsten till en annan adress, eventuellt som ett resultat av att en resurs flyttas till en annan plats.

En statuskod i 400-intervallet anger ett klient- eller programfel. Statuskod 403 innebär till exempel att webbtjänsten kräver att användaren autentiseras, men appen har inte gjort det. Statuskod 404 inträffar när appen försöker komma åt en resurs som inte finns.

Statuskoder i 500-intervallet tyder på ett fel på serversidan, till exempel att tjänsten är otillgänglig eller för upptagen för att hantera begäran.

Objektet HttpResponseMessage som returneras av en begäran som skickas via ett HttpClient objekt kan sammanfatta mycket av komplexiteten i hanteringen av de olika statuskoderna. Det här kodfragmentet visar hur du verifierar att statuskoden i ett svarsmeddelande anger lyckade och hanterar statuskoder som indikerar någon form av fel.

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
}

Kunskapstest

1.

Vilket HTTP-verb använder du för att skapa en ny resurs i en REST-webbtjänst?

2.

Vilken metod i HttpResponseMessage klassen ska du anropa för att verifiera att en HTTP-begäran lyckades?"