Využívání webové služby RESTful

Článek
03/05/2024

Běžným scénářem je integrace webové služby do aplikace. Tento článek ukazuje, jak využívat webovou službu RESTful z Xamarin.Forms aplikace.

Representational State Transfer (REST) je styl architektury pro vytváření webových služeb. Požadavky REST se provádějí přes HTTP 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. Toto sloveso se v ukázkové aplikaci nepoužívá.
DELETE – tato operace slouží k odstranění položky dat ve webové službě.

Rozhraní API webové služby, která dodržují REST, se nazývají rozhraní RESTful API a definují se 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 RESTful 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. Ukázková aplikace používá opensourcovou knihovnu NewtonSoft JSON.NET k serializaci a deserializaci zpráv.

Jednoduchost rest pomohla, aby byla primární metodou pro přístup k webovým službám v mobilních aplikacích.

Po spuštění ukázkové aplikace se připojí k místně hostované službě REST, jak je znázorněno na následujícím snímku obrazovky:

Sample Application

Poznámka:

V iOSu 9 a novějších vynucuje služba App Transport Security (ATS) zabezpečená připojení mezi internetovými prostředky (například back-endovým serverem aplikace) a aplikací, což brání náhodnému zpřístupnění citlivých informací. Vzhledem k tomu, že služba ATS je ve výchozím nastavení povolená v aplikacích vytvořených pro iOS 9, budou všechna připojení podléhat požadavkům na zabezpečení ATS. Pokud připojení nesplňují tyto požadavky, dojde k selhání s výjimkou.

ATS se dá odhlásit, pokud není možné používat protokol HTTPS a zabezpečenou komunikaci pro internetové prostředky. Toho lze dosáhnout aktualizací souboru Info.plist aplikace. Další informace najdete v tématu App Transport Security.

Využívání webové služby

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 úkolu	PUT	/api/todoitems/	A JSON formatted TodoItem
Odstranění položky úkolu	DELETE	/api/todoitems/{id}

Většina identifikátorů URI obsahuje TodoItem ID v cestě. Chcete-li například odstranit TodoItem ID, jehož ID je 6bb8a868-dba1-4f1a-93b7-24ebce87e243, klient odešle požadavek DELETE na http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243. Další informace o datovém modelu použitém v ukázkové aplikaci najdete v tématu Modelování dat.

Když architektura webového rozhraní API obdrží požadavek, směruje požadavek na akci. Tyto akce jsou jednoduše veřejné metody ve TodoItemsController třídě. Architektura používá middleware směrování ke spárování adres URL příchozích požadavků a jejich mapování na akce. Rozhraní REST API by měla používat směrování atributů, které model funkce aplikace používá jako sadu 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 naleznete v tématu Vytváření back-endových služeb pro nativní mobilní aplikace.

Třída HttpClient se používá k odesílání a přijímání požadavků přes PROTOKOL HTTP. Poskytuje funkce pro odesílání požadavků HTTP a přijímání odpovědí HTTP z identifikovaného prostředku URI. Každý požadavek se odešle jako asynchronní operace. Další informace o asynchronníchoperacích

Třída HttpResponseMessage představuje zprávu odpovědi HTTP přijatou z webové služby po provedení požadavku HTTP. Obsahuje informace o odpovědi, včetně stavového kódu, záhlaví a libovolného textu. Třída HttpContent představuje tělo HTTP a hlavičky obsahu, například Content-Type a Content-Encoding. Obsah lze číst pomocí některé z ReadAs metod, například ReadAsStringAsync a ReadAsByteArrayAsyncv závislosti na formátu dat.

Vytvoření objektu HTTPClient

Instance HttpClient je deklarována na úrovni třídy tak, aby objekt žije tak dlouho, dokud aplikace potřebuje provádět požadavky HTTP, jak je znázorněno v následujícím příkladu kódu:

public class RestService : IRestService
{
  HttpClient client;
  ...

  public RestService ()
  {
    client = new HttpClient ();
    ...
  }
  ...
}

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, jak je znázorněno v následujícím příkladu kódu:

public async Task<List<TodoItem>> RefreshDataAsync ()
{
  ...
  Uri uri = new Uri (string.Format (Constants.TodoItemsUrl, string.Empty));
  ...
  HttpResponseMessage response = await client.GetAsync (uri);
  if (response.IsSuccessStatusCode)
  {
      string content = await response.Content.ReadAsStringAsync ();
      Items = JsonSerializer.Deserialize<List<TodoItem>>(content, serializerOptions);
  }
  ...
}

Služba REST odešle stavový kód HTTP ve HttpResponseMessage.IsSuccessStatusCode vlastnosti, který indikuje, jestli 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á, obsah odpovědi se přečte pro zobrazení. Vlastnost HttpResponseMessage.Content představuje obsah odpovědi HTTP a HttpContent.ReadAsStringAsync metoda asynchronně zapisuje obsah HTTP do řetězce. Tento obsah se pak deserializuje z JSON na ListTodoItem instanci.

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, jak je znázorněno v následujícím příkladu kódu:

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

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

  if (response.IsSuccessStatusCode)
  {
    Debug.WriteLine (@"\tTodoItem successfully saved.");
  }
  ...
}

Instance TodoItem je 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 ve HttpResponseMessage.IsSuccessStatusCode vlastnosti, který indikuje, jestli požadavek HTTP byl úspěšný nebo neúspěšný. Mezi běžné odpovědi pro tuto operaci patří:

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, jak je znázorněno v následujícím příkladu kódu:

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, jak je znázorněno v následujícím příkladu kódu:

public async Task DeleteTodoItemAsync (string id)
{
  Uri uri = new Uri (string.Format (Constants.TodoItemsUrl, id));
  ...
  HttpResponseMessage response = await client.DeleteAsync (uri);
  if (response.IsSuccessStatusCode)
  {
    Debug.WriteLine (@"\tTodoItem successfully deleted.");
  }
  ...
}

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 mobilní aplikaci ladit současně. V tomto scénáři musíte pro simulátor iOS a emulátor Android povolit přenosy HTTP s vymazáním textu. Informace o konfiguraci projektu tak, aby umožňovaly komunikaci, najdete v tématu Připojení s místními webovými službami.