Nutzen eines Rest-WebdienstsConsume a RESTful Web Service

Beispiel herunterladen Das Beispiel herunterladenDownload Sample Download the sample

Das Integrieren eines Webdiensts in eine Anwendung ist ein gängiges Szenario. In diesem Artikel wird veranschaulicht, wie Sie einen Rest-Webdienst aus einer xamarin. Forms-Anwendung nutzen.Integrating a web service into an application is a common scenario. This article demonstrates how to consume a RESTful web service from a Xamarin.Forms application.

Der Representational State Transfer (Rest) ist ein Architekturstil zum Entwickeln von Webdiensten.Representational State Transfer (REST) is an architectural style for building web services. Rest-Anforderungen werden über HTTP mit denselben HTTP-Verben hergestellt, die Webbrowser zum Abrufen von Webseiten und zum Senden von Daten an Server verwenden.REST requests are made over HTTP using the same HTTP verbs that web browsers use to retrieve web pages and to send data to servers. Die Verben sind:The verbs are:

  • Get – dieser Vorgang wird verwendet, um Daten aus dem Webdienst abzurufen.GET – this operation is used to retrieve data from the web service.
  • Post – dieser Vorgang wird verwendet, um ein neues Datenelement für den Webdienst zu erstellen.POST – this operation is used to create a new item of data on the web service.
  • Put – dieser Vorgang wird verwendet, um ein Datenelement für den Webdienst zu aktualisieren.PUT – this operation is used to update an item of data on the web service.
  • Patch – dieser Vorgang wird verwendet, um ein Element der Daten im Webdienst zu aktualisieren, indem eine Reihe von Anweisungen zum Ändern des Elements beschrieben werden.PATCH – this operation is used to update an item of data on the web service by describing a set of instructions about how the item should be modified. Dieses Verb wird in der Beispielanwendung nicht verwendet.This verb is not used in the sample application.
  • Delete – dieser Vorgang wird verwendet, um ein Datenelement für den Webdienst zu löschen.DELETE – this operation is used to delete an item of data on the web service.

Webdienst-APIs, die Rest einhalten, werden als Rest-APIs bezeichnet und mithilfe von definiert:Web service APIs that adhere to REST are called RESTful APIs, and are defined using:

  • Ein Basis-URI.A base URI.
  • HTTP-Methoden wie Get, Post, Put, Patch oder DELETE.HTTP methods, such as GET, POST, PUT, PATCH, or DELETE.
  • Ein Medientyp für die Daten, z. b. JavaScript Object Notation (JSON).A media type for the data, such as JavaScript Object Notation (JSON).

Rest-Webdienste verwenden normalerweise JSON-Nachrichten, um Daten an den Client zurückzugeben.RESTful web services typically use JSON messages to return data to the client. JSON ist ein textbasiertes Datenaustauschformat, das kompakte Nutzlasten erzeugt, was zu geringeren Bandbreitenanforderungen beim Senden von Daten führt.JSON is a text-based data-interchange format that produces compact payloads, which results in reduced bandwidth requirements when sending data. Die Beispielanwendung verwendet die Open Source- Bibliothek "newtonsoft JSON.net ", um Nachrichten zu serialisieren und zu deserialisieren.The sample application uses the open source NewtonSoft JSON.NET library to serialize and deserialize messages.

Die Einfachheit von Rest hat dazu beigetragen, dass Sie die primäre Methode für den Zugriff auf Webdienste in mobilen Anwendungen ist.The simplicity of REST has helped make it the primary method for accessing web services in mobile applications.

Wenn die Beispielanwendung ausgeführt wird, wird eine Verbindung mit einem lokal gehosteten Rest-Dienst hergestellt, wie im folgenden Screenshot zu sehen:When the sample application is run, it will connect to a locally hosted REST service, as shown in the following screenshot:

Hinweis

In ios 9 und höher erzwingt App-Transport Sicherheit (app Transport Security, ATS) sichere Verbindungen zwischen Internetressourcen (z. b. dem Back-End-Server der APP) und der APP, wodurch eine versehentliche Offenlegung vertraulicher Informationen verhindert wird.In iOS 9 and greater, App Transport Security (ATS) enforces secure connections between internet resources (such as the app's back-end server) and the app, thereby preventing accidental disclosure of sensitive information. Da ATS in apps, die für IOS 9 erstellt wurden, standardmäßig aktiviert ist, unterliegen alle Verbindungen den Sicherheitsanforderungen.Since ATS is enabled by default in apps built for iOS 9, all connections will be subject to ATS security requirements. Wenn Verbindungen diese Anforderungen nicht erfüllen, können Sie mit einer Ausnahme fehlschlagen.If connections do not meet these requirements, they will fail with an exception.

Es kann deaktiviert werden, wenn es nicht möglich ist, das https -Protokoll und die sichere Kommunikation für Internetressourcen zu verwenden.ATS can be opted out of if it is not possible to use the HTTPS protocol and secure communication for internet resources. Dies kann durch Aktualisieren der Datei " Info. plist " der APP erreicht werden.This can be achieved by updating the app's Info.plist file. Weitere Informationen finden Sie unter App-Transport Sicherheit.For more information see App Transport Security.

Verwenden des WebdienstsConsuming the Web Service

Der Rest-Dienst wird mit ASP.net Core geschrieben und bietet die folgenden Vorgänge:The REST service is written using ASP.NET Core and provides the following operations:

VorgangOperation HTTP-MethodeHTTP method Relativer URIRelative URI ParameterParameters
Abrufen einer Liste von To-Do-ElementenGet a list of to-do items GETGET /api/todoitems//api/todoitems/
Neues to-do-Element erstellenCreate a new to-do item BereitstellenPOST /api/todoitems//api/todoitems/ Ein JSON-formatiertes "$ doitem"A JSON formatted TodoItem
Aktualisieren eines To-Do-ElementsUpdate a to-do item StelltePUT /api/todoitems//api/todoitems/ Ein JSON-formatiertes "$ doitem"A JSON formatted TodoItem
Löschen eines To-Do-ElementsDelete a to-do item DELETEDELETE /api/todoitems/{id}/api/todoitems/{id}

Die meisten URIs enthalten die TodoItem-ID im Pfad.The majority of the URIs include the TodoItem ID in the path. Um z. b. den TodoItem, dessen ID 6bb8a868-dba1-4f1a-93b7-24ebce87e243ist, zu löschen, sendet der Client eine DELETE-Anforderung an http://hostname/api/todoitems/6bb8a868-dba1-4f1a-93b7-24ebce87e243.For example, to delete the TodoItem whose ID is 6bb8a868-dba1-4f1a-93b7-24ebce87e243, the client sends a DELETE request to 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.For more information about the data model used in the sample application, see Modeling the data.

Wenn das Web-API-Framework eine Anforderung empfängt, leitet es die Anforderung an eine Aktion weiter.When the Web API framework receives a request it routes the request to an action. Diese Aktionen sind einfach öffentliche Methoden in der TodoItemsController-Klasse.These actions are simply public methods in the TodoItemsController class. Das Framework verwendet eine Routing Tabelle, um zu bestimmen, welche Aktion als Reaktion auf eine Anforderung aufgerufen werden soll. Dies wird im folgenden Codebeispiel gezeigt:The framework uses a routing table to determine which action to invoke in response to a request, which is shown in the following code example:

config.Routes.MapHttpRoute(
    name: "TodoItemsApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { controller="todoitems", id = RouteParameter.Optional }
);

Die Routing Tabelle enthält eine Routen Vorlage, und wenn das Web-API-Framework eine HTTP-Anforderung empfängt, versucht es, den URI mit der Routen Vorlage in der Routing Tabelle abzugleichen.The routing table contains a route template, and when the Web API framework receives an HTTP request, it tries to match the URI against the route template in the routing table. Wenn keine übereinstimmende Route gefunden wird, empfängt der Client den Fehler 404 (nicht gefunden).If a matching route cannot be found the client receives a 404 (not found) error. Wenn eine übereinstimmende Route gefunden wird, wählt die Web-API den Controller und die Aktion wie folgt aus:If a matching route is found, Web API selects the controller and the action as follows:

  • Um den Controller zu finden, fügt die Web-API "controller" dem Wert der {Controller} -Variablen hinzu.To find the controller, Web API adds "controller" to the value of the {controller} variable.
  • Um die Aktion zu finden, untersucht die Web-API die HTTP-Methode und überprüft Controller Aktionen, die mit derselben HTTP-Methode wie ein Attribut ergänzt werden.To find the action, Web API looks at the HTTP method and looks at controller actions that are decorated with the same HTTP method as an attribute.
  • Die Platzhalter Variable {ID} ist einem Aktionsparameter zugeordnet.The {id} placeholder variable is mapped to an action parameter.

Der Rest-Dienst verwendet die Standard Authentifizierung.The REST service uses basic authentication. Weitere Informationen finden Sie unter Authentifizieren eines Rest-Webdiensts.For more information see Authenticating a RESTful web service. Weitere Informationen zum ASP.net-Web-API Routing finden Sie unter Routing in ASP.net-Web-API auf der ASP.NET-Website.For more information about ASP.NET Web API routing, see Routing in ASP.NET Web API on the ASP.NET website. Weitere Informationen zum Erstellen des Rest-Diensts mit ASP.net Core finden Sie unter Erstellen von Back-End- Diensten für Native Mobile Anwendungen.For more information about building the REST service using ASP.NET Core, see Creating Backend Services for Native Mobile Applications.

Die HttpClient-Klasse wird verwendet, um Anforderungen über HTTP zu senden und zu empfangen.The HttpClient class is used to send and receive requests over HTTP. Es stellt Funktionen zum Senden von HTTP-Anforderungen und empfangen von HTTP-Antworten aus einer vom URI identifizierten Ressource bereit.It provides functionality for sending HTTP requests and receiving HTTP responses from a URI identified resource. Jede Anforderung wird als asynchroner Vorgang gesendet.Each request is sent as an asynchronous operation. Weitere Informationen zu asynchronen Vorgängen finden Sie unter async-Unterstützung: Übersicht.For more information about asynchronous operations, see Async Support Overview.

Die HttpResponseMessage-Klasse stellt eine HTTP-Antwortnachricht dar, die vom Webdienst empfangen wurde, nachdem eine HTTP-Anforderung durchgeführt wurde.The HttpResponseMessage class represents an HTTP response message received from the web service after an HTTP request has been made. Sie enthält Informationen über die Antwort, einschließlich Statuscode, Header und beliebiger Text.It contains information about the response, including the status code, headers, and any body. Die HttpContent-Klasse stellt den HTTP-Textkörper und Inhalts Header dar, z. b. Content-Type und Content-Encoding.The HttpContent class represents the HTTP body and content headers, such as Content-Type and Content-Encoding. Der Inhalt kann je nach Format der Daten mit allen ReadAs Methoden wie ReadAsStringAsync und ReadAsByteArrayAsyncgelesen werden.The content can be read using any of the ReadAs methods, such as ReadAsStringAsync and ReadAsByteArrayAsync, depending upon the format of the data.

Erstellen des httpclient-ObjektsCreating the HTTPClient Object

Die HttpClient Instanz wird auf Klassenebene deklariert, damit das Objekt so lange wie die Anwendung HTTP-Anforderungen ausführen muss, wie im folgenden Codebeispiel gezeigt:The HttpClient instance is declared at the class-level so that the object lives for as long as the application needs to make HTTP requests, as shown in the following code example:

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

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

Abrufen von DatenRetrieving Data

Die HttpClient.GetAsync-Methode wird verwendet, um die Get-Anforderung an den Webdienst zu senden, der durch den URI angegeben wird. Anschließend wird die Antwort vom Webdienst empfangen, wie im folgenden Codebeispiel gezeigt:The HttpClient.GetAsync method is used to send the GET request to the web service specified by the URI, and then receive the response from the web service, as shown in the following code example:

public async Task<List<TodoItem>> RefreshDataAsync ()
{
  ...
  var uri = new Uri (string.Format (Constants.TodoItemsUrl, string.Empty));
  ...
  var response = await _client.GetAsync (uri);
  if (response.IsSuccessStatusCode)
  {
      var content = await response.Content.ReadAsStringAsync ();
      Items = JsonConvert.DeserializeObject <List<TodoItem>> (content);
  }
  ...
}

Der Rest-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode-Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist.The REST service sends an HTTP status code in the HttpResponseMessage.IsSuccessStatusCode property, to indicate whether the HTTP request succeeded or failed. 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 angezeigt werden.For this operation the REST service sends HTTP status code 200 (OK) in the response, which indicates that the request succeeded and that the requested information is in the response.

Wenn der http-Vorgang erfolgreich war, wird der Inhalt der Antwort für die Anzeige gelesen.If the HTTP operation was successful, the content of the response is read, for display. Die HttpResponseMessage.Content-Eigenschaft stellt den Inhalt der HTTP-Antwort dar, und die HttpContent.ReadAsStringAsync-Methode schreibt den HTTP-Inhalt asynchron in eine Zeichenfolge.The HttpResponseMessage.Content property represents the content of the HTTP response, and the HttpContent.ReadAsStringAsync method asynchronously writes the HTTP content to a string. Dieser Inhalt wird dann von JSON in eine List TodoItem Instanzen konvertiert.This content is then converted from JSON to a List of TodoItem instances.

Erstellen von DatenCreating Data

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:The HttpClient.PostAsync method is used to send the POST request to the web service specified by the URI, and then to receive the response from the web service, as shown in the following code example:

public async Task SaveTodoItemAsync (TodoItem item, bool isNewItem = false)
{
  var uri = new Uri (string.Format (Constants.TodoItemsUrl, string.Empty));

  ...
  var json = JsonConvert.SerializeObject (item);
  var 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 konvertiert, um Sie an den Webdienst zu senden.The TodoItem instance is converted to a JSON payload for sending to the web service. Diese Nutzlast wird dann in den Text des http-Inhalts eingebettet, der an den Webdienst gesendet wird, bevor die Anforderung mit der PostAsync-Methode erfolgt.This payload is then embedded in the body of the HTTP content that will be sent to the web service before the request is made with the PostAsync method.

Der Rest-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode-Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist.The REST service sends an HTTP status code in the HttpResponseMessage.IsSuccessStatusCode property, to indicate whether the HTTP request succeeded or failed. Die häufigsten Antworten für diesen Vorgang lauten:The common responses for this operation are:

  • 201 (erstellt) – die Anforderung hat dazu geführt, dass eine neue Ressource erstellt wurde, bevor die Antwort gesendet wurde.201 (CREATED) – the request resulted in a new resource being created before the response was sent.
  • 400 (ungültige Anforderung) – die Anforderung wird vom Server nicht verstanden.400 (BAD REQUEST) – the request is not understood by the server.
  • 409 (Konflikt) – die Anforderung konnte aufgrund eines Konflikts auf dem Server nicht ausgeführt werden.409 (CONFLICT) – the request could not be carried out because of a conflict on the server.

Aktualisieren von DatenUpdating Data

Die HttpClient.PutAsync-Methode wird verwendet, um die PUT-Anforderung an den Webdienst zu senden, der durch den URI angegeben wird. Anschließend wird die Antwort vom Webdienst empfangen, wie im folgenden Codebeispiel gezeigt:The HttpClient.PutAsync method is used to send the PUT request to the web service specified by the URI, and then receive the response from the web service, as shown in the following code example:

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.The operation of the PutAsync method is identical to the PostAsync method that's used for creating data in the web service. Die möglichen Antworten, die vom Webdienst gesendet werden, unterscheiden sich jedoch.However, the possible responses sent from the web service differ.

Der Rest-Dienst sendet einen HTTP-Statuscode in der HttpResponseMessage.IsSuccessStatusCode-Eigenschaft, um anzugeben, ob die HTTP-Anforderung erfolgreich war oder fehlgeschlagen ist.The REST service sends an HTTP status code in the HttpResponseMessage.IsSuccessStatusCode property, to indicate whether the HTTP request succeeded or failed. Die häufigsten Antworten für diesen Vorgang lauten:The common responses for this operation are:

  • 204 (kein Inhalt) – die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.204 (NO CONTENT) – the request has been successfully processed and the response is intentionally blank.
  • 400 (ungültige Anforderung) – die Anforderung wird vom Server nicht verstanden.400 (BAD REQUEST) – the request is not understood by the server.
  • 404 (nicht gefunden) – die angeforderte Ressource ist auf dem Server nicht vorhanden.404 (NOT FOUND) – the requested resource does not exist on the server.

Löschen von DatenDeleting Data

Die HttpClient.DeleteAsync-Methode wird verwendet, um die DELETE-Anforderung an den Webdienst zu senden, der durch den URI angegeben wird. Anschließend wird die Antwort vom Webdienst empfangen, wie im folgenden Codebeispiel gezeigt:The HttpClient.DeleteAsync method is used to send the DELETE request to the web service specified by the URI, and then receive the response from the web service, as shown in the following code example:

public async Task DeleteTodoItemAsync (string id)
{
  var uri = new Uri (string.Format (Constants.TodoItemsUrl, id));
  ...
  var 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.The REST service sends an HTTP status code in the HttpResponseMessage.IsSuccessStatusCode property, to indicate whether the HTTP request succeeded or failed. Die häufigsten Antworten für diesen Vorgang lauten:The common responses for this operation are:

  • 204 (kein Inhalt) – die Anforderung wurde erfolgreich verarbeitet, und die Antwort ist absichtlich leer.204 (NO CONTENT) – the request has been successfully processed and the response is intentionally blank.
  • 400 (ungültige Anforderung) – die Anforderung wird vom Server nicht verstanden.400 (BAD REQUEST) – the request is not understood by the server.
  • 404 (nicht gefunden) – die angeforderte Ressource ist auf dem Server nicht vorhanden.404 (NOT FOUND) – the requested resource does not exist on the server.