Warum REST?

Obwohl es APIs oder Anwendungs-Plugins in vielen Varianten und Standards gibt, werde ich meinen persönlichen Favoriten besprechen: REST-Dienste. Sie fragen sich vielleicht: „Warum REST?“ Die Antwort ist einfach: Es ist einfacher als SOAP. Es gibt auch andere Gründe: REST unterstützt mehr Datenformate als SOAP, das nur XML unterstützt. Ein weiterer wichtiger Grund, warum ich REST für das BESTE halte, ist, dass es Hand in Hand mit JSON geht.

JSON (JavaScript Object Notation) bietet im Allgemeinen eine schnellere Datenanalyse, was eine bessere Unterstützung für Browser mit diesem leichten Datenformat bedeutet. Schließlich ist die Nutzung von REST-APIs in Mendix erfordert keine Installation von Client-Bibliotheken oder Dateien, damit Ihre App funktioniert.

Welche API verwende ich?

Die Google Cloud API umfasst eine ganze Reihe der besten Dienste von Google, die alle in nutzbare Methoden unterteilt sind, von denen viele völlig kostenlos verwendet werden können. Bevor Sie jedoch mit einer dieser APIs interagieren können, muss sich Ihre Anfrage mit einem OAuth-Token authentifizieren. Google verwendet OAuth 2.0 als De-facto-Authentifizierungsmethode für die meisten seiner APIs. Das bedeutet, dass ein Benutzer, um eine Google-API verwenden zu können, zunächst die Google Identity API (Für serverseitige Apps), um nachfolgende Aufrufe der Google-Dienste zu tätigen.

Mit anderen Worten: Der Erhalt eines Tokens ist der erste Schritt zur Implementierung vieler APIs von Google und ein guter Ausgangspunkt für jemanden, der in die API-Entwicklung einsteigen möchte.

Voraussetzungen:

Bevor Sie beginnen, geht dieser Blog davon aus, dass Sie eine beliebige Google API für ein Projekt auf der Google Cloud Platform aktiviert und die Seite mit den OAuth-Anmeldeinformationen , OAuth-Zustimmungsbildschirme für dieses Google-Projekt. Insbesondere müssen Sie Umleitungs-URLs für Ihre App konfigurieren, damit diese auf Ihren lokalen Host oder die bereitgestellte Webanwendung verweisen. Außerdem benötigen Sie sowohl eine Client-ID als auch ein Client-Geheimnis von Google, nachdem Sie den OAuth-Client Ihrer App konfiguriert haben.

Ein Wort zu REST-Methoden

In diesem Beispiel verwende ich eine POST-Methode, um die Identity API von Google aufzurufen. Aber was bedeutet das? In REST gibt es 5 Methoden, die Sie kennen müssen:

• jetzt lesen — Dies wird zum Erstellen neuer Datensätze verwendet
• STARTE — Dies gibt einen Datensatz oder eine Liste von Datensätzen zurück
• SETZEN — Wird zum Aktualisieren oder Ersetzen eines Datensatzes verwendet
• PATCH — Wird zum Aktualisieren oder Ändern eines Datensatzes verwendet
• LÖSCHEN — Löscht oder vereinfacht den Datensatz

Es gibt noch einige andere Methoden, die ich kenne, aber ich bin ihnen bei meiner Arbeit nie begegnet. Wenn Sie interessiert sind, gibt es eine gute Zusammenfassung der Methoden hier.

Ein allgemeiner Plan zur Integration von REST-Diensten

Je nachdem, welche Methode Sie verwenden und welche API Sie nutzen, können die tatsächlichen Schritte zum Abschließen einer Integration variieren. Beispielsweise hat eine GET-Anforderung keinen Anforderungstext und verwendet stattdessen Abfragezeichenfolgen. Im Allgemeinen sind hier jedoch die Schritte zum Verwenden eines REST-Dienstes in Mendix Studio Pro:

1. Legen Sie Ihren Standort fest

• Auch als Endpunkte oder URI bekannt. Dies ist der Ort, an dem der Dienst gehostet wird.

2. Wählen Sie Ihre HTTP-Methode

• Sie haben die Wahl zwischen den oben genannten Methoden. Im Allgemeinen erfahren Sie in der API-Dokumentation, welche Sie auswählen sollten.

3. Authentifizierung

• Kann entweder OAUTH oder ein API-Schlüssel sein oder ist überhaupt nicht erforderlich.

4. HTTP-Header

• Header können verschiedene Rollen spielen. Jeder Dienst kann eindeutige Header haben. Sie müssen die Dokumentation für die API zu Rate ziehen, die Sie verwenden möchten.

Um das Format der Antwort festzulegen, können wir den Header „Inhaltstyp“ und versehen Sie es mit dem Wert „Anwendung/JSON“ für das JSON-Format oder “Anwendung/XML” für XML. Es gibt noch weitere Optionen wie 'Anwendung/x-www-form-urlencoded', das wir in diesem Tutorial verwenden werden (sehen Sie sich diesen Stack Overflow-Beitrag an, um eine großartige Zusammenfassung von alle Inhaltstypen).

5. Erstellen Sie die Anfrage

• Für die meisten Methoden müssen Sie einen Anforderungstext angeben, normalerweise im JSON-Format. Für GET-Methoden verwenden wir normalerweise Abfragezeichenfolgen, die am Ende des Standorts hinzugefügt werden, um Parameter zu übergeben. Diese sind normalerweise durch ein „?“ am Ende des Standorts gekennzeichnet, auch als URI bekannt.

6. Behandeln Sie die Antwort

• Hierfür gibt es einige Optionen, beispielsweise das Speichern der Antwort in einer Zeichenfolgenvariablen oder das Anwenden einer Importzuordnung, die die Daten Ihrem Domänenmodell zuordnet. Die beste Option ist von Fall zu Fall unterschiedlich, in den meisten Fällen sollten Sie sich jedoch für die Anwendung einer Importzuordnung entscheiden.

Wie funktioniert Google Identity?

Bevor wir beginnen können, eine kurze Erklärung, wie Google OAuth 2.0 für serverseitige Apps implementiert.

Dokumentation von Google erklärt es in 5 Schritten, die ich hier für Sie zusammenfasse: Verwenden von OAuth 2.0 für Webserveranwendungen | Google Identity | Google Developers.

Schritt 1: Autorisierungsparameter festlegen

Das bedeutet, dass wir eine URL in unserem Mendix App, die detailliert beschreibt, worauf unsere Anwendung im Namen des Benutzers von den Google-Diensten zugreifen möchte.

In Schritt 2 wird der Benutzer zu dieser Google-URL weitergeleitet, um den Zugriff auf sein Google-Konto zu genehmigen. Anschließend wird er zurück zu Ihrer Mendix App, zusammen mit einem Zugangscode, den wir zur Autorisierung unserer Token-Anforderung verwenden.

Die wichtigen Werte sind hierbei:

• Umgeleitete URI (Sollte auf die URL Ihrer App weiterleiten),
• Scopes (Berechtigungen für Google APIs wie Mail/Drive/Translate etc., klicken Sie auf werden auf dieser Seite erläutert für eine Liste aller Bereiche für Google APIs)
• Kunden-ID (Client-ID wird von Google bereitgestellt, nachdem Sie Ihre App unter OAuth registriert haben)
• Staat (Ein von der App verwendeter Wert zur Statusbeibehaltung, eine Kennung, mit der Sie später die richtige Anfrage abrufen können)

Hier ist ein Beispiel, wie diese URL aussehen könnte:

https://accounts.google.com/o/oauth2/v2/auth?kann=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-translation&Zugriffstyp=offline&Gewährte Bereiche einschließen=wahr&Antworttyp=Code&Zustand= 123 &Umleitung_uri=https://localhost:8080/link/googleredirect?Code=&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com

Schritt 2: Weiterleitung zum OAuth 2.0-Server von Google

Leiten Sie den Benutzer zur URL weiter, die Sie in Schritt 1 erstellt haben (ich habe die in Nanoflows verfügbare Javascript-Aktion „URL öffnen“ verwendet).

Schritt 3: Google fordert den Nutzer zur Zustimmung auf

Der Benutzer wird von Google aufgefordert, sich anzumelden bzw. sein Konto auszuwählen und dann den von Ihrer App angeforderten Zugriff zu genehmigen.

Schritt 4: Verarbeiten der OAuth 2.0-Serverantwort

Nachdem der Benutzer die Anfrage an sein Konto bestätigt hat, leitet Google den Benutzer zum Umleitungs-URI-Parameter weiter, den wir in Schritt 1 angegeben haben. Dies ist Ihre App-URL, aber in meinem Fall habe ich die Deeplink Modul zur Handhabung der Weiterleitung. Auf diese Weise konnte ich auf den Autorisierungscode zugreifen, den Google in den Link einfügt. Dies ist ein Beispiel für den Deep Link, der zur Handhabung dieses Problems erstellt wurde:

https://localhost:8080/link/googleredirect?code=

Schritt 5: Autorisierungscode gegen Aktualisierungs- und Zugriffstoken austauschen

Sobald Google Ihnen die Zugangscode, können Sie nun den REST-Aufruf durchführen, um es gegen ein offizielles Token einzutauschen. Hier ist die Anfrage und Antwort für mein Beispiel

Ich habe mein Projekt bei Google gelöscht. Nach der Veröffentlichung funktionieren diese Anfragen nicht mehr so ​​wie sie sind (Sie müssen Ihre eigene Client-ID und Ihr eigenes Client-Geheimnis verwenden)

Fordern Sie Inhalt für POST-Anforderung an https://oauth2.googleapis.com/token?grant_type=authorization_code&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&client_secret=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&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3D 
HTTP/1.1 Inhaltstyp: application/x-www-form-urlencoded

code=4%2F0AdQt8qiGaCaJYgKgRpHKqXj8265JL72PfsKpusgctqYXhVwPxg5qn4EHU9iUGnMxMiHiqA

Antwortinhalt für POST-Anfrage an https://oauth2.googleapis.com/token?grant_type=authorization_code&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&client_secret=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&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3D
HTTP/1.1 200 OK Cache-Steuerung: kein Cache, kein Speicher, max. Alter=0, muss erneut validiert werden Pragma: kein Cache Datum: Mo., 01. August 2022, 12:53:44 GMT Läuft ab: Mo., 01. Januar 1990, 00:00:00 GMT Inhaltstyp: application/json; charset=utf-8 Variiert: Ursprung Variiert: X-Ursprung Variiert: Referrer-Server: Gerüst auf HTTPServer2 X-XSS-Schutz: 0 X-Frame-Optionen: SAMEORIGIN X-Content-Type-Optionen: nosniff Alt-Svc: h3=”:443"; ma=2592000,h3–29=”:443"; ma=2592000,h3-Q050=“:443"; ma=2592000,h3-Q046=“:443"; ma=2592000,h3-Q043=“:443"; ma=2592000,quic=“:443"; ma=2592000; v=“46,43“ Transfer-Encoding: Chunked

{
 “access_token”: “ya29.A0AVA9y1tawnqK-42beGFAomiTqx8Zg0UUiedmIIPaAIraSas6VEO2D7NH5rInBPCUQK_7aghDiiTVrD_SnnQzOAtGq3XP2GQfWbpuZmDFjWfL0FSAw6JQU37mthQnRFsJvvqlgzTcryTdruKiOtcc63YrI8DvYUNnWUtBVEFTQVRBU0ZRRTY1ZHI4NjVOQUxhR2ppS0kyOVpINVZoYTJ4Zw0163”,
 “expires_in”: 3599,
 “scope”: “https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-translation", „token_type“: „Träger“ }

Nachdem Sie nun hoffentlich die Architektur dahinter verstanden haben, können wir auf die Einzelheiten des Aufrufs der Token-API eingehen.

Aufruf der API in Mendix

Legen Sie den Standort fest

Um Ihren Standort festzulegen, gehen Sie zu den Eigenschaften Ihrer Aufruf-REST-Aktion (in einem Mikrofluss) und klicken Sie auf Bearbeiten. Sie können den Standort hier festlegen, indem Sie die URI angeben, unter der sich die API befindet, in Anführungszeichen, da es sich um eine Zeichenfolgenwert.

Es empfiehlt sich jedoch, eine Anwendungskonstante zum Speichern dieser Daten zu erstellen, sodass Sie sich über Tippfehler oder Kopier- und Einfügefehler keine Gedanken machen müssen.

Der Standort hierfür ist https://oauth2.googleapis.com/token. Denken Sie daran, dass wir am Ende des Standorts eine Abfrage anhängen.

Auswählen der HTTP-Methode

Wie oben erwähnt, verwenden wir die POST-Methode für diese Integration. Ich habe dies ausgewählt, weil die Dokumentation von Google in ihrem Beispiel angibt, dass dies so sein sollte.

Als nächstes: Authentifizierung

Um sicherzustellen, dass wir registrierte Benutzer sind, müssen wir Google in unserer Anfrage einige Details übermitteln. Wir müssen die Client-ID und Client-Geheimnis Unsere App wurde von Google herausgegeben (Als Abfragefelder) und wir müssen die Zugangscode dem Benutzer im Anforderungstext gewährt.

Welche Header brauchen wir?

Für diese Anfrage müssen wir nur den Header 'Inhaltstyp' und geben Sie den Wert 'application / x-www-form-urlencoded'. Wir geben dies weiter, da es Google mitteilt, welches Format Ihre Anfrage verwendet.

Überprüfen Sie immer die bereitgestellte Dokumentation, bevor Sie davon ausgehen, dass keine vorhanden ist, da das Fehlen eines erforderlichen Headers normalerweise zu einer 401-Antwort (ungültige Anforderung) führt.

Erstellen unserer Abfrage

Da wir für unsere Anfrage einige Parameter in der URI übergeben müssen, müssen wir unsere Abfrage an den Basisspeicherort der APIs anhängen.

Der Standort der Basis:

https://oauth2.googleapis.com/token

Die zusätzliche Abfragezeichenfolge:

?Grant_type=Autorisierungscode&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&Client_Secret=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&Umleitung_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3

Hier ist eine Aufschlüsselung der Bedeutung der einzelnen Felder direkt von Google:

Denken Sie daran, Ihre Abfrage per URL zu kodieren bevor Sie die Anfrage stellen.

URL-Kodierung? Was ist das?

Wenn die Abfragezeichenfolge Sonderzeichen oder Leerzeichen enthält, führt dies zu einem 401-Fehler (Bad Request). Dies ist einfach eine Möglichkeit, diese Sonderzeichen in etwas zu übersetzen, das von Browsern allgemein akzeptiert wird. Die URL-Kodierung ist eine Zeichenfolgenfunktion in Mendix, die Sie in jedem Mikro- oder Nanoflow aufrufen können.

Jetzt können Sie alles zusammenfügen und Ihre endgültige Zeichenfolge sollte ungefähr so ​​aussehen

https://accounts.google.com/o/oauth2/v2/auth?kann=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-translation&Zugriffstyp=offline&Gewährte Bereiche einschließen=wahr&Antworttyp=Code&Zustand= 1 &Umleitung_uri=https://localhost:8080/link/googleredirect?code=&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com

Bedenken Sie, dass die eigentliche Abfrageanweisung Ihre Anmeldeinformationen enthält und den Zugriffscode und die Umleitungs-URL Ihres App-Benutzers bereitstellt. Sie unterscheidet sich daher von meiner.

Definieren des Anforderungstexts

Da es sich um eine Post-Methode handelt, müssen wir einen Request-Body angeben. Wählen Sie unter Request Benutzerdefinierte Anforderungsvorlage und geben Sie den Textkörper an:

Code=IHR BENUTZERZUGRIFFSCODE

Nun zur Bearbeitung der Antwort

Mendix erlaubt uns zu Anwenden einer Importzuordnung um die Antwortdaten in Ihr Domänenmodell abzubilden.

Dazu benötigen Sie ein JSON-Beispiel der Antwort. In der Dokumentation von Google finden Sie dieses Beispiel.

{ "Zugriffstoken": "1/fFAGRNJru1FTz70BzhT3Zg", "läuft ab in": 3920, "Tokentyp": "Träger", "Bereich": "https://www.googleapis.com/auth/drive.metadata.readonly", "Aktualisierungstoken": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }

Wählen Sie in Studio Pro unter der Registerkarte „Antwort“ der REST-Anrufaktivität die Option „Importzuordnung anwenden“ aus.

Wählen Sie im angezeigten Fenster die Option zum Erstellen einer neuen Importzuordnung aus und geben Sie der Zuordnung einen Namen.

Klicken Sie im Import Mapping Editor auf „Elemente auswählen” in der oberen linken Ecke des Bildschirms. Wählen Sie „JSON-Struktur“ als Option hierfür.

Wählen Sie oder Erstellen Sie das JSON-Mapping, mit einem passenden Namen. Fügen Sie nun das JSON von oben in den Textbereich ein und klicken Sie auf „Aktualisieren“.

Klicken Sie auf „OK“, um das Fenster zu schließen. Klicken Sie nun auf dem Bildschirm „Elemente auswählen“ auf „Alle erweitern“ und dann auf „Alles markieren“, bevor Sie auf „OK“ klicken.

Als nächstes können Sie in der Importzuordnung einfach auf „Automatisch zuordnen“ klicken. Studio Pro erstellt automatisch alle erforderlichen Entitäten und Zuordnungen. Standardmäßig werden diese als nicht persistente Entitäten erstellt (Entitäten, die im Speicher vorhanden sind und nicht in die Datenbank übertragen werden). Sie können diese Zuordnung bei Bedarf manuell ändern, aber in den meisten Fällen gibt es keine und Sie können sie so belassen.

Sie können jetzt auf die von der API in Ihrem Mikroflow zurückgegebenen Daten zugreifen und diese abrufen.

Was mit den Daten im Einzelnen geschieht, sobald sie in Ihrer App zugänglich sind, liegt bei Ihnen. Jeder Dienst ist anders, keine zwei Implementierungen sind gleich.

In meinem Beispiel speichere ich das Token in einer dauerhaften Entität, die mit dem Benutzerkonto in der Datenbank verknüpft ist. Bei einer Implementierung in der Praxis sollten Sie jedoch auch über die Hinzufügung einer Verschlüsselung nachdenken.

Das ist alles, Leute

Ich hoffe, Sie fanden dies hilfreich, wenn Sie mehr darüber lesen möchten, wie Sie REST-Dienste implementieren in Mendix, schau dir unsere an Dokumentation Seite für weitere Informationen, oder besuchen Sie unsere academy und fangen Sie an zu lernen.