Korzystanie z usługi internetowej opartej na protokole REST

Przeglądanie przykładu

Representational State Transfer (REST) to styl architektury do tworzenia usług internetowych. Żądania REST są zwykle wykonywane za pośrednictwem protokołu HTTPS przy użyciu tych samych czasowników HTTP, których przeglądarki internetowe używają do pobierania stron internetowych i wysyłania danych na serwery. Czasowniki to:

• GET — ta operacja służy do pobierania danych z usługi internetowej.
• POST — ta operacja służy do tworzenia nowego elementu danych w usłudze internetowej.
• PUT — ta operacja służy do aktualizowania elementu danych w usłudze internetowej.
• PATCH — ta operacja służy do aktualizowania elementu danych w usłudze internetowej, opisując zestaw instrukcji dotyczących sposobu modyfikacji elementu.
• DELETE — ta operacja służy do usuwania elementu danych w usłudze internetowej.

Interfejsy API usług internetowych, które są zgodne z interfejsem REST, są definiowane przy użyciu:

• Podstawowy identyfikator URI.
• Metody HTTP, takie jak GET, POST, PUT, PATCH lub DELETE.
• Typ nośnika danych, taki jak JavaScript Object Notation (JSON).

Usługi internetowe oparte na protokole REST zwykle używają komunikatów JSON do zwracania danych do klienta. JSON to format wymiany danych oparty na tekście, który generuje kompaktowe ładunki, co powoduje zmniejszenie wymagań dotyczących przepustowości podczas wysyłania danych. Prostota interfejsu REST pomogła uczynić ją podstawową metodą uzyskiwania dostępu do usług internetowych w aplikacjach mobilnych.

Uwaga

Uzyskiwanie dostępu do usługi internetowej często wymaga programowania asynchronicznego. Aby uzyskać więcej informacji na temat programowania asynchronicznego, zobacz Asynchroniczne programowanie za pomocą asynchronicznego i await.

Operacje usługi sieci Web

Przykładowa usługa REST jest napisana przy użyciu platformy ASP.NET Core i udostępnia następujące operacje:

Operacja	Metoda HTTP	Względny identyfikator URI	Parametry
Pobieranie listy zadań do wykonania	GET	/api/todoitems/
Tworzenie nowego elementu zadań do wykonania	POST	/api/todoitems/	Format JSON todoItem
Aktualizowanie elementu zadań do wykonania	ODŁÓŻ	/api/todoitems/	Format JSON todoItem
Usuwanie elementu z listą zadań do wykonania	DELETE	/api/todoitems/{id}

Aplikacja .NET MAUI i usługa internetowa używają TodoItem klasy do modelowania danych wyświetlanych i wysyłanych do usługi internetowej na potrzeby magazynu:

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

Właściwość ID służy do unikatowego identyfikowania każdego TodoItem obiektu i jest używana przez usługę internetową do identyfikowania danych, które mają zostać zaktualizowane lub usunięte. Na przykład aby usunąć TodoItem identyfikator, którego identyfikator to 6bb8a868-dba1-4f1a-93b7-24ebce87e243, aplikacja .NET MAUI wysyła żądanie DELETE do https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243.

Gdy platforma internetowego interfejsu API odbiera żądanie, kieruje żądanie do akcji. Te akcje są metodami publicznymi TodoItemsController w klasie . Struktura internetowego interfejsu API używa oprogramowania pośredniczącego routingu do dopasowania adresów URL przychodzących żądań i mapowania ich na akcje. Interfejsy API REST powinny używać routingu atrybutów do modelowania funkcjonalności aplikacji jako zestawu zasobów, których operacje są reprezentowane przez czasowniki HTTP. Routing atrybutów używa zestawu atrybutów do mapowania akcji bezpośrednio na szablony tras. Aby uzyskać więcej informacji na temat routingu atrybutów, zobacz Routing atrybutów dla interfejsów API REST. Aby uzyskać więcej informacji na temat tworzenia usługi REST przy użyciu platformy ASP.NET Core, zobacz Tworzenie usług zaplecza dla natywnych aplikacji mobilnych.

Tworzenie obiektu HTTPClient

Aplikacja interfejsu użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) może korzystać z usługi internetowej opartej na protokole REST, wysyłając żądania do usługi internetowej z klasą HttpClient . Ta klasa udostępnia funkcje wysyłania żądań HTTP i odbierania odpowiedzi HTTP z zidentyfikowanego zasobu identyfikatora URI. Każde żądanie jest wysyłane jako operacja asynchroniczna.

Obiekt HttpClient powinien być zadeklarowany na poziomie klasy, tak aby żył tak długo, jak aplikacja musi wysyłać żądania 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
        };
    }
    ...
}

Obiekt JsonSerializerOptions służy do konfigurowania formatowania ładunku JSON otrzymanego z i wysyłanego do usługi internetowej. Aby uzyskać więcej informacji, zobacz How to instantiate JsonSerializerOptions instances with System.Text.Json (Jak utworzyć wystąpienie wystąpień JsonSerializerOptions za pomocą pliku System.Text.Json).

Pobieranie danych

Metoda HttpClient.GetAsync służy do wysyłania żądania GET do usługi internetowej określonej przez identyfikator URI, a następnie odbierania odpowiedzi z usługi internetowej:

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;
}

Dane są odbierane z usługi internetowej jako HttpResponseMessage obiektu. Zawiera on informacje o odpowiedzi, w tym kod stanu, nagłówki i dowolną treść. Usługa REST wysyła kod stanu HTTP w odpowiedzi, którą można uzyskać z HttpResponseMessage.IsSuccessStatusCode właściwości , aby wskazać, czy żądanie HTTP zakończyło się pomyślnie, czy nie powiodło się. W przypadku tej operacji usługa REST wysyła kod stanu HTTP 200 (OK) w odpowiedzi, co wskazuje, że żądanie powiodło się i że żądane informacje są w odpowiedzi.

Jeśli operacja HTTP zakończyła się pomyślnie, zawartość odpowiedzi jest odczytywana. Właściwość HttpResponseMessage.Content reprezentuje zawartość odpowiedzi i jest typu HttpContent. Klasa HttpContent reprezentuje treść HTTP i nagłówki zawartości, takie jak Content-Type i Content-Encoding. Zawartość jest następnie odczytywana przy string użyciu HttpContent.ReadAsStringAsync metody . Element string jest następnie deserializowany z formatu JSON do List TodoItem obiektu .

Ostrzeżenie

ReadAsStringAsync Użycie metody do pobrania dużej odpowiedzi może mieć negatywny wpływ na wydajność. W takich okolicznościach odpowiedź powinna zostać bezpośrednio zdeserializowana, aby uniknąć konieczności pełnego buforowania.

Tworzenie danych

Metoda HttpClient.PostAsync służy do wysyłania żądania POST do usługi internetowej określonej przez identyfikator URI, a następnie do odbierania odpowiedzi z usługi internetowej:

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);
    }
}

W tym przykładzie TodoItem wystąpienie jest serializowane do ładunku JSON do wysyłania do usługi internetowej. Ten ładunek jest następnie osadzony w treści zawartości HTTP, która zostanie wysłana do usługi internetowej przed wysłaniem żądania za pomocą PostAsync metody .

Usługa REST wysyła kod stanu HTTP w odpowiedzi, którą można uzyskać z HttpResponseMessage.IsSuccessStatusCode właściwości , aby wskazać, czy żądanie HTTP zakończyło się pomyślnie, czy nie powiodło się. Typowe odpowiedzi dla tej operacji to:

• 201 (CREATED) — żądanie spowodowało utworzenie nowego zasobu przed wysłaniem odpowiedzi.
• 400 (NIEPRAWIDŁOWE ŻĄDANIE) — żądanie nie jest zrozumiałe dla serwera.
• 409 (KONFLIKT) — nie można wykonać żądania z powodu konfliktu na serwerze.

Aktualizowanie danych

Metoda HttpClient.PutAsync służy do wysyłania żądania PUT do usługi internetowej określonej przez identyfikator URI, a następnie odbierania odpowiedzi z usługi internetowej:

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

Operacja PutAsync metody jest identyczna z PostAsync metodą używaną do tworzenia danych w usłudze internetowej. Jednak możliwe odpowiedzi wysyłane z usługi internetowej różnią się.

Usługa REST wysyła kod stanu HTTP w odpowiedzi, którą można uzyskać z HttpResponseMessage.IsSuccessStatusCode właściwości , aby wskazać, czy żądanie HTTP zakończyło się pomyślnie, czy nie powiodło się. Typowe odpowiedzi dla tej operacji to:

• 204 (BRAK ZAWARTOŚCI) — żądanie zostało pomyślnie przetworzone, a odpowiedź jest celowo pusta.
• 400 (NIEPRAWIDŁOWE ŻĄDANIE) — żądanie nie jest zrozumiałe dla serwera.
• 404 (NIE ZNALEZIONO) — żądany zasób nie istnieje na serwerze.

Usuwanie danych

Metoda HttpClient.DeleteAsync służy do wysyłania żądania DELETE do usługi internetowej określonej przez identyfikator URI, a następnie odbierania odpowiedzi z usługi internetowej:

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);
    }
}

Usługa REST wysyła kod stanu HTTP w odpowiedzi, którą można uzyskać z HttpResponseMessage.IsSuccessStatusCode właściwości , aby wskazać, czy żądanie HTTP zakończyło się pomyślnie, czy nie powiodło się. Typowe odpowiedzi dla tej operacji to:

• 204 (BRAK ZAWARTOŚCI) — żądanie zostało pomyślnie przetworzone, a odpowiedź jest celowo pusta.
• 400 (NIEPRAWIDŁOWE ŻĄDANIE) — żądanie nie jest zrozumiałe dla serwera.
• 404 (NIE ZNALEZIONO) — żądany zasób nie istnieje na serwerze.

Programowanie lokalne

Jeśli tworzysz lokalnie usługę internetową REST przy użyciu platformy, takiej jak ASP.NET Core Web API, możesz jednocześnie debugować usługę internetową i aplikację MAUI platformy .NET. W tym scenariuszu, aby korzystać z usługi internetowej za pośrednictwem protokołu HTTP z emulatorów systemu Android i symulatorów systemu iOS, musisz włączyć ruch HTTP w postaci zwykłego tekstu w aplikacji .NET MAUI. Aby uzyskać więcej informacji, zobacz Połączenie do lokalnych usług internetowych z emulatorów systemu Android i symulatorów systemu iOS.