Consumir um serviço REST com HttpClient
Muitos serviços Web modernos implementam a arquitetura REST. Essa estrutura permite que um serviço Web exponha operações e dados por meio de uma série de pontos de extremidade bem definidos. As solicitações que os aplicativos cliente enviam a um serviço Web REST para recuperar, modificar, criar ou excluir dados usam um conjunto predefinido de verbos. Um serviço Web REST responde a essas solicitações de maneira padrão. Essa abordagem facilita a construção de aplicativos cliente.
O modelo REST é construído sobre o protocolo HTTP. Um aplicativo .NET MAUI pode enviar solicitações para um serviço Web REST usando a HttpClient classe. Nesta unidade, você aprenderá sobre HttpClient e como usá-lo para interagir com um serviço Web REST.
O que é a classe HttpClient?
HttpClient é uma classe .NET que um aplicativo pode usar para enviar solicitações HTTP e receber respostas HTTP de um serviço Web REST. Um conjunto de URIs identifica os recursos que o serviço Web expõe. Um URI combina o endereço do serviço Web com o nome de um recurso disponível nesse endereço.
A HttpClient classe usa uma API baseada em tarefas para desempenho e fornece acesso a informações em mensagens de solicitação, como cabeçalhos HTTP e códigos de status, bem como corpos de mensagens que contêm os dados reais que estão sendo enviados e recebidos.
A HttpClient classe está disponível no System.Net.Http namespace. Um aplicativo pode criar um HttpClient objeto usando o construtor padrão:
using System.Net.Http;
...
var client = new HttpClient();
Executar operações CRUD com um objeto HttpClient
Um serviço Web REST permite que um cliente execute operações em dados por meio de um conjunto de verbos HTTP. O trabalho do verbo HTTP é indicar a ação desejada a ser executada em um recurso. Existem muitos verbos HTTP, mas os quatro mais comuns são POST, GET, PUT, e DELETE. Um serviço pode implementar esses verbos para permitir que um aplicativo cliente gerencie o ciclo de vida dos objetos executando operações CRUD (Create, Read, Update and Delete), da seguinte maneira:
O
POSTverbo indica que você deseja criar um novo recurso.O
GETverbo indica que você deseja recuperar um recurso.O
PUTverbo indica que você deseja atualizar um recurso.O
DELETEverbo indica que você deseja excluir um recurso.
Criar um novo recurso com HttpClient
Para criar um novo recurso usando HttpCliento , você pode usar o SendAsync método passando-lhe um HttpRequestMessage objeto.
O HttpRequestMessage destina-se a modelar a solicitação que é enviada para o serviço Web. Você especifica o verbo HTTP, a URL do serviço Web e preenche qualquer carga a ser enviada por meio da HttpRequestMessage.Content propriedade.
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Este fragmento de código executa as seguintes tarefas:
- Ele cria uma instância do
HttpClientcliente chamado que ele usa para enviar uma mensagem. - Ele cria uma instância de
HttpRequestMessagemensagem chamada que ele usa para modelar a mensagem. A mensagem tem o verbo HTTP e URL. - Ele define a
Contentpropriedade doHttpRequestMessage, usando aJsonContent.Createfunção. Essa função serializa automaticamente a variável part em JSON adequado para envio ao serviço Web. - Ele envia a mensagem usando o
HttpClientobjeto. É retornado umHttpResponseMessageque contém informações como o código de status e informações retornadas pelo serviço Web.
Ler um recurso com HttpClient
Você pode ler um recurso de um serviço Web usando a mesma técnica descrita anteriormente, exceto inicializando o HttpRequestMessage com um HttpMethod.Getarquivo . No entanto, o HttpClient tem um par de métodos de conveniência que fornecem atalhos.
Para ler um recurso usando HTTPCliento , use o GetStringAsync método conforme mostrado no exemplo a seguir:
HttpClient client = new HttpClient();
string text = await client.GetStringAsync("https://...");
O GetStringAsync método usa um URI que faz referência ao recurso e retorna uma resposta como uma cadeia de caracteres. A resposta da cadeia de caracteres é o recurso que o aplicativo solicitou. O formato de dados de resposta é o padrão para o serviço solicitado, como JSON ou XML. Um aplicativo pode dizer ao serviço Web que ele exige que os dados sejam retornados em um formato específico adicionando o MediaTypeWithQualityHeaderValue cabeçalho. Por exemplo, se o aplicativo solicitar que os dados sejam enviados de volta no formato JSON, ele poderá usar o seguinte código:
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
Neste exemplo, o resultado é retornado como uma cadeia de caracteres e contém apenas o corpo da mensagem de resposta. Para obter a resposta completa, incluindo cabeçalhos, corpo e código de status, chame o GetAsync método. Os dados são retornados como um HttpResponseMessage objeto.
Atualizar um recurso com HttpClient
Para atualizar um recurso usando HttpClient, use um HttpRequestMessage inicializado com um verbo PUT . O código a seguir é semelhante ao necessário para criar um novo recurso:
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);
message.Content = JsonContent.Create<Part>(part);
HttpResponseMessage response = await client.SendAsync(message);
Nota
A diferença fundamental entre POST e PUT é a idempotência. Se você repetir a mesma PUT solicitação várias vezes, o mesmo recurso será atualizado com os mesmos dados e o efeito será o mesmo como se a solicitação tivesse sido enviada apenas uma vez. Se você emitir a mesma POST solicitação várias vezes, o resultado será o serviço REST criando várias cópias do recurso.
Excluir um recurso com HttpClient
Para excluir um recurso usando HttpClient, chame SendAsync com um HttpRequestMessage inicializado com um verbo DELETE :
HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);
HttpResponseMessage response = await client.SendAsync(message);
A resposta contém os cabeçalhos, o código de status e o objeto excluído.
Lidar com respostas de uma solicitação
Todas as solicitações HTTP retornam uma mensagem de resposta. Os dados na resposta dependem de qual verbo o aplicativo enviou. Por exemplo, o corpo de resposta de uma solicitação HTTP GET contém os dados para o recurso solicitado.
O corpo de resposta de uma POST solicitação retorna uma cópia do recurso que foi criado, mas o corpo de resposta de uma PUT solicitação deve estar vazio.
Você deve sempre verificar e manipular o código de status na mensagem de resposta. Se esse código de status estiver no intervalo de 200 (200, 201, 202 e assim por diante), a operação será considerada bem-sucedida, embora mais informações possam ser necessárias posteriormente.
Um código de status no intervalo 300 indica que a solicitação pode ter sido redirecionada pelo serviço Web para um endereço diferente, possivelmente como resultado de um recurso se mover para um local diferente.
Um código de status no intervalo 400 indica um erro de cliente ou aplicativo. Por exemplo, o código de status 403 significa que o serviço Web exige que o usuário seja autenticado, mas o aplicativo não fez isso. O código de status 404 ocorre quando o aplicativo tenta acessar um recurso que não existe.
Os códigos de status no intervalo 500 são indicativos de um erro do lado do servidor, como o serviço estar indisponível ou muito ocupado para lidar com a solicitação.
O HttpResponseMessage objeto retornado por uma solicitação enviada por meio de um HttpClient objeto pode abstrair grande parte da complexidade de lidar com os diferentes códigos de status. Este fragmento de código mostra como verificar se o código de status em uma mensagem de resposta indica sucesso e manipular códigos de status que indicam algum tipo de falha.
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
}