REST-Clientbibliothek

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu DataSnap-REST


Die Embarcadero-REST-Bibliothek ist ein Framework für den Zugriff auf REST-basierte Webdienste (REST ist die Abkürzung für "Representational State Transfer"). Die Bibliothek ist für alle von Delphi unterstützten Plattformen verfügbar.

In diesem Framework wird JSON als Darstellungsformat verwendet. XML wird nicht explizit unterstützt.


Begriffe

Begriff Definition

REST

REpresentational State Transfer – gemäß der Definition von Roy Fielding 2000 (EN)

Dienst

Ein REST-basierter Webdienst

Client

Eine Instanz der TRESTClient-Komponente

Anforderung

Eine Instanz der TRESTRequest-Komponente

Antwort

Eine Instanz der TRESTResponse-Komponente

Hauptkomponenten und -klassen

Das Konzept der REST-Komponenten wurde basierend auf drei Hauptkomponenten entwickelt: die Anforderung, der Client und die Antwort. Alle drei sind Teil des Workflows beim Abrufen von Daten von einem Dienst.

TRESTClient

REST.Client.TRESTClient ist die Komponente, die eine Anforderung an einen Dienst tatsächlich ausführt. TRESTClient verwaltet die HTTP-Verbindung zu einem Dienst, die HTTP-Header sowie die Proxy-Server und empfängt die Antwortdaten. Authentifikatoren (werden später beschrieben) können dem Client hinzugefügt werden, um eine zweckmäßige Authentifizierung einer Anforderung zu ermöglichen.

Eine der wichtigsten Eigenschaften eines Clients ist BaseURL. Der Basis-URL ist der Hauptendpunkt eines Dienstanbieters; er bleibt normalerweise für alle Anforderungen an diesen Anbieter konstant. Alle Anforderungen werden an diesen Endpunkt geleitet, daher ist der Basis-URL die "erste Hälfte" des gesamten Anforderungs-URL. Die "zweite Hälfte" ist die "Ressource", die von der Anforderungskomponente bereitgestellt wird. In der Dokumentation des Dienstanbieters sind normalerweise Informationen zur URL-Struktur enthalten.

TRESTClient ist so konzipiert, dass alle HTTP-bezogenen Exceptions so lange verborgen werden, wie die Exception durch HTTP-Standardcode dargestellt werden kann. Der Client löst nur "harte" Exceptions, Verbindungsfehler usw. aus. Das Framework arbeitet mit dem neueren TNetHTTPClient, der auf System-HTTP-Client-Sockets basiert. Dies ermöglicht es, die Fähigkeit des Betriebssystems zur automatischen Auflösung und zum Umgang mit SSL/TLS/HTTPS zu nutzen.

TRESTRequest

Die Anforderung (REST.Client.TRESTRequest) enthält alle Parameter und Einstellungen, die die eigentliche HTTP-Anforderung an den Dienst bilden. Wenn eine Verbindung zu einer Client-Komponente besteht, kann die Anforderung ausgeführt werden (sogar während des Entwurfs). Eine der wichtigste Eigenschaften einer Anforderung ist die "Ressource". Dieser Wert bildet die weiter oben erwähnte "zweite Hälfte" des gesamten Anforderungs-URL und legt die eigentliche Aktion fest, die für den Dienst ausgeführt wird. Die Anforderung legt auch die HTTP-Methoden ("get", "post", "put", "delete") fest, die für ihre Ausführung verwendet werden.

Eine Anforderung enthält typischerweise folgende Parameter:

Parameter

Die TRESTRequest-Komponente unterstützt mehrere verschiedene Parametertypen mit jeweils eigenen Verwendungsmustern.

Header-Parameter

Diese Parameter haben die Form "Schlüssel=Wert" und sind in den HTTP-Header der Anforderung integriert.

Post/Get-Parameter

Diese Parameter haben die Form Schlüssel=Wert, und deren Integration in die Anforderung hängt von der Anforderungsmethode ab.

  • Bei HTTP-Post-Anforderungen sind die Parameter im Rumpf der Anforderung integriert.
  • Bei HTTP-Get-Anforderungen sind die Parameter im URL als Teil des Abfrage-Strings integriert.
Hinweis: Vermeiden Sie bei diesen Parametern die geschweiften Klammern im Parameter [ResourceSuffix('item')].

Rumpf-Parameter

Diese Parameter bestehen nur aus einem Wert, und sie sind im Rumpf der Anforderung enthalten. Sie können nicht für HTTP-Get- oder HTTP-Delete-Anforderungen verwendet werden, da sie über keinen Rumpf verfügen.

URL-Segment-Parameter

URL-Segment-Parameter sind positionsabhängig und in jedem URL-Segment vorhanden. Zum Beispiel: 

 http://www.example.com/first-segment/second-segment/index.html?

Diese Parameter können auf Basis des für BaseURL und Request eingegebenen Wertes automatisch erstellt werden. Mit der Eigenschaft AutoCreateParams können Sie dieses Verhalten steuern.

Hinweis: Der Wert des Parameters hängt von seiner Art ab, die ein bestimmtes Flag ist.

Cookie-Parameter

Diese Parameter haben die Form Schlüssel=Wert und werden als Cookie-Werte gesendet.

Alle Parameter werden automatisch verschlüsselt, damit sie standardmäßig den Bedingungen einer gültigen HTTP-Anforderung entsprechen. Es gibt eventuell Szenarien, in denen der Wert des Parameters bereits verschlüsselt ist und nicht erneut verschlüsselt werden muss. Setzen Sie in diesem Fall in den Optionen des Parameters das Flag "poDoNotEncode". Dadurch wird die Anforderung veranlasst, den Parameterwert unverändert zu übernehmen.

REST.Client.TRESTResponse

Die Antwort enthält alle vom Dienst zurückgegebenen Daten. Die Daten umfassen den HTTP-Statuscode, Fehlermeldungen (falls vorhanden) und natürlich die zurückgegebenen JSON-Daten. Ein Antwortobjekt kann ad hoc vom Client bei der Ausführung der Anforderung erstellt werden, oder das Antwortobjekt kann im Voraus erstellt und dann vor Ausführung einer Anforderung mit einem Client verbunden werden.

Auf die Antwortdaten kann mit den Eigenschaften "Content", "JSONValue" oder "RAWbytes" zugegriffen werden.

Authentifizierung

Für die meisten Dienste ist erst eine Authentifizierung erforderlich, bevor sie verwendet werden können. Mithilfe der Authentifikatorklassen werden bestimmte Authentifizierungsmethoden angewendet, die für den REST-Dienst erforderlich sind. Ein Authentifikator wird dem Client hinzugefügt und automatisch für jede ausgeführte Anforderung ausgeführt. Nach der Konfiguration kann die Eigenschaft für so viele Anforderungen wie benötigt verwendet werden, ohne dass sie nochmals geändert werden müssten. Normalerweise arbeitet der Authentifikator als Dekorator für die Anforderung, indem der Anforderung Header oder andere Parameter hinzugefügt werden. Aufgrund der Vielzahl der vorhandenen Authentifizierungsmethoden würde die Bereitstellung nur eines Authentifikators nicht ausreichen. Stattdessen wurde ein flexibles Framework entwickelt, das die Authentifizierung für viele verschiedene Methoden ermöglicht.

Einige Standard-Authentifikatoren sind im Komponentensatz enthalten, und benutzerdefinierte Authentifikatoren können einfach integriert werden (siehe unten).

TSimpleAuthenticator

Der einfache Authentifikator stellt eine Basisauthentifizierung wie ein HTML-Formular mit einem Eingabefeld für einen Benutzernamen und einem weiteren für ein Passwort dar. Die Daten werden als Schlüssel=Wert-Tupel übertragen, wobei zuerst der Wert, dann der Benutzername und schließlich das Passwort kommt. Neben dem Benutzernamen und dem Passwort benötigt dieser Authentifikator auch die Namen der Schlüssel. Der Wert für einen Benutzernamen könnte als "user", "username" oder vielleicht einfach nur als "u" übertragen werden. Diese Schlüsselnamen können in den Eigenschaften UserNameKey und PasswordKey angegeben werden.

Je nach Anforderungsmethode werden die Daten entweder bei einer Get-Anforderung im URL (unsicher) oder bei einer Post-Anforderung im Rumpf übertragen.

THTTPBasicAuthenticator

Der Basis-Authentifikator nimmt eine grundlegende HTTP-Authentifizierung vor. Er nimmt einen Wert, der den Benutzernamen und das Passwort enthält, in den HTTP-Header der Anforderung auf. Gemäß der RFC2617-Definition sind der Benutzername und das Passwort in Base64 codiert. Der Header wird für jede Anforderung eingebettet.

TOAuth1Authenticator/ TOAuth2Authenticator

Der OAuth1-Authentifikator unterstützt die Authentifizierung mit der "OAuth 1.0a"-Methode.

OAuth1 ist ein Workflow, der Benutzerinteraktionen einschließt. Das bedeutet, dass für die Unterstützung der OAuth1-Authentifizierung mehr Arbeit erforderlich ist, als einfach nur den Authentifikator einzufügen. Das Grundkonzept von OAuth ist, dass die Anwendung eine Webansicht öffnet, die eine Anmeldeseite des Dienstanbieters (wie z. B. Twitter) enthält. Die Anwendung an sich erhält zu keiner Zeit Zugriff auf den Benutzernamen oder das Passwort des Benutzers; sie empfängt nur Token vom Dienstanbieter und muss anhand dieser Token auf den Dienst zugreifen.

Einige Dienste (wie Twitter oder Google, siehe OAuth2) ermöglichen das Speichern dieser Zugriffs-Token für die spätere Wiederverwendung, um eine weitere ausdrückliche Authentifizierung durch den Benutzer zu vermeiden. Dieses Verhalten ist jedoch ausschließlich vom jeweiligen Dienst abhängig. Andere Dienste löschen die Token eventuell nach einer bestimmten (kurzen) Zeit.

Aufgrund der starken Abhängigkeit von den Dienstanbietern kann eine allgemeine Komponente wie diese nur eine gewisse Unterstützung bieten und die Infrastruktur für den Workflow des Dienstanbieters bereitstellen. Von dieser Klasse können Sie eigene ableiten, um spezifische Authentifikatorklassen für bestimmte Dienstanbieter zu erstellen.

Ein Beispiel für diesen Authentifikator finden Sie unter Beispiele: Twitter, Google Tasks, Facebook.

Erstellen von benutzerdefinierten Authentifikatoren

Wenn keiner der vorhandenen Authentifikatoren für einen bestimmten Dienst anwendbar ist, können Sie benutzerdefinierte Authentifikatoren erstellen. Als ersten Schritt erstellen Sie eine neue von TCustomAuthenticator abgeleitete Klasse zum Überschreiben der Methode DoAuthenticate. Diese Methode übernimmt zwei Parameter: einen Verweis auf den Client, der die aktuelle Anforderung ausführt, und einen Verweis auf die Anforderung selbst.

Bei Bedarf können der Anforderung Parameter hinzugefügt werden.

Weitere Klassen

Zusätzlich zu den Hauptkomponenten Anforderung, Client und Antwort enthält die Bibliothek auch einen Datenmengenadapter, mit dem eine in JSON erstellte Antwort in eine abgeleitete Datenmengenklasse übertragen werden kann.

TRESTResponseDataSetAdapter

Wenn eine REST-Dienstantwort im JSON-Format vorliegt, kann ein RESTResponseDataSetAdapter den Inhalt der Antwort analysieren und die Daten in eine Datenmenge (TDataSet) übertragen.

Allerdings können nicht alle JSON-Daten in eine Datenmengenstruktur umgewandelt werden. Der Parser sucht nach einem JSON-Objekt oder einem Array mit JSON-Objekten. Der Parser sucht nach Sammlungen mit Schlüsselwerten der JSON-Objekte, um die Datenmengenspalten zu erstellen. Aufgrund der Merkmale von JSON-Daten durchläuft der Parser die gesamte Antwort und sammelt Informationen für die Spalten der Datenmenge. Auf diese Weise ist die Datenmenge immer vollständig.

Der Adapter dient nur der Anzeige von Daten. Für die Bearbeitung der Daten und das Eintragen der Daten auf dem Server müssen Sie einen eigenen Adapter erstellen.

Vordefinierte Felder

Vergleichbar mit datenbankbezogenen Datenmengen kann dieser Datenmengenadapter auch Felddefinitionen enthalten. Wenn nicht alle Daten aus der Antwort in die Datenmenge übertragen werden sollen, können Felder vordefiniert werden. In diesem Fall überspringt der Parser die Suche nach Feldern und überträgt einfach die Daten, wenn der Schlüsselname des JSON-Objekts und der Feldname übereinstimmen. Durch die Vordefinition von Feldern kann der Vorgang beschleunigt werden, weil die Suche nach Feldern entfällt.

Definieren eines Stammobjekts

Einige Dienste bilden eventuell eine Antwort, die die Daten in einer "Hülle" mit einigen Metainformationen enthält.

Die gewünschten Daten für die Datenmenge befinden sich im Stammobjekt. Dieser Wert ist ein String mit dem Namen oder den Namen der JSON-Entitäten, die die Daten für den Adapter enthalten. Wenn Sie mehrere Namen festlegen möchten oder müssen, verketten Sie sie mit Punkten, um einen Pfad zu bilden.

Verwendung

Ein Beispiel für diesen Authentifikator finden Sie unter Beispiele: Google Tasks, Facebook.

Beispiele

Die Beispiele sind alle in einem einzigen Projekt – RESTDemos – enthalten, und der Beispielcode befindet sich im "Samples"-Verzeichnis von Delphi. Das Hauptformular enthält mehrere Registerkarten, und jede davon stellt ein Beispiel der REST-Bibliothek dar. In diesem Tutorial zeigen alle Beispiele die Verwendung der Komponenten auf der Quelltextebene. Dieselben Ergebnisse erzielen Sie, wenn Sie die Komponenten auf einem Formular platzieren und sie in geeigneter Weise verbinden.

Zugreifen auf eine einfache API

Verwenden Sie für ein erstes Beispiel den Songsterr-Dienst (www.songsterr.com (EN)), eine Online-Musikdatenbank mit Informationen über Künstler und deren Musik. Grundlegende Abfragen können ohne Voraussetzungen, wie Registrierung oder Autorisierung, durchgeführt werden.

Erstellen Sie ein neues Projekt, und legen Sie drei Komponenten auf dem Formular ab:

  • TRESTRequest
  • TRESTClient
  • TRESTResponse

Wenn Sie zuerst die RESTClient-, dann die RESTRequest- und schließlich die RESTResponse-Komponente ablegen, können Sie sehen, wie diese Komponenten automatisch miteinander verbunden werden.

Die API von SongsTerr ist auf der folgenden Website beschrieben: http://www.songsterr.com/. Alle Anforderungstypen sind dokumentiert und beschrieben.

Für die RESTClient-Komponente müssen Sie die Eigenschaft BaseURL festlegen, die den Haupteintrittspunkt für den Zugriff auf eine API darstellt. In diesem Fall lautet der BaseURL http://www.songsterr.com/a/ra/. Alle Anforderungen an diesen Dienst sollten diesen URL als Basis verwenden. Für die Client-Komponente ist keine weitere Konfiguration erforderlich.

Als Nächstes legen Sie die Eigenschaften für die RESTRequest-Komponente fest. Die Eigenschaft Resource dieser Komponente enthält den eigentlichen Abfrage-String. In diesem Beispiel sollen grundlegende Informationen über Lieder anhand eines Musters abgefragt werden, daher könnte gemäß der Dokumentation der Abfrage-String "songs.json" lauten ("songs.xml" und "songs.plist" wären auch möglich, um die Antworten im XML- bzw- PLIST-Format zu erhalten). Für die Eingabe eines Musters sollten Sie TRESTRequest den Parameter pattern hinzufügen. Für <pattern> können Sie "Madonna", oder was immer Sie möchten, einfügen.

Das ist alles. Die Anforderung kann jetzt in der IDE durch Klicken mit der rechten Maustaste auf die RESTRequest-Komponente und Auswahl von Ausführen im Kontextmenü ausgeführt werden. Nach einem kurzen Moment wird die Eigenschaft "content" der RESTResponse-Komponente mit den Daten von dem Dienst aktualisiert. Sie können diese Eigenschaft auch über LiveBindings mit einer TMemo- oder TEdit-Komponente verbinden.

Ein Nebenaspekt: Sie müssen eine "GET-Anforderung" angeben, und das Muster ist Teil des URL. Gemäß den HTTP-Standards muss dieser Wert "URL-codiert" sein, wenn er Leerzeichen oder andere Sonderzeichen enthält. Verwenden Sie dafür einfach einen Anforderungsparameter vom Typ "URL-Segment".

Ändern Sie jetzt in den RESTRequest-Parametern den Parameter pattern in "Rolling Stones". Führen Sie die Anforderung erneut aus, und Sie werden sehen, dass Sie sich nicht um das Leerzeichen im Namen der Band kümmern müssen. Das Leerzeichen wird automatisch codiert.

Weitere Informationen und ein Beispielprojekt, das den Zugriff auf einen einfachen API-Dienst demonstriert, finden Sie unter Verwenden der REST-Clientbibliothek zum Zugreifen auf REST-basierte Webdienste.

Zugreifen auf die Twitter-API

Das Twitter-Beispiel zeigt, wie eine Verbindung zur Twitter-API mit OAuth1 als Authentifizierungsmechanismus hergestellt wird. Der OAuth1-Workflow wird auch hier beschrieben: https://dev.twitter.com/docs/auth/oauth.

Der Authentifizierungsvorgang besteht aus zwei Schritten: Zuerst müssen Sie einen Authentifizierungscode anfordern. In diesem Schritt muss der Benutzer sein Passwort eingeben. Der zweite Schritt besteht in der Anforderung des Zugriffs-Token. Dies erfolgt für den Benutzer transparent.

Voraussetzung: Registrieren einer Anwendung

Bevor Sie mit Ihrem Client auf die Twitter-API zugreifen können, müssen Sie diesen Client als Anwendung bei der Entwicklerkonsole von Twitter registrieren. Dies können Sie auf der folgenden Seite ausführen: https://dev.twitter.com/apps (EN).

Nach der Registrierung der Anwendung erhalten Sie einen "consumer-key" und ein "consumer-secret", die Sie später für die Authentifizierung verwenden müssen.


Schritt 1: Abrufen eines Anforderungs-Token und eines Authentifizierungscodes

Dies stellt den ersten Teil des OAuth1-Workflows dar. Sie senden Ihren "consumer-key" und Ihr "consumer-secret" an den Anforderungs-Token-Endpunkt von Twitter. Daraufhin erhalten Sie sofort das "Anforderungs-Token" und das "Anforderungs-Token-Secret". Beide Werte benötigen Sie später. Senden Sie nun das Anforderungs-Token zurück an Twitter, aber verwenden Sie diesmal den Zugriffs-Token-Endpunkt. Dies müssen Sie in einer Webansicht ausführen, weil hierfür eine Benutzerinteraktion erforderlich ist. (Randnotiz: Twitter bietet auch die Methode "x-auth" an, für die keine Webansicht erforderlich ist, aber diese Methode steht nur für autorisierte Anwendungen, wie dem offiziellen Twitter-Client, zur Verfügung.)

In der Webansicht zeigt Twitter einen sechsstelligen Verifizierungscode an. Diese Ansicht ist sehr eingeschränkt: Der Code kann nicht ausgewählt und in die Zwischenablage kopiert werden – Sie müssen die Zahlen manuell übertragen.

Schritt 2: Abrufen eines Zugriffs-Token

Mit dem Verifizierungscode aus Schritt 1 führen Sie eine Anforderung an den Zugriffs-Token-Endpunkt aus und erhalten daraufhin ein Zugriffs-Token und ein Zugriffs-Token-Secret. Das Anforderungs-Token und dessen Secret aus Schritt 1 sind ungültig und dessen Werte sollten gelöscht werden – sie können nicht wiederverwendet werden.

Schritt 3: Senden einer Statusaktualisierung ("Tweet")

Jetzt stehen dem OAuth1-Authentifikator alle erforderlichen Daten zum Signieren einer Anforderung an die Twitter-API zur Verfügung, und Sie können Ihre erste Statusaktualisierung ("Tweet") senden.

Zugreifen auf die Google Tasks-API

Das Google-Beispiel zeigt, wie eine Verbindung zur Google-API mit OAuth2 als Authentifizierungsmechanismus hergestellt wird. Der OAuth2-Workflow wird auch hier beschrieben: https://developers.google.com/accounts/docs/OAuth2InstalledApp?hl=de (EN).

Der Authentifizierungsvorgang besteht aus zwei Schritten: Zuerst müssen Sie einen Authentifizierungscode anfordern. In diesem Schritt muss der Benutzer sein Passwort eingeben. Der zweite Schritt besteht in der Anforderung des Zugriffs-Token. Dies erfolgt für den Benutzer transparent.


Voraussetzung: Registrieren einer Anwendung

Bevor Sie mit Ihrem Client auf die Google-API zugreifen können, müssen Sie diesen Client als Anwendung bei der "API-Konsole" von Google-Code registrieren. Dies können Sie auf der folgenden Seite ausführen: https://code.google.com/apis/console?hl=en#access (EN).

Bei der Registrierung der App müssen Sie die APIs auswählen, auf die Sie zugreifen möchten. In diesem Beispiel wählen Sie einfach die "Tasks API" und aktivieren diese. Auf eine API, die nicht für Ihre Anwendung aktiviert wurde, können Sie später nicht zugreifen. Nach der Registrierung der Anwendung erhalten Sie eine "Client-ID" und ein "Client-Secret", die Sie später für die Authentifizierung verwenden müssen.


Schritt 1: Anfordern eines Authentifizierungscodes

Der erste Schritt dieses Workflows umfasst das Anfordern des Authentifizierungscodes. Öffnen Sie dazu eine Webansicht für einen speziellen Google-URL. Für diesen URL sind die folgenden Parameter erforderlich:

  • response_type=code
    Dieser Parameter muss für native Apps bei Google den Wert "code" haben.
  • client_id={CLIENTID}
    Hier müssen Sie Ihre Client-ID eingeben, die Sie nach der Registrierung Ihrer Anwendung erhalten haben.
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob
    Hier wird der konstante URI, der von Google bereitgestellt wird, angegeben, weil Sie einen nativen Client verwenden und es im Gegensatz zu Webanwendungen keine Zielseite gibt, zu der der Benutzer umgeleitet werden könnte.
  • login_hint=user@example.com (optional)
    Damit sich der Workflow für den Benutzer einfacher gestaltet, lässt Google die Angabe eines Anmeldehinweises zu. Dies könnte die E-Mail-Adresse des Benutzers sein, die automatisch in das Anmeldefeld eingefügt wird, damit der Benutzer nur noch sein Passwort eingeben muss.

Ihr vollständiger URL für dieses Beispiel würde folgendermaßen lauten: 

 LURL := ' https://accounts.google.com/o/oauth2/auth ';
 + '?response_type=' + URIEncode('code');
 + '&client_id=' + URIEncode( 'INSERT_YOUR_OWN_CLIENT_ID_HERE' );
 + '&redirect_uri=' + URIEncode('urn:ietf:wg:oauth:2.0:oob');
 + '&scope=' + URIEncode(' https://www.googleapis.com/auth/tasks ');
 + '&login_hint=' + URIEncode('user@example.com'); // optional

Schritt 2: Anfordern eines Zugriffs-Token

Für diesen Schritt benötigen Sie die Komponenten TRESTClient und TRESTRequest: 

  LClient := TRESTClient.Create(' https://accounts.google.com/ ');

Als Nächstes müssen Sie das Anforderungsobjekt erstellen und konfigurieren. Es enthält die folgenden, für Google erforderlichen Parameter:

  • code={AUTHCODE_AUS_SCHRITT#1}
  • client_id={CLIENTID}
    Die Client-ID für Ihre Anwendung, die in der API-Konsole erscheint.
  • client_secret={CLIENTSECRET}
    Das Client-Secret für Ihre Anwendung, das in der API-Konsole erscheint.
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob
    Hier wird der konstante URI, der von Google bereitgestellt wird, angegeben, weil ein nativer Client verwendet wird und es im Gegensatz zu Webanwendungen keine Zielseite gibt, zu der der Benutzer umgeleitet werden könnte.
  • grant_type=authorization_code
    Gemäß der OAuth 2.0-Spezifikation muss dieses Feld einen Wert für "authorization_code" enthalten.

Im Code sollte die Zugriffsanforderung folgendermaßen lauten: 

  LRequest := TRESTRequest.Create(nil);
  LRequest.Method := TRESTRequestMethod.rmPOST;
  LRequest.Resource := 'o/oauth2/token';
  // required parameters
  LRequest.AddParameter('code', 'AUTHCODE_FROM_STEP#1', TRESTRequestParameterKind.pkGETorPOST);
  LRequest.AddParameter('client_id', 'YOUR_CLIENTID', TRESTRequestParameterKind.pkGETorPOST);
  LRequest.AddParameter('client_secret', 'YOUR_CLIENT_SECRET', TRESTRequestParameterKind.pkGETorPOST);
  LRequest.AddParameter('redirect_uri', 'urn:ietf:wg:oauth:2.0:oob', TRESTRequestParameterKind.pkGETorPOST);
  LRequest.AddParameter('grant_type', 'authorization_code', TRESTRequestParameterKind.pkGETorPOST);

Nach Vorbereitung des Anforderungsobjekts können Sie es einfach mit dem Client ausführen: 

  LClient.Execute(LRequest);

Nach erfolgreicher Ausführung der Anforderung erhalten Sie ein Zugriffs-Token im Inhalt der Antwort. Diesen Wert können Sie durch Abfragen des Anforderungsobjekts extrahieren: 

  LClient.Response.TryGetSimpleValue('access_token', LToken);

Sie müssen den Wert des Zugriffs-Token speichern, weil er für alle folgenden Anforderungen an die Google-API benötigt wird.

Zugreifen auf die Facebook-API

In dem Facebook-Beispiel wird gezeigt, wie Sie auf die Graph-API von Facebook mit OAuth2 zugreifen. Als allerersten Schritt müssen Sie das Zugriffs-Token anfordern. Mit diesem Zugriffs-Token greifen Sie später auf die Graph-API zu. Beim Abfragen der API verwenden Sie dieses Zugriffs-Token dann für die Authentifizierung.

Voraussetzung: Registrieren einer Anwendung

Bevor Sie mit Ihrem Client auf die Facebook-API zugreifen können, müssen Sie diesen Client als Anwendung bei Facebook registrieren. Dies können Sie auf der folgenden Seite ausführen: https://developers.facebook.com/apps (EN).

Nach der Registrierung der Anwendung erhalten Sie eine "App-ID", die Sie später für die Authentifizierung verwenden. Bitte beachten Sie, dass diese "App-ID" auch manchmal als "Client-ID" bezeichnet wird.


Schritt 1: Anfordern eines Zugriffs-Token

Facebook bietet eine Reihe von Möglichkeiten für die Anforderung eines Zugriffs-Token. Da Sie nicht die bereitgestellten Facebook-SDKs verwenden, sollten Sie die Methode "Login Flow for Web (without JavaScript SDK)" (Anmeldeablauf für das Web (ohne JavaScript-SDK)) verwenden. Die Dokumentation befindet sich auf der folgenden Website: https://developers.facebook.com/docs/facebook-login/login-flow-for-web-no-jssdk/ (EN).

Sie fordern Ihr Zugriffs-Token durch Öffnen einer Webansicht mit einem Facebook-URL an. Der Basis-URL lautet https://www.facebook.com/dialog/oauth. Sie müssen mehrere Parameter hinzufügen, aber nur die ersten beiden sind erforderlich. Die anderen beiden sind aber sehr hilfreich:

  • client_id={CLIENTID}
    Hier müssen Sie Ihre Client-ID eingeben, die Sie nach der Registrierung Ihrer Anwendung erhalten haben. Sie wird als "App-ID" aufgeführt.
  • redirect_uri=https://www.facebook.com/connect/login_success.html
    Hier wird der konstante URI, der von Facebook bereitgestellt wird, angegeben, weil Sie einen nativen Client verwenden und es im Gegensatz zu Webanwendungen keine Zielseite gibt, zu der der Benutzer umgeleitet werden kann.
  • response_type=token
    Für Facebook müssen native Anwendungen "token" als Wert für "response type" verwenden. Dadurch wird der Anmeldemechanismus veranlasst, das Zugriffs-Token als zusätzlichen Teil in den Umleitungs-URI aufzunehmen.

Ihr vollständiger URL für dieses Beispiel würde folgendermaßen lauten: 

  LURL := 'https://www.facebook.com/dialog/oauth'
   + '?client_id=' + URIEncode( 'INSERT_YOUR_OWN_CLIENT_ID_HERE' )
   + '&response_type=token'
   + '&scope=' + URIEncode('user_about_me,user_birthday')
   + '&redirect_uri=' + URIEncode(' https://www.facebook.com/connect/login_success.html ');

Das Zugriffs-Token ist ungefähr zwei Stunden gültig. Es kann im Hintergrund aktualisiert werden, ohne dass der Benutzer sich erneut authentifizieren muss. Weitere Informationen finden Sie unter https://developers.facebook.com/docs/facebook-login/access-tokens/#extending (EN).

Schritt 2: Abrufen von Benutzerinformationen

Sie benötigen jetzt die folgenden Komponenten: TRESTCient, TRESTRequest, TRESTResponse und TOAuth2Authenticator.

Der erste Schritt besteht wieder im Erstellen des Clients und des Authentifikators und dem Verbinden der beiden: 

 LClient := TRESTClient.Create(' https://graph.facebook.com/ ');

 LOAuth2 := TOAuth2Authenticator.Create(self);
 with (LOAuth2 AS TOAuth2Authenticator) do
 begin
   AccessToken := 'YOUR_OWN_ACCESS-TOKEN_FROM_STEP#1';
 end;
 LClient.Authenticator := LOAuth2;

Als Nächstes müssen Sie die Anforderung vorbereiten. Der Ressourcen-URI wurde durch den Graph Explorer von Facebook generiert. Dieser URI gibt Ihren Namen, Ihren Geburtstag (falls Sie sich nicht mehr daran erinnern können...) sowie die Namen Ihrer ersten zehn Kontakte ("Freunde") zurück. Der Graph Explorer befindet sich auf der folgenden Website: https://developers.facebook.com/tools/explorer (EN). 

 LRequest := TRESTRequest.Create(nil);
 LRequest.Method := TRESTRequestMethod.rmGET;
 LRequest.Resource := 'me?fields=name,birthday,friends.limit(10).fields(name)';

Das ist alles. Sie können jetzt die Anforderung mit dem Client ausführen: 

  LClient.Execute(LRequest);

Der in JSON codierte Inhalt befindet sich im Antwortobjekt des Clients. Dieses Antwortobjekt wurde vom Client ad hoc erstellt, weil Sie kein Antwortobjekt bereitgestellt haben. 

  memo_ResponseData.Lines.Text := LClient.Response.Content;

Umwandeln einer Antwort in eine Datenmenge

Eine in JSON erstellte Antwort eines Dienstes kann in eine beliebige von TDataSet abgeleitete Klasse umgewandelt werden. Dazu müssen die Daten in einer Form vorliegen, die in eine Datenmenge übertragen werden können. Das kann entweder ein JSON-Objekt oder ein Array mit JSON-Objekten sein. Jedes Objekt ist ein neuer Datensatz in der Datenmenge. Die Eigenschaften von JSON-Objekten bilden normalerweise die Spalten in der Datenmenge.

Siehe auch

Abgerufen von „https://docwiki.embarcadero.com/RADStudio/Alexandria/d/index.php?title=REST-Clientbibliothek&oldid=218426“