Verwenden eines RESTful-Webdiensts

Beispiel herunterladen Laden Sie das Beispiel herunter

Die Integration eines Webdiensts in eine Anwendung ist ein gängiges Szenario. In diesem Artikel wird veranschaulicht, wie Sie einen RESTful-Webdienst aus einer Xamarin.Forms Anwendung verwenden.

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, z. B. JavaScript-Objektnotation (JSON).

RESTful-Webdienste verwenden normalerweise JSON-Nachrichten, um Daten an den Client zurückzugeben. JSON ist ein textbasiertes Datenaustauschformat, das kompakte Nutzlasten erzeugt, was zu reduzierten 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 es die primäre Methode für den Zugriff auf Webdienste in mobilen Anwendungen ist.

Wenn die Beispielanwendung ausgeführt wird, wird eine Verbindung mit einem lokal gehosteten REST-Dienst hergestellt, 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, schlägt sie mit einer Ausnahme fehl.

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 mithilfe von ASP.NET Core geschrieben und stellt die folgenden Vorgänge bereit:

Vorgang HTTP-Methode Relativer URI Parameter
Abrufen einer Liste von To-Do-Elementen GET /api/todoitems/
Erstellen eines neuen Aufgabenelements POST /api/todoitems/ Ein JSON-formatiertes TodoItem
Aktualisieren eines To-Do-Elements PUT /api/todoitems/ Ein JSON-formatiertes TodoItem
Löschen eines To-Do-Elements Delete /api/todoitems/{id}

Die meisten URIs enthalten die TodoItem ID im Pfad. Um beispielsweise die TodoItem ID zu löschen, sendet der Client eine DELETE-Anforderung 6bb8a868-dba1-4f1a-93b7-24ebce87e243an http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243. Weitere Informationen zum datenmodell, das in der Beispielanwendung verwendet wird, finden Sie unter Modellieren der Daten.

Wenn das Web-API-Framework eine Anforderung empfängt, wird die Anforderung an eine Aktion weitergeleitet. Diese Aktionen sind einfach öffentliche Methoden in der TodoItemsController Klasse. Das Framework verwendet Routing-Middleware, um den URLs eingehender Anforderungen zu entsprechen und ihnen Aktionen zuzuordnen. REST-APIs sollten das Attributrouting des Modells als Gruppe von Ressourcen verwenden, deren Vorgänge durch HTTP-Verben dargestellt werden. Beim Attributrouting werden Aktionen mithilfe von Attributen direkt Routenvorlagen zugeordnet. Weitere Informationen zum Attributrouting finden Sie unter Attributrouting für REST-APIs. Weitere Informationen zum Erstellen des REST-Diensts mithilfe von ASP.NET Core finden Sie unter Erstellen von Back-End-Diensten für native mobile Anwendungen.

Die HttpClient Klasse wird verwendet, um Anforderungen über HTTP zu senden und zu empfangen. Es bietet Funktionen zum Senden von HTTP-Anforderungen und empfangen HTTP-Antworten aus einer identifizierten Ressource. Jede Anforderung wird als asynchroner Vorgang gesendet. Weitere Informationen zu asynchronen Vorgängen finden Sie unter Async Support Übersicht.

Die HttpResponseMessage Klasse stellt eine HTTP-Antwortnachricht dar, die vom Webdienst empfangen wurde, nachdem eine HTTP-Anforderung vorgenommen wurde. Es enthält Informationen über die Antwort, einschließlich des Statuscodes, Kopfzeilen und eines beliebigen Textkörpers. Die HttpContent Klasse stellt die HTTP-Text- und Inhaltsheader dar, z Content-Type . B. und Content-Encoding. Der Inhalt kann mithilfe einer der ReadAs Methoden wie ReadAsStringAsync z. B. und ReadAsByteArrayAsync, je nach Format der Daten gelesen werden.

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 vornehmen 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. Für diesen Vorgang sendet der REST-Dienst HTTP-Statuscode 200 (OK) in der Antwort, was angibt, dass die Anforderung erfolgreich war und dass die angeforderten Informationen in der Antwort enthalten sind.

Wenn der HTTP-Vorgang erfolgreich war, wird der Inhalt der Antwort gelesen, für die Anzeige. 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 zu einer List Instanz TodoItem deserialisiert.

Warnung

Mithilfe der ReadAsStringAsync Methode zum Abrufen einer großen Antwort kann eine negative Leistungswirkung auftreten. Unter solchen Umständen sollte die Antwort direkt deserialisiert werden, um zu vermeiden, dass sie vollständig gepuffert werden muss.

Erstellen von Daten

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 zum Senden an den Webdienst serialisiert. Diese Nutzlast wird dann im Textkörper des HTTP-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anforderung mit der PostAsync Methode vorgenommen 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 wird, 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 durchgeführt werden.

Aktualisieren von Daten

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

Der Vorgang der PutAsync Methode entspricht der Methode, die PostAsync zum Erstellen 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 (KEIN INHALT) – die Anforderung wurde erfolgreich verarbeitet und die Antwort ist absichtlich leer.
  • 400 (BAD REQUEST) – die Anforderung wird vom Server nicht verstanden.
  • 404 (NICHT GEFUNDEN) – 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 (KEIN INHALT) – die Anforderung wurde erfolgreich verarbeitet und die Antwort ist absichtlich leer.
  • 400 (BAD REQUEST) – die Anforderung wird vom Server nicht verstanden.
  • 404 (NICHT GEFUNDEN) – 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 die mobile App gleichzeitig debuggen. In diesem Szenario müssen Sie den HTTP-Datenverkehr für den iOS-Simulator und den Android-Emulator eindeutigen Text aktivieren. Informationen zur Konfiguration Ihres Projekts zum Zulassen der Kommunikation finden Sie unter Verbinden mit lokalen Webdiensten.