Verwenden eines RESTful-Webdiensts

  • Artikel

Das Integrieren eines Webdiensts in eine Anwendung ist ein gängiges Szenario. In diesem Artikel wird veranschaulicht, wie Ein RESTful-Webdienst aus einer Xamarin.Forms Anwendung verwendet wird.

Representational State Transfer (REST) ist ein Architekturstil zum Erstellen von Webdiensten. REST-Anforderungen werden über HTTP mit den gleichen HTTP-Verben ausgeführt, die Webbrowser verwenden, um Webseiten abzurufen und Daten an Server zu senden. Es gibt folgende Verben:

  • GET: Dieser Vorgang wird verwendet, um Daten aus dem Webdienst abzurufen.
  • POST: Dieser Vorgang wird verwendet, um ein neues Datenelement im Webdienst zu erstellen.
  • PUT: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu aktualisieren.
  • PATCH: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu aktualisieren, indem eine Reihe von Anweisungen zur Änderung des Elements beschrieben wird. Dieses Verb wird in der Beispielanwendung nicht verwendet.
  • DELETE: Dieser Vorgang wird verwendet, um ein Datenelement im Webdienst zu löschen.

Webdienst-APIs, die dem REST-Standard entsprechen, werden als RESTful-APIs bezeichnet und wie folgt definiert:

  • Ein Basis-URI.
  • HTTP-Methoden wie GET, POST, PUT, PATCH oder DELETE.
  • Ein Medientyp für die Daten, wie etwa JavaScript Object Notation (JSON) oder XML.

RESTful-Webdienste verwenden in der Regel JSON-Nachrichten, um Daten an den Client zurückzugeben. JSON ist ein textbasiertes Datenaustauschformat, das kompakte Nutzlasten erzeugt, was zu geringeren Bandbreitenanforderungen beim Senden von Daten führt. Die Beispielanwendung verwendet die Open Source NewtonSoft JSON.NET-Bibliothek zum Serialisieren und Deserialisieren von Nachrichten.

Die Einfachheit von REST hat dazu beigetragen, dass sie die primäre Methode für den Zugriff auf Webdienste in mobilen Anwendungen ist.

Wenn die Beispielanwendung ausgeführt wird, stellt sie eine Verbindung mit einem lokal gehosteten REST-Dienst her, wie im folgenden Screenshot gezeigt:

Beispielanwendung

Hinweis

In iOS 9 und höher erzwingt App Transport Security (ATS) sichere Verbindungen zwischen Internetressourcen (z. B. dem Back-End-Server der App) und der App, wodurch die versehentliche Offenlegung vertraulicher Informationen verhindert wird. Da ATS standardmäßig in Apps aktiviert ist, die für iOS 9 erstellt wurden, unterliegen alle Verbindungen den ATS-Sicherheitsanforderungen. Wenn Verbindungen diese Anforderungen nicht erfüllen, tritt ein Ausnahmefehler auf.

ATS kann deaktiviert werden, wenn es nicht möglich ist, das HTTPS-Protokoll und die sichere Kommunikation für Internetressourcen zu verwenden. Dies kann durch Aktualisieren der Info.plist-Datei der App erreicht werden. Weitere Informationen finden Sie unter App Transport Security.

Nutzen des Webdiensts

Der REST-Dienst wird mit ASP.NET Core geschrieben und stellt die folgenden Vorgänge bereit:

Vorgang HTTP-Methode Relative URL Parameter
Abrufen einer Liste von To-Do-Elementen GET /api/todoitems/
Erstellen eines neuen Aufgabenelements NACHRICHT /api/todoitems/ Ein JSON-formatiertes todoItem-Objekt
Aktualisieren eines To-Do-Elements PUT /api/todoitems/ Ein JSON-formatiertes todoItem-Objekt
Löschen eines To-Do-Elements DELETE /api/todoitems/{id}

Der Großteil der URIs enthält die TodoItem ID im Pfad. Um beispielsweise die TodoItem ID 6bb8a868-dba1-4f1a-93b7-24ebce87e243zu löschen, sendet der Client eine DELETE-Anforderung an http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243. Weitere Informationen zum in der Beispielanwendung verwendeten Datenmodell finden Sie unter Modellieren der Daten.

Wenn das Web-API-Framework eine Anforderung empfängt, leitet es die Anforderung an eine Aktion weiter. Diese Aktionen sind einfach öffentliche Methoden in der TodoItemsController Klasse. Das Framework verwendet Routing-Middleware, um die URLs eingehender Anforderungen abzugleichen und aktionen zuzuordnen. REST-APIs sollten das Attributrouting des Modells der App als Eine Reihe von Ressourcen verwenden, deren Vorgänge durch HTTP-Verben dargestellt werden. Beim Attributrouting werden Aktionen mithilfe von Attributen direkt Routenvorlagen zugeordnet. Weitere Informationen zum Attribut-Routing finden Sie unter Attribut-Routing für REST-APIs. Weitere Informationen zum Erstellen des REST-Diensts mit ASP.NET Core finden Sie unter Creating Back-End Services for Native Mobile Applications.

Die HttpClient Klasse wird zum Senden und Empfangen von Anforderungen über HTTP verwendet. Es bietet Funktionen zum Senden von HTTP-Anforderungen und empfangen von HTTP-Antworten von einer identifizierten URI-Ressource. Jede Anfrage wird als asynchroner Vorgang gesendet. Weitere Informationen zu asynchronen Vorgängen finden Sie unter Async Support Overview.

Die HttpResponseMessage Klasse stellt eine HTTP-Antwortnachricht dar, die vom Webdienst empfangen wurde, nachdem eine HTTP-Anforderung gestellt wurde. Sie enthält Informationen zur Antwort, einschließlich Statuscode, Headern und beliebigem Text. Die HttpContent-Klasse steht für den HTTP-Textkörper und die Inhaltsheader, wie etwa Content-Type und Content-Encoding. Der Inhalt kann mithilfe einer der ReadAs Methoden gelesen werden, z ReadAsStringAsync . B. und ReadAsByteArrayAsyncabhängig vom Format der Daten.

Erstellen des HTTPClient-Objekts

Die HttpClient Instanz wird auf Klassenebene deklariert, sodass das Objekt so lange lebt, wie im folgenden Codebeispiel gezeigt, dass die Anwendung HTTP-Anforderungen stellen muss:

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

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

Abrufen von Daten

Die HttpClient.GetAsync Methode wird verwendet, um die GET-Anforderung an den vom URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen, wie im folgenden Codebeispiel gezeigt:

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

Der REST-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Bei diesem Vorgang sendet der REST-Dienst in der Antwort den HTTP-Statuscode 200 (OK), der anzeigt, dass die Anforderung erfolgreich war und die angeforderten Informationen in der Antwort enthalten sind.

Wenn der HTTP-Vorgang erfolgreich war, wird der Inhalt der Antwort zur Anzeige gelesen. Die HttpResponseMessage.Content Eigenschaft stellt den Inhalt der HTTP-Antwort dar, und die HttpContent.ReadAsStringAsync Methode schreibt den HTTP-Inhalt asynchron in eine Zeichenfolge. Dieser Inhalt wird dann von JSON in eine List Instanz TodoItem deserialisiert.

Warnung

Die Verwendung der ReadAsStringAsync-Methode zum Abruf einer umfangreichen Antwort kann negative Auswirkungen auf die Leistung haben. In solchen Fällen sollte die Antwort direkt deserialisiert werden, damit sie nicht vollständig gepuffert werden muss.

Daten erstellen

Die HttpClient.PostAsync Methode wird verwendet, um die POST-Anforderung an den vom URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen, wie im folgenden Codebeispiel gezeigt:

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

Die TodoItem Instanz wird in eine JSON-Nutzlast serialisiert, um an den Webdienst zu senden. Diese Nutzlast wird dann in den Textkörper des HTTP-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anfrage mit der PostAsync-Methode gestellt wird.

Der REST-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die allgemeinen Antworten für diesen Vorgang sind:

  • 201 (CREATED): Die Anforderung führte dazu, dass eine neue Ressource erstellt wurde, bevor die Antwort gesendet wurde.
  • 400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
  • 409 (CONFLICT): Die Anforderung konnte aufgrund eines Konflikts auf dem Server nicht ausgeführt werden.

Daten aktualisieren

Die HttpClient.PutAsync Methode wird verwendet, um die PUT-Anforderung an den vom URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen, wie im folgenden Codebeispiel gezeigt:

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

Die Funktionsweise der PutAsync-Methode ist identisch mit der PostAsync-Methode, die für die Erstellung von Daten im Webdienst verwendet wird. Die möglichen Antworten, die vom Webdienst gesendet werden, unterscheiden sich jedoch.

Der REST-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die allgemeinen Antworten für diesen Vorgang sind:

  • 204 (NO CONTENT): Die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.
  • 400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
  • 404 (NOT FOUND): Die angeforderte Ressource ist auf dem Server nicht vorhanden.

Löschen von Daten

Die HttpClient.DeleteAsync Methode wird verwendet, um die DELETE-Anforderung an den vom URI angegebenen Webdienst zu senden und dann die Antwort vom Webdienst zu empfangen, wie im folgenden Codebeispiel gezeigt:

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

Der REST-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die allgemeinen Antworten für diesen Vorgang sind:

  • 204 (NO CONTENT): Die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.
  • 400 (BAD REQUEST): Die Anforderung wird vom Server nicht verstanden.
  • 404 (NOT FOUND): Die angeforderte Ressource ist auf dem Server nicht vorhanden.

Lokale Entwicklung

Wenn Sie Ihren REST-Webdienst lokal mit einem Framework wie ASP.NET Core Web API entwickeln, können Sie Ihren Webdienst und Ihre mobile App gleichzeitig debuggen. In diesem Szenario müssen Sie den HTTP-Klartextdatenverkehr für den iOS-Simulator und den Android-Emulator aktivieren. Informationen zur Konfiguration Ihres Projekts, um die Kommunikation zu ermöglichen, finden Sie unter Verbinden zu lokalen Webdiensten.