Использование службы REST с HttpClient

  • 5 мин

Многие современные веб-службы реализуют архитектуру REST. Эта архитектура позволяет веб-службе предоставлять операции и данные через несколько четко определенных конечных точек. Запросы, отправляемые клиентскими приложениями в веб-службу REST для получения, изменения, создания или удаления данных, используют заранее определенный набор команд. Веб-служба REST реагирует на эти запросы стандартным образом. Такой подход упрощает создание клиентских приложений.

Модель REST основана на протоколе HTTP. Приложение .NET MAUI может отправлять запросы в веб-службу REST с помощью класса HttpClient. В этом уроке вы узнаете о HttpClient том, как использовать его для взаимодействия с веб-службой REST.

Что такое класс HttpClient?

HttpClient представляет собой класс .NET, который позволяет приложению отправлять HTTP-запросы и получать HTTP-ответы через веб-службу REST. Набор URI определяет ресурсы, предоставляемые веб-службой. В строке URI адрес веб-службы объединяется с именем ресурса, доступного по этому адресу.

Класс HttpClient использует API на основе задач для повышения производительности и предоставляет доступ к информации в сообщениях запроса, таких как заголовки HTTP и коды состояния, а также тела сообщений, содержащие фактические данные, отправляемые и полученные.

Схема, показывающая, как клиентское приложение использует объект HttpClient для отправки и получения HTTP-сообщений и ответов

Класс HttpClient находится в пространстве имен System.Net.Http. Приложение может создать объект HttpClient с помощью конструктора по умолчанию:

using System.Net.Http;
...

var client = new HttpClient();

Выполнение операций CRUD для объекта HttpClient

Веб-служба REST позволяет клиенту выполнять операции с данными с помощью набора HTTP-команд. Задание команды HTTP заключается в том, чтобы указать требуемое действие, которое необходимо выполнить в ресурсе. Существует множество HTTP-команд, но четыре из них используются чаще всего: POST, GET, PUT и DELETE. Служба может реализовать эти команды, чтобы клиентское приложение могло управлять жизненным циклом объектов, выполняя операции создания, чтения, обновления и удаления (CRUD) для следующих целей.

  • Команда POST указывает, что вы хотите создать ресурс.

  • Команда GET указывает, что вы хотите получить ресурс.

  • Команда PUT указывает, что вы хотите обновить ресурс.

  • Команда DELETE указывает, что вы хотите удалить ресурс.

Схема, показывающая основные операции CRUD, которые может реализовать служба REST, включая получение, запись, размещение и удаление.

Создание ресурса с помощью HttpClient

Чтобы создать новый ресурс с помощью HttpClient, можно использовать SendAsync метод передачи HttpRequestMessage объекта.

Здесь HttpRequestMessage моделирует запроса, отправляемый в веб-службу. Укажите HTTP-команду, URL-адрес веб-службы и все полезные данные, которые нужно отправить, в свойстве 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);

Этот фрагмент кода выполняет следующие задачи.

  • Он создает экземпляр HttpClient с именем client, который затем применяет отправки сообщения.
  • Он создает экземпляр HttpRequestMessage с именем message, который затем применяет для создания сообщения. Экземпляр message содержит HTTP-команду и URL-адрес.
  • Он задает свойство Content для HttpRequestMessage, используя функцию JsonContent.Create. Эта функция автоматически сериализует переменную части в JSON, подходящую для отправки в веб-службу.
  • Он отправляет сообщение с помощью объекта HttpClient. Возвращаемое значение HttpResponseMessage содержит такие сведения, как код состояния и данные, полученные от веб-службы.

Чтение ресурса с помощью HttpClient

Вы можете прочитать ресурс из веб-службы, используя тот же метод, что и ранее описано, за исключением инициализации HttpRequestMessage с помощью .HttpMethod.Get Однако есть HttpClient несколько удобных методов, которые предоставляют сочетания клавиш.

Чтобы считать ресурс с помощью HTTPClient, используйте метод GetStringAsync, как показано в следующем примере:

HttpClient client = new HttpClient();

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

Метод GetStringAsync принимает URI, который ссылается на ресурс и возвращает ответ в виде строки. Эта строка содержит ресурс, запрошенный приложением. Формат данных ответа — это значение по умолчанию для запрошенной службы, например JSON или XML. Приложение может сообщить веб-службе, что данные должны возвращаться в определенном формате, добавив заголовок MediaTypeWithQualityHeaderValue. Например, если приложению нужен ответ в формате JSON, оно может использовать следующий код:

HttpClient client = new HttpClient();

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

В этом примере результат возвращается в строковом формате и содержит только текст ответного сообщения. Чтобы получить весь ответ, включая заголовки, текст и код состояния, вызовите метод GetAsync. Данные возвращаются в виде объекта HttpResponseMessage.

Обновление ресурса с помощью HttpClient

Чтобы обновить ресурс с помощью класса HttpClient, используйте метод HttpRequestMessage, задав для него команду PUT. Следующий код создает пример запроса для создания нового ресурса:

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

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

HttpResponseMessage response = await client.SendAsync(message);

Примечание.

Основные различия между POST и PUT заключаются в идемпотентности. Если вы несколько раз повторите одинаковый запрос PUT, один и тот же ресурс будет обновляться с использованием одних тех же данных, то есть конечный результат будет таким же, как при однократном выполнении такого запроса. При выполнении одного POST запроса несколько раз результатом будет служба REST, создавая несколько копий ресурса.

Удаление ресурса с помощью HttpClient

Чтобы удалить ресурс с помощью, вызовите SendAsync инициализированную HttpRequestMessage с помощью HttpClientкоманды DELETE:

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

HttpResponseMessage response = await client.SendAsync(message);

Ответ содержит заголовки, код состояния и удаленный объект.

Обработка ответов на запрос

Все HTTP-запросы возвращают ответное сообщение. Данные в ответе зависят от команды, от которой отправляется приложение. Например, текст ответа для HTTP-запроса GET содержит данные о запрошенном ресурсе.

Текст POST ответа запроса возвращает копию созданного ресурса, но текст PUT ответа запроса должен быть пустым.

Не забывайте проверять и обрабатывать код состояния в ответном сообщении. Если этот код состояния находится в диапазоне 200 (200, 201, 202 и т. д.), операция считается успешной, хотя дополнительные сведения могут потребоваться позже.

Код состояния в диапазоне 300 указывает, что запрос может быть перенаправлен веб-службой на другой адрес, возможно, в результате перемещения ресурса в другое расположение.

Код состояния в диапазоне 400 указывает на ошибку в клиенте или в приложении. Например, код состояния 403 означает, что приложение не выполнило обязательную для веб-службы проверку подлинности пользователя. Код состояния 404 означает, что приложение пытается получить доступ к несуществующему ресурсу.

Коды состояния в диапазоне 500 означают ошибку на стороне сервера, например, если служба недоступна или слишком загружена для обработки нового запроса.

Объект HttpResponseMessage, возвращаемый запросом, отправленным через объект HttpClient, может оградить приложение от значительной части работы по обработке кодов состояния. В этом фрагменте кода показано, как проверить, что код состояния в ответном сообщении указывает на успешность и обрабатывает коды состояния, указывающие на какой-то сбой.

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
}

Проверка знаний

1.

Какую команду HTTP нужно использовать для создания нового ресурса в веб-службе REST?

2.

Какой метод класса HttpResponseMessage слеудет вызвать для проверки успешности HTTP-запроса?