Een REST-service gebruiken met HttpClient

  • 5 minuten

Veel moderne webservices implementeren de REST-architectuur. Met deze structuur kan een webservice bewerkingen en gegevens beschikbaar maken via een reeks goed gedefinieerde eindpunten. De aanvragen die client-apps verzenden naar een REST-webservice om gegevens op te halen, te wijzigen of te maken of te verwijderen, gebruiken een vooraf gedefinieerde set werkwoorden. Een REST-webservice reageert op deze aanvragen op een standaard manier. Deze aanpak maakt het eenvoudiger om client-apps te maken.

Het REST-model is gebouwd op het HTTP-protocol. Een .NET MAUI-toepassing kan aanvragen verzenden naar een REST-webservice met behulp van de HttpClient klasse. In deze les leert u hoe HttpClient u deze kunt gebruiken om te communiceren met een REST-webservice.

Wat is de HttpClient-klasse?

HttpClient is een .NET-klasse die een app kan gebruiken om HTTP-aanvragen te verzenden en HTTP-antwoorden te ontvangen van een REST-webservice. Een set URI's identificeert de resources die door de webservice worden weergegeven. Een URI combineert het adres van de webservice met de naam van een resource die beschikbaar is op dat adres.

De HttpClient klasse maakt gebruik van een taakgebaseerde API voor prestaties en biedt u toegang tot informatie in aanvraagberichten zoals HTTP-headers en statuscodes, evenals berichtteksten die de werkelijke gegevens bevatten die worden verzonden en ontvangen.

Diagram waarin wordt getoond hoe een client-app gebruikmaakt van een HttpClient-object voor het verzenden en ontvangen van HTTP-berichten en -antwoorden

De HttpClient klasse is beschikbaar in de System.Net.Http naamruimte. Een app kan een HttpClient object maken met behulp van de standaardconstructor:

using System.Net.Http;
...

var client = new HttpClient();

CRUD-bewerkingen uitvoeren met een HttpClient-object

Met een REST-webservice kan een client bewerkingen uitvoeren op gegevens via een set HTTP-woorden. De taak van het HTTP-werkwoord is om de gewenste actie aan te geven die moet worden uitgevoerd op een resource. Er zijn veel HTTP-woorden, maar de vier meest voorkomende zijn POST, GET, en PUTDELETE. Een service kan deze bewerkingen implementeren om een clienttoepassing in staat te stellen de levenscyclus van objecten te beheren door CRUD-bewerkingen (Create, Read, Update en Delete) als volgt uit te voeren:

  • Het POST werkwoord geeft aan dat u een nieuwe resource wilt maken.

  • Het GET werkwoord geeft aan dat u een resource wilt ophalen.

  • Het PUT werkwoord geeft aan dat u een resource wilt bijwerken.

  • Het DELETE werkwoord geeft aan dat u een resource wilt verwijderen.

Diagram met de eenvoudige CRUD-bewerkingen die een REST-service kan implementeren, waaronder ophalen, posten, plaatsen en verwijderen.

Een nieuwe resource maken met HttpClient

Als u een nieuwe resource wilt maken met behulp van HttpClient, kunt u de SendAsync methode gebruiken die een HttpRequestMessage object doorgeeft.

Het HttpRequestMessage is bedoeld om de aanvraag te modelleren die naar de webservice wordt verzonden. U geeft het HTTP-werkwoord, de URL van de webservice op en vult elke nettolading in die via de HttpRequestMessage.Content eigenschap moet worden verzonden.

HttpClient client = new HttpClient();

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

HttpResponseMessage response = await client.SendAsync(message);

Met dit codefragment worden de volgende taken uitgevoerd:

  • Er wordt een exemplaar gemaakt van HttpClient de aangeroepen client die wordt gebruikt om een bericht te verzenden.
  • Er wordt een exemplaar gemaakt van HttpRequestMessage een aangeroepen bericht dat wordt gebruikt om het bericht te modelleren. Het bericht heeft het HTTP-werkwoord en de URL.
  • Hiermee stelt u de Content eigenschap van de HttpRequestMessage, met behulp van de JsonContent.Create functie. Met deze functie wordt de onderdeelvariabele automatisch geserialiseerd in JSON die geschikt is voor verzending naar de webservice.
  • Het bericht wordt verzonden met behulp van het HttpClient object. Er HttpResponseMessage wordt een geretourneerd dat informatie bevat, zoals de statuscode en informatie die door de webservice wordt geretourneerd.

Een resource lezen met HttpClient

U kunt een resource van een webservice lezen met behulp van dezelfde techniek als eerder beschreven, behalve het initialiseren van de HttpRequestMessage resource met een HttpMethod.Get. Het HttpClient heeft echter een aantal handige methoden die snelkoppelingen bieden.

Als u een resource wilt lezen met behulp van HTTPClient, gebruikt u de GetStringAsync methode zoals wordt weergegeven in het volgende voorbeeld:

HttpClient client = new HttpClient();

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

De GetStringAsync methode gebruikt een URI die verwijst naar de resource en een antwoord retourneert als een tekenreeks. Het tekenreeksantwoord is de resource die de app heeft aangevraagd. De indeling voor antwoordgegevens is de standaardindeling voor de aangevraagde service, zoals JSON of XML. Een app kan de webservice vertellen dat de gegevens moeten worden geretourneerd in een specifieke indeling door de MediaTypeWithQualityHeaderValue header toe te voegen. Als de app bijvoorbeeld aanvraagt dat gegevens worden teruggestuurd in JSON-indeling, kan deze de volgende code gebruiken:

HttpClient client = new HttpClient();

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

In dit voorbeeld wordt het resultaat geretourneerd als een tekenreeks en bevat alleen de hoofdtekst van het antwoordbericht. Als u het volledige antwoord wilt ophalen, inclusief headers, hoofdteksten en statuscode, roept u de GetAsync methode aan. De gegevens worden geretourneerd als een HttpResponseMessage object.

Een resource bijwerken met HttpClient

Als u een resource wilt bijwerken met behulp van HttpClient, gebruikt u een HttpRequestMessage geïnitialiseerde resource met een PUT-werkwoord . De volgende code is vergelijkbaar met de code die nodig is om een nieuwe resource te maken:

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

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

HttpResponseMessage response = await client.SendAsync(message);

Notitie

Het fundamentele verschil tussen POST en PUT is idempotentie. Als u dezelfde PUT aanvraag meerdere keren herhaalt, wordt dezelfde resource bijgewerkt met dezelfde gegevens en is het effect hetzelfde als als als de aanvraag slechts eenmaal is verzonden. Als u dezelfde POST aanvraag meerdere keren uitgeeft, wordt het resultaat de REST-service die meerdere exemplaren van de resource maakt.

Een resource verwijderen met HttpClient

Als u een resource wilt verwijderen met behulp van HttpClient, roept SendAsync u aan met een HttpRequestMessage geïnitialiseerde term DELETE :

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

HttpResponseMessage response = await client.SendAsync(message);

Het antwoord bevat de headers, statuscode en verwijderd object.

Antwoorden van een aanvraag verwerken

Alle HTTP-aanvragen retourneren een antwoordbericht. De gegevens in het antwoord zijn afhankelijk van welk werkwoord de app heeft verzonden. De antwoordtekst van een HTTP-aanvraag GET bevat bijvoorbeeld de gegevens voor de aangevraagde resource.

De antwoordtekst van een POST aanvraag retourneert een kopie van de resource die is gemaakt, maar de hoofdtekst van het antwoord van een PUT aanvraag moet leeg zijn.

U moet altijd de statuscode in het antwoordbericht controleren en afhandelen. Als deze statuscode zich in het bereik van 200 (200, 201, 202, enzovoort) bevindt, wordt de bewerking geacht succesvol te zijn, hoewel er later mogelijk verdere informatie nodig is.

Een statuscode in het bereik 300 geeft aan dat de aanvraag mogelijk is omgeleid door de webservice naar een ander adres, mogelijk als gevolg van het verplaatsen van een resource naar een andere locatie.

Een statuscode in het bereik 400 geeft een client- of toepassingsfout aan. Statuscode 403 betekent bijvoorbeeld dat de webservice vereist dat de gebruiker wordt geverifieerd, maar dat de app dit niet heeft gedaan. Statuscode 404 vindt plaats wanneer de app probeert toegang te krijgen tot een resource die niet bestaat.

Statuscodes in het bereik 500 wijzen op een fout aan de serverzijde, zoals dat de service niet beschikbaar is of te druk is om de aanvraag af te handelen.

Het HttpResponseMessage object dat wordt geretourneerd door een aanvraag die via een HttpClient object is ingediend, kan een groot deel van de complexiteit van het verwerken van de verschillende statuscodes abstraheren. Dit codefragment laat zien hoe u kunt controleren of de statuscode in een antwoordbericht geslaagd is en statuscodes verwerkt die duiden op een of andere fout.

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
}

Kenniscontrole

1.

Welk HTTP-werkwoord gebruikt u om een nieuwe resource te maken in een REST-webservice?

2.

Welke methode van de HttpResponseMessage klasse moet u aanroepen om te controleren of een HTTP-aanvraag is geslaagd?"