Verwenden eines RESTful-Webdiensts

Laden Sie das Beispiel herunter. Herunterladen des Beispiels

Die Integration eines Webdiensts in eine Anwendung ist ein gängiges Szenario. In diesem Artikel wird veranschaulicht, wie Sie einen RESTful-Webdienst aus einer Anwendung Xamarin.Forms 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ück zu geben. 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-Bibliothek NewtonSoft JSON.NET, um Nachrichten zu serialisieren und zu deserialisieren.

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, 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 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, wird eine Ausnahme ausgelöst.

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

Nutzen des Webdiensts

Der REST-Dienst wird mithilfe ASP.NET Core und stellt die folgenden Vorgänge zur Verfügung:

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 Im JSON-Format formatiertes TodoItem
Aktualisieren eines To-Do-Elements PUT /api/todoitems/ Ein Im JSON-Format formatiertes TodoItem
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 zu löschen, deren ID ist, sendet der Client TodoItem 6bb8a868-dba1-4f1a-93b7-24ebce87e243 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 zu finden und sie Aktionen zu zuordnen. REST-APIs sollten das Attributrouting des Modells der App-Funktionalität als eine 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 mit 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. Sie bietet Funktionen zum Senden von HTTP-Anforderungen und Empfangen von HTTP-Antworten von einer identifizierten URI-Ressource. Jede Anforderung wird als asynchroner Vorgang gesendet. Weitere Informationen zu asynchronen Vorgängen finden Sie unter Übersicht über die asynchrone Unterstützung.

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

Erstellen des HTTPClient-Objekts

Die -Instanz wird auf Klassenebene deklariert, sodass das Objekt so lange verwendet wird, wie die Anwendung HTTP-Anforderungen ausführen muss, wie im folgenden HttpClient Codebeispiel gezeigt:

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

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

Abrufen von Daten

Die -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 HttpClient.GetAsync 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 -Eigenschaft, um anzugeben, ob die HttpResponseMessage.IsSuccessStatusCode HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist. Für diesen Vorgang sendet der REST-Dienst den HTTP-Statuscode 200 (OK) in der Antwort, der angibt, 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 -Methode schreibt den HTTP-Inhalt asynchron HttpContent.ReadAsStringAsync in eine Zeichenfolge. Dieser Inhalt wird dann von JSON in eine von List TodoItem -Instanzen deserialisiert.

Warnung

Die Verwendung ReadAsStringAsync der -Methode zum Abrufen einer großen Antwort kann negative Auswirkungen auf die Leistung haben. In solchen Fällen sollte die Antwort direkt deserialisiert werden, um zu vermeiden, dass sie vollständig gepuffert werden muss.

Erstellen von Daten

Die -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 HttpClient.PostAsync 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 sie an den Webdienst zu senden. Diese Nutzlast wird dann in den Text des HTTP-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anforderung mit der -Methode gesendet PostAsync wird.

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

  • 201 (CREATED): Die Anforderung führte dazu, dass vor dem Senden der Antwort eine neue Ressource erstellt 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 -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 HttpClient.PutAsync 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 -Methode, die zum Erstellen PostAsync 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 -Eigenschaft, um anzugeben, ob die HttpResponseMessage.IsSuccessStatusCode HTTP-Anforderung erfolgreich war 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.

Löschen von Daten

Die -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 HttpClient.DeleteAsync 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 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-Simualtor und den Android-Emulator aktivieren. Informationen zur Konfiguration Ihres Projekts für die Kommunikation finden Sie unter Verbinden mit lokalen Webdiensten.