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

Обзор примера

Передача репрезентативного состояния (REST) — это архитектурный стиль для создания веб-служб. Запросы REST обычно выполняются по протоколу HTTPS, используя те же HTTP-команды, которые веб-браузеры используют для получения веб-страниц и отправки данных на серверы. Ниже приведен перечень команд.

• GET — эта операция используется для получения данных из веб-службы.
• POST — эта операция используется для создания нового элемента данных в веб-службе.
• PUT — эта операция используется для обновления элемента данных в веб-службе.
• PATCH — эта операция используется для обновления элемента данных веб-службы путем описания набора инструкций по изменению элемента.
• DELETE — эта операция используется для удаления элемента данных в веб-службе.

API веб-службы, которые соответствуют REST, определяются с помощью:

• Базовый универсальный код ресурса (URI).
• Методы HTTP, такие как GET, POST, WHERE, PATCH или DELETE.
• Тип носителя для данных, например нотация объектов JavaScript (JSON).

Веб-службы на основе REST обычно используют сообщения JSON для возврата данных клиенту. JSON — это текстовый формат обмена данными, который создает компактные полезные данные, что приводит к снижению требований к пропускной способности при отправке данных. Простота REST помогла сделать его основным методом для доступа к веб-службам в мобильных приложениях.

Примечание.

Для доступа к веб-службе часто требуется асинхронное программирование. Дополнительные сведения об асинхронном программировании см. в статье асинхронное программирование с асинхронным программированием и ожиданием.

Операции веб-службы

Пример службы REST записывается с помощью ASP.NET Core и предоставляет следующие операции:

Операция	Метод HTTP	Относительный универсальный код ресурса (URI)	Параметры
Получение списка элементов todo	GET	/api/todoitems/
Создание нового элемента todo	POST	/api/todoitems/	Формат JSON TodoItem
Обновление элемента todo	PUT	/api/todoitems/	Формат JSON TodoItem
Удаление элемента todo	DELETE	/api/todoitems/{id}

Приложение .NET MAUI и веб-служба используют TodoItem класс для моделирования данных, отображаемых и отправленных в веб-службу для хранения:

public class TodoItem
{
    public string ID { get; set; }
    public string Name { get; set; }
    public string Notes { get; set; }
    public bool Done { get; set; }
}

Свойство ID используется для уникальной идентификации каждого TodoItem объекта и используется веб-службой для идентификации данных для обновления или удаления. Например, чтобы удалить TodoItem идентификатор 6bb8a868-dba1-4f1a-93b7-24ebce87e243, приложение .NET MAUI отправляет запрос https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243DELETE.

Когда платформа веб-API получает запрос, он направляет запрос в действие. Эти действия являются общедоступными методами TodoItemsController в классе. Платформа веб-API использует ПО промежуточного слоя маршрутизации, чтобы сопоставить URL-адреса входящих запросов и сопоставить их с действиями. REST API должны использовать маршрутизацию атрибутов для моделирования функциональных возможностей приложения в виде набора ресурсов, операции которых представлены HTTP-командами. При маршрутизации с помощью атрибутов используется набор атрибутов для сопоставления действий непосредственно с шаблонами маршрутов. Дополнительные сведения о маршрутизации атрибутов см. в разделе "Маршрутизация атрибутов" для REST API. Дополнительные сведения о создании службы REST с помощью ASP.NET Core см. в статье "Создание серверных служб для собственных мобильных приложений".

Создание объекта HTTPClient

Приложение .NET Multi-platform App UI (.NET MAUI) может использовать веб-службу на основе REST, отправляя запросы в веб-службу с HttpClient помощью класса. Этот класс предоставляет функциональные возможности для отправки HTTP-запросов и получения HTTP-ответов из определяемого ресурса URI. Каждый запрос отправляется как асинхронная операция.

Объект HttpClient должен быть объявлен на уровне класса, чтобы он работал до тех пор, пока приложение должно выполнять HTTP-запросы:

public class RestService
{
    HttpClient _client;
    JsonSerializerOptions _serializerOptions;

    public List<TodoItem> Items { get; private set; }

    public RestService()
    {
        _client = new HttpClient();
        _serializerOptions = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            WriteIndented = true
        };
    }
    ...
}

Объект JsonSerializerOptions используется для настройки форматирования полезных данных JSON, полученных и отправленных в веб-службу. Дополнительные сведения см. в статье Создание экземпляров экземпляров JsonSerializerOptions с помощью System.Text.Json.

Извлечение данных

Метод HttpClient.GetAsync используется для отправки запроса GET в веб-службу, указанную URI, а затем получает ответ от веб-службы:

public async Task<List<TodoItem>> RefreshDataAsync()
{
    Items = new List<TodoItem>();

    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));
    try
    {
        HttpResponseMessage response = await _client.GetAsync(uri);
        if (response.IsSuccessStatusCode)
        {
            string content = await response.Content.ReadAsStringAsync();
            Items = JsonSerializer.Deserialize<List<TodoItem>>(content, _serializerOptions);
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }

    return Items;
}

Данные получаются из веб-службы в качестве HttpResponseMessage объекта. Он содержит сведения об ответе, включая код состояния, заголовков и любой текст. Служба REST отправляет код состояния HTTP в ответе, который можно получить из HttpResponseMessage.IsSuccessStatusCode свойства, чтобы указать, выполнен ли HTTP-запрос успешно или завершился сбоем. Для этой операции служба REST отправляет код состояния HTTP 200 (ОК) в ответе, который указывает, что запрос выполнен успешно и что запрошенная информация находится в ответе.

Если операция HTTP прошла успешно, содержимое ответа считывается. Свойство HttpResponseMessage.Content представляет содержимое ответа и имеет тип HttpContent. HttpContent Класс представляет тело HTTP и заголовки содержимого, таких как Content-Type и Content-Encoding. Затем содержимое считывается в string метод с помощью HttpContent.ReadAsStringAsync метода. Затем десериализируется string из JSON в List TodoItem объекты.

Предупреждение

ReadAsStringAsync Использование метода для получения большого ответа может оказать негативное влияние на производительность. В таких случаях ответ должен быть непосредственно десериализирован, чтобы избежать необходимости полностью буферизировать его.

Создание данных

Метод HttpClient.PostAsync используется для отправки запроса POST в веб-службу, указанную URI, а затем для получения ответа от веб-службы:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, string.Empty));

    try
    {
        string json = JsonSerializer.Serialize<TodoItem>(item, _serializerOptions);
        StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

        HttpResponseMessage response = null;
        if (isNewItem)
            response = await _client.PostAsync(uri, content);
        else
            response = await _client.PutAsync(uri, content);

        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully saved.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

В этом примере TodoItem экземпляр сериализуется в полезные данные JSON для отправки в веб-службу. Затем эта полезные данные внедряется в текст http-содержимого, которое будет отправлено веб-службе перед выполнением запроса с PostAsync помощью метода.

Служба REST отправляет код состояния HTTP в ответе, который можно получить из HttpResponseMessage.IsSuccessStatusCode свойства, чтобы указать, выполнен ли HTTP-запрос успешно или завершился сбоем. Типичные ответы для этой операции:

• 201 (CREATED) — запрос привел к созданию нового ресурса до отправки ответа.
• 400 (BAD REQUEST) — запрос не понимается сервером.
• 409 (CONFLICT) — запрос не удалось выполнить из-за конфликта на сервере.

Обновление данных

Метод HttpClient.PutAsync используется для отправки запроса PUT в веб-службу, указанную URI, а затем получает ответ от веб-службы:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  response = await _client.PutAsync(uri, content);
  ...
}

Операция PutAsync метода идентична PostAsync методу, который используется для создания данных в веб-службе. Однако возможные ответы, отправленные из веб-службы, отличаются.

Служба REST отправляет код состояния HTTP в ответе, который можно получить из HttpResponseMessage.IsSuccessStatusCode свойства, чтобы указать, выполнен ли HTTP-запрос успешно или завершился сбоем. Типичные ответы для этой операции:

• 204 (NO CONTENT) — запрос успешно обработан и ответ намеренно пуст.
• 400 (BAD REQUEST) — запрос не понимается сервером.
• 404 (NOT FOUND) — запрошенный ресурс не существует на сервере.

Удаление данных

Метод HttpClient.DeleteAsync используется для отправки запроса DELETE в веб-службу, указанную URI, а затем получает ответ от веб-службы:

public async Task DeleteTodoItemAsync(string id)
{
    Uri uri = new Uri(string.Format(Constants.RestUrl, id));

    try
    {
        HttpResponseMessage response = await _client.DeleteAsync(uri);
        if (response.IsSuccessStatusCode)
            Debug.WriteLine(@"\tTodoItem successfully deleted.");
    }
    catch (Exception ex)
    {
        Debug.WriteLine(@"\tERROR {0}", ex.Message);
    }
}

Служба REST отправляет код состояния HTTP в ответе, который можно получить из HttpResponseMessage.IsSuccessStatusCode свойства, чтобы указать, выполнен ли HTTP-запрос успешно или завершился сбоем. Типичные ответы для этой операции:

• 204 (NO CONTENT) — запрос успешно обработан и ответ намеренно пуст.
• 400 (BAD REQUEST) — запрос не понимается сервером.
• 404 (NOT FOUND) — запрошенный ресурс не существует на сервере.

Сервер локальной

Если вы разрабатываете веб-службу REST локально с помощью платформы, например ASP.NET Веб-API Core, вы можете выполнять отладку веб-службы и приложения .NET MAUI одновременно. В этом сценарии для использования веб-службы по протоколу HTTP из эмуляторов Android и симуляторов iOS необходимо включить чистый http-трафик в приложении .NET MAUI. Дополнительные сведения см. в разделе Подключение локальных веб-служб из эмуляторов Android и симуляторов iOS.