Verwenden eines RESTful-Webdiensts

  • Artikel

Beispiel herunterladen Das Beispiel herunterladen

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

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 Object Notation (JSON).

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, es zur primären Methode für den Zugriff auf Webdienste in mobilen Anwendungen zu machen.

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 und verhindert so die versehentliche Offenlegung vertraulicher Informationen. Da ATS in Apps, die für iOS 9 erstellt wurden, standardmäßig aktiviert ist, unterliegen alle Verbindungen den ATS-Sicherheitsanforderungen. Wenn Verbindungen diese Anforderungen nicht erfüllen, schlagen 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 Datei Info.plist 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 Relativer URI Parameter
Abrufen einer Liste von To-Do-Elementen GET /api/todoitems/
Erstellen eines neuen To-Do-Elements 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 zu löschen, deren ID lautet 6bb8a868-dba1-4f1a-93b7-24ebce87e243, sendet der Client eine DELETE-Anforderung an 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, leitet es die Anforderung an eine Aktion weiter. Diese Aktionen sind einfach öffentliche Methoden in der TodoItemsController -Klasse. Das Framework verwendet Routingmiddleware, um die URLs eingehender Anforderungen abzugleichen und aktionen zuzuordnen. REST-APIs sollten das Attributrouting des Modells für die Funktionalität der App als Satz 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 zum Empfangen von HTTP-Antworten von einer URI identifizierten Ressource. Jede Anforderung wird als asynchroner Vorgang gesendet. Weitere Informationen zu asynchronen Vorgängen finden Sie unter Übersicht über die Async-Unterstützung.

Die HttpResponseMessage -Klasse stellt eine HTTP-Antwortnachricht dar, die vom Webdienst empfangen wird, nachdem eine HTTP-Anforderung gestellt wurde. Sie enthält Informationen zur Antwort, einschließlich Statuscode, Headern und beliebigem Text. Die HttpContent -Klasse stellt den HTTP-Text und die Inhaltsheader dar, z Content-Type . B. und Content-Encoding. Der Inhalt kann mit einer beliebigen Methode ReadAs wie und ReadAsByteArrayAsyncgelesen werden, ReadAsStringAsync je nach Format der Daten.

Erstellen des HTTPClient-Objekts

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

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 durch den 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-status Code 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 status Code 200 (OK) in der Antwort, der 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 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 von TodoItem -Instanzen deserialisiert.

Warnung

Die Verwendung der ReadAsStringAsync -Methode zum Abrufen einer großen Antwort kann sich negativ auf die Leistung auswirken. In solchen Fällen sollte die Antwort direkt deserialisiert werden, um eine vollständige Pufferung zu vermeiden.

Erstellen von Daten

Die HttpClient.PostAsync -Methode wird verwendet, um die POST-Anforderung an den durch den 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 instance wird zum Senden an den Webdienst in eine JSON-Nutzlast serialisiert. Diese Nutzlast wird dann in den Text des HTTP-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anforderung mit der PostAsync -Methode gestellt wird.

Der REST-Dienst sendet einen HTTP-status Code in der HttpResponseMessage.IsSuccessStatusCode -Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die häufigsten 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.

Aktualisieren von Daten

Die HttpClient.PutAsync -Methode wird verwendet, um die PUT-Anforderung an den durch den 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 ist identisch mit der PostAsync Methode, die 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-status Code in der HttpResponseMessage.IsSuccessStatusCode -Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Die häufigsten 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-status Code in der HttpResponseMessage.IsSuccessStatusCode -Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich oder fehlgeschlagen ist. Die häufigsten 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 (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 ihre mobile App gleichzeitig debuggen. In diesem Szenario müssen Sie klartext-HTTP-Datenverkehr für den iOS-Simulator und den Android-Emulator aktivieren. Informationen zur Konfiguration Ihres Projekts zum Zulassen der Kommunikation finden Sie unter Herstellen einer Verbindung mit lokalen Webdiensten.