Využívání webové služby založené na REST

Článek
05/14/2024

Representational State Transfer (REST) je styl architektury pro vytváření webových služeb. Požadavky REST se obvykle provádějí přes HTTPS pomocí stejných příkazů HTTP, které webové prohlížeče používají k načtení webových stránek a odesílání dat na servery. Příkazy jsou:

GET – tato operace slouží k načtení dat z webové služby.
POST – tato operace slouží k vytvoření nové položky dat ve webové službě.
PUT – tato operace slouží k aktualizaci položky dat ve webové službě.
PATCH – tato operace se používá k aktualizaci položky dat ve webové službě popisem sady pokynů o tom, jak se má položka upravit.
DELETE – tato operace slouží k odstranění položky dat ve webové službě.

Rozhraní API webových služeb, která dodržují REST, jsou definována pomocí:

Základní identifikátor URI.
Metody HTTP, například GET, POST, PUT, PATCH nebo DELETE.
Typ média pro data, například JavaScript Object Notation (JSON).

Webové služby založené na REST obvykle používají zprávy JSON k vrácení dat klientovi. JSON je textový formát výměny dat, který vytváří kompaktní datové části, což má za následek snížení požadavků na šířku pásma při odesílání dat. Jednoduchost REST pomohla, aby byla primární metodou pro přístup k webovým službám v mobilních aplikacích.

Poznámka:

Přístup k webové službě často vyžaduje asynchronní programování. Další informace o asynchronním programování naleznete v tématu Asynchronní programování s asynchronní a await.

Operace webové služby

Ukázková služba REST se zapisuje pomocí ASP.NET Core a poskytuje následující operace:

Operace	Metoda HTTP:	Relativní identifikátor URI	Parametry
Získání seznamu položek úkolů	GET	/api/todoitems/
Vytvoření nové položky úkolu	POST	/api/todoitems/	A JSON formatted TodoItem
Aktualizace položky seznamu úkolů	PUT	/api/todoitems/	A JSON formatted TodoItem
Odstranění položky seznamu úkolů	DELETE	/api/todoitems/{id}

Aplikace .NET MAUI a webová služba používají TodoItem třídu k modelování dat, která se zobrazují a odesílají do webové služby pro úložiště:

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

Vlastnost ID slouží k jedinečné identifikaci jednotlivých TodoItem objektů a používá ji webová služba k identifikaci dat, která se mají aktualizovat nebo odstranit. Pokud chcete například odstranit TodoItem ID, jehož ID je 6bb8a868-dba1-4f1a-93b7-24ebce87e243, aplikace .NET MAUI odešle požadavek DELETE na https://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243.

Když architektura webového rozhraní API obdrží požadavek, směruje požadavek na akci. Tyto akce jsou veřejné metody ve TodoItemsController třídě. Architektura webového rozhraní API používá middleware směrování tak, aby odpovídal adresám URL příchozích požadavků a namapoval je na akce. Rozhraní REST API by měla používat směrování atributů k modelování funkčnosti aplikace jako sady prostředků, jejichž operace jsou reprezentovány příkazy HTTP. Směrování atributů používá sadu atributů k mapování akcí přímo na šablony směrování. Další informace o směrování atributů naleznete v tématu Směrování atributů pro rozhraní REST API. Další informace o vytváření služby REST pomocí ASP.NET Core najdete v tématu Vytváření back-endových služeb pro nativní mobilní aplikace.

Vytvoření objektu HTTPClient

Aplikace .NET Multi-Platform App UI (.NET MAUI) může využívat webovou službu založenou na REST odesláním požadavků do webové služby s HttpClient třídou. Tato třída poskytuje funkce pro odesílání požadavků HTTP a příjem odpovědí HTTP z identifikovaného prostředku URI. Každý požadavek se odešle jako asynchronní operace.

Objekt HttpClient by měl být deklarován na úrovni třídy, aby jeho život trvalo tak dlouho, dokud aplikace potřebuje provádět požadavky 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
        };
    }
    ...
}

Objekt JsonSerializerOptions slouží ke konfiguraci formátování datové části JSON přijaté a odeslané do webové služby. Další informace najdete v tématu Vytvoření instance instancí JsonSerializerOptions pomocí System.Text.Json.

Načtení dat

Metoda HttpClient.GetAsync se používá k odeslání požadavku GET webové službě určené identifikátorem URI a přijetí odpovědi z webové služby:

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

Data se z webové služby přijímají jako HttpResponseMessage objekt. Obsahuje informace o odpovědi, včetně stavového kódu, záhlaví a libovolného textu. Služba REST odešle stavový kód HTTP v odpovědi, který lze získat z HttpResponseMessage.IsSuccessStatusCode vlastnosti, aby indikovala, zda požadavek HTTP byl úspěšný nebo neúspěšný. Pro tuto operaci služba REST odešle stavový kód HTTP 200 (OK) v odpovědi, která indikuje, že požadavek byl úspěšný a že požadované informace jsou v odpovědi.

Pokud byla operace HTTP úspěšná, přečte se obsah odpovědi. Vlastnost HttpResponseMessage.Content představuje obsah odpovědi a je typu HttpContent. Třída HttpContent představuje tělo HTTP a hlavičky obsahu, například Content-Type a Content-Encoding. Obsah se pak načte string do metody.HttpContent.ReadAsStringAsync Pak string se deserializuje z JSON na ListTodoItem objekty.

Upozorňující

ReadAsStringAsync Použití metody k načtení velké odpovědi může mít negativní dopad na výkon. Za takových okolností by odpověď měla být přímo deserializována, aby se nemusela plně ukládat do vyrovnávací paměti.

Vytvoření dat

Metoda HttpClient.PostAsync se používá k odeslání požadavku POST webové službě určené identifikátorem URI a následnému přijetí odpovědi z webové služby:

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

V tomto příkladu TodoItem je instance serializována do datové části JSON pro odesílání do webové služby. Tato datová část se pak vloží do textu obsahu HTTP, který se odešle do webové služby před provedením požadavku pomocí PostAsync metody.

Služba REST odešle stavový kód HTTP v odpovědi, který lze získat z HttpResponseMessage.IsSuccessStatusCode vlastnosti, aby indikovala, zda požadavek HTTP byl úspěšný nebo neúspěšný. Typické odpovědi pro tuto operaci jsou:

201 (CREATED) – požadavek způsobil vytvoření nového prostředku před odesláním odpovědi.
400 (CHYBNÝ POŽADAVEK) – požadavek není serverem srozumitelný.
409 (CONFLICT) – požadavek nelze provést kvůli konfliktu na serveru.

Aktualizace dat

Metoda HttpClient.PutAsync se používá k odeslání požadavku PUT webové službě určené identifikátorem URI a přijetí odpovědi z webové služby:

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

Operace PutAsync metody je stejná jako PostAsync metoda, která se používá k vytváření dat ve webové službě. Možné odpovědi odeslané z webové služby se však liší.

204 (BEZ OBSAHU) – požadavek byl úspěšně zpracován a odpověď je záměrně prázdná.
400 (CHYBNÝ POŽADAVEK) – požadavek není serverem srozumitelný.
404 (NENALEZENA) – požadovaný prostředek na serveru neexistuje.

Odstranění dat

Metoda HttpClient.DeleteAsync se používá k odeslání požadavku DELETE webové službě určené identifikátorem URI a přijetí odpovědi z webové služby:

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

204 (BEZ OBSAHU) – požadavek byl úspěšně zpracován a odpověď je záměrně prázdná.
400 (CHYBNÝ POŽADAVEK) – požadavek není serverem srozumitelný.
404 (NENALEZENA) – požadovaný prostředek na serveru neexistuje.

Místní vývoj

Pokud vyvíjíte webovou službu REST místně s architekturou, jako je webové rozhraní API ASP.NET Core, můžete webovou službu a aplikaci .NET MAUI ladit současně. V tomto scénáři musíte v aplikaci .NET MAUI povolit přenosy HTTP přes PROTOKOL HTTP z emulátorů Androidu a simulátorů iOS. Další informace najdete v tématu Připojení k místním webovým službám z emulátorů Androidu a simulátorů iOS.

Share via