Korzystanie z usługi internetowej RESTful

Pobieranie przykładu

Integrowanie usługi internetowej z aplikacją jest typowym scenariuszem. W tym artykule pokazano, jak korzystać z usługi internetowej RESTful z Xamarin.Forms poziomu aplikacji.

Representational State Transfer (REST) to styl architektury do tworzenia usług internetowych. Żądania REST są wykonywane za pośrednictwem protokołu HTTP przy użyciu tych samych czasowników HTTP, których przeglądarki internetowe używają do pobierania stron internetowych i wysyłania danych do serwerów. 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. To zlecenie nie jest używane w przykładowej aplikacji.
• DELETE — ta operacja służy do usuwania elementu danych w usłudze internetowej.

Interfejsy API usługi internetowej, które są zgodne z interfejsem REST, są nazywane interfejsami API RESTful i 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 RESTful 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. Przykładowa aplikacja używa biblioteki NewtonSoft JSON.NET typu open source do serializacji i deserializacji komunikatów.

Prostota interfejsu REST pomogła uczynić ją podstawową metodą uzyskiwania dostępu do usług internetowych w aplikacjach mobilnych.

Po uruchomieniu przykładowej aplikacji połączy się ona z lokalnie hostowaną usługą REST, jak pokazano na poniższym zrzucie ekranu:

Uwaga

W systemie iOS 9 lub nowszym usługa App Transport Security (ATS) wymusza bezpieczne połączenia między zasobami internetowymi (takimi jak serwer zaplecza aplikacji) i aplikacją, co uniemożliwia przypadkowe ujawnienie poufnych informacji. Ponieważ usługa ATS jest domyślnie włączona w aplikacjach utworzonych dla systemu iOS 9, wszystkie połączenia będą objęte wymaganiami dotyczącymi zabezpieczeń usługi ATS. Jeśli połączenia nie spełniają tych wymagań, zakończy się niepowodzeniem z wyjątkiem.

Usługa ATS może zrezygnować z korzystania z protokołu HTTPS i bezpiecznej komunikacji dla zasobów internetowych. Można to osiągnąć, aktualizując plik Info.plist aplikacji. Aby uzyskać więcej informacji, zobacz App Transport Security.

Korzystanie z usługi internetowej

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 elementów do wykonania	GET	/api/todoitems/
Tworzenie nowego elementu do wykonania	POST	/api/todoitems/	Format JSON todoItem
Aktualizowanie elementu do wykonania	ODŁÓŻ	/api/todoitems/	Format JSON todoItem
Usuwanie elementu do wykonania	DELETE	/api/todoitems/{id}

Większość identyfikatorów URI zawiera TodoItem identyfikator w ścieżce. Aby na przykład usunąć TodoItem identyfikator, którego identyfikator to 6bb8a868-dba1-4f1a-93b7-24ebce87e243, klient wysyła żądanie DELETE do http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243. Aby uzyskać więcej informacji na temat modelu danych używanego w przykładowej aplikacji, zobacz Modelowanie danych.

Gdy platforma internetowego interfejsu API odbiera żądanie, kieruje żądanie do akcji. Te akcje są po prostu metodami publicznymi TodoItemsController w klasie. Platforma używa oprogramowania pośredniczącego routingu, aby dopasować adresy URL żądań przychodzących i mapować je na akcje. Interfejsy API REST powinny używać routingu atrybutów modelu funkcji 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 ASP.NET Core, zobacz Creating Backend Services for Native Mobile Applications (Tworzenie usług zaplecza dla natywnych aplikacji mobilnych).

Klasa służy do wysyłania HttpClient i odbierania żądań za pośrednictwem protokołu HTTP. Zapewnia ona funkcje wysyłania żądań HTTP i odbierania odpowiedzi HTTP z zidentyfikowanego zasobu identyfikatora URI. Każde żądanie jest wysyłane jako operacja asynchroniczna. Aby uzyskać więcej informacji na temat operacji asynchronicznych, zobacz Async Support Overview (Omówienie asynchronicznej pomocy technicznej).

Klasa HttpResponseMessage reprezentuje komunikat odpowiedzi HTTP odebrany z usługi internetowej po wykonaniu żądania HTTP. Zawiera on informacje o odpowiedzi, w tym kod stanu, nagłówki i dowolną treść. Klasa HttpContent reprezentuje treść HTTP i nagłówki zawartości, takie jak Content-Type i Content-Encoding. Zawartość może być odczytywana przy użyciu dowolnej z ReadAs metod, takich jak ReadAsStringAsync i ReadAsByteArrayAsync, w zależności od formatu danych.

Tworzenie obiektu HTTPClient

HttpClient Wystąpienie jest deklarowane na poziomie klasy, tak aby obiekt mieścił się tak długo, jak aplikacja musi wysyłać żądania HTTP, jak pokazano w poniższym przykładzie kodu:

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

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

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, jak pokazano w poniższym przykładzie kodu:

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

Usługa REST wysyła kod stanu HTTP we HttpResponseMessage.IsSuccessStatusCode właściwości, aby wskazać, czy żądanie HTTP powiodło się, 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 na potrzeby wyświetlania. Właściwość HttpResponseMessage.Content reprezentuje zawartość odpowiedzi HTTP, a HttpContent.ReadAsStringAsync metoda asynchronicznie zapisuje zawartość HTTP w ciągu. Ta zawartość jest następnie deserializacji z formatu JSON do ListTodoItem wystąpienia.

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, jak pokazano w poniższym przykładzie kodu:

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

Wystąpienie TodoItem 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 we HttpResponseMessage.IsSuccessStatusCode właściwości, aby wskazać, czy żądanie HTTP powiodło się, 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, jak pokazano w poniższym przykładzie kodu:

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 we HttpResponseMessage.IsSuccessStatusCode właściwości, aby wskazać, czy żądanie HTTP powiodło się, 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, jak pokazano w poniższym przykładzie kodu:

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

Usługa REST wysyła kod stanu HTTP we HttpResponseMessage.IsSuccessStatusCode właściwości, aby wskazać, czy żądanie HTTP powiodło się, 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ę mobilną. W tym scenariuszu należy włączyć ruch HTTP w postaci zwykłego tekstu dla symulatora systemu iOS i emulatora systemu Android. Aby uzyskać informacje o konfiguracji projektu umożliwiającej komunikację, zobacz Połączenie do lokalnych usług internetowych.

Pokrewne łącza

• Tworzenie internetowego interfejsu API przy użyciu platformy ASP.NET Core
• Tworzenie usług zaplecza dla natywnych aplikacji mobilnych
• Routing atrybutów dla interfejsów API REST
• TodoREST (przykład)
• HttpClient API
• Konfiguracja zabezpieczeń sieci systemu Android
• iOS App Transport Security
• Połączenie do lokalnych usług internetowych