Beispiel: OAuth 2.0-Autorisierung
In diesem Beispiel wird gezeigt, wie Sie einen REST-Webservice, für den eine OAuth 2.0-Autorisierung erforderlich ist, aufrufen. Die Client-Applikation ist ein MapForce Mapping. Darin werden über die Google Calendar API (https://developers.google.com/calendar/) Kalenderereignisse abgerufen. Aus Gründen der Einfachheit ruft das Mapping die Kalenderinformationen im Istzustand ab und gibt nur das rohe JSON-Result aus, ohne dieses weiter zu verarbeiten.
Voraussetzungen:
•MapForce Enterprise Edition
•Um dieses Beispiel durchspielen zu können, benötigen Sie ein Google-Konto. Wenn Sie einen anderen Webservice aufrufen möchten, fordern Sie OAuth 2.0-Anmeldeinformationen von Ihrem Webservice-Anbieter an und verwenden Sie diese in der unten stehenden Anleitung.
Anforderung der OAuth 2.0-Anmeldeinformationen
Wenn Sie die erforderlichen OAuth 2.0-Anmeldeinformationen für den Aufruf des Webservice bereits zur Verfügung haben, können Sie diesen Schritt überspringen. Andernfalls ist der genaue Ablauf vom Anbieter des Webservice, der von Ihrem Mapping aufgerufen wird, abhängig. Um die Google Calender API, wie in diesem Beispiel gezeigt, aufzurufen, gehen Sie folgendermaßen vor:
1.Melden Sie sich bei der Google API-Konsole (https://console.developers.google.com/) an.
2.Erstellen Sie ein neues Projekt.
3.Klicken Sie auf OAuth-Zustimmungsbildschirm.
4.Wählen Sie als Benutzertyp Extern, es sei denn, Sie haben ein G Suite-Konto, über das Sie nur Benutzern in Ihrem Unternehmen API-Zugriff einräumen können.
5.Geben Sie "mapforce-demo" als Applikationsnamen ein und speichern Sie die Einstellungen.
6.Klicken Sie auf Anmeldedaten erstellen wählen Sie anschließend OAuth-Client-ID aus.
7.Geben Sie als Applikationstyp Desktopanwendung und als Client-Namen "MapForce Client" ein.
8.Klicken Sie auf Erstellen. Daraufhin wird die Client-ID erstellt und steht auf der Seite Anmeldedaten zur Verfügung.
9.Klicken Sie auf 
, um die OAuth 2.0-Autorisierungsinformationen als JSON-Datei herunterzuladen.
Sie haben nun die folgenden OAuth 2.0-Autorisierungsinformationen von der Google Console API erhalten:
1.Autorisierungsendpunkt
2.Token-Endpunkt
3.Client ID
4.Client Secret
Aktivieren der Google Calender API
Um Aufrufe von Clients zu akzeptieren, muss die in diesem Beispiel verwendete Google Calendar API aktiviert werden. Klicken Sie in der Google API-Konsole auf Bibliothek, suchen Sie die Google Calendar API und aktivieren Sie sie:
In diesem Beispiel werden wir die list-Methode der Events Entity aufrufen. Ausführliche Informationen über diese API-Methode finden Sie unter https://developers.google.com/calendar/v3/reference/events/list. Beachten Sie die folgenden wichtigen Punkte:
1.Wie in der Dokumentation beschrieben, muss die Methode durch Senden eines GET Request an https://www.googleapis.com/calendar/v3/calendars/calendarId/events aufgerufen werden, wobei calendarId der Identifier eines Google Calendar ist. Der Request-Parameter calendarId wird in der Folge später über MapForce konfiguriert.
2.Für den Aufruf der API-Methode ist mindestens einer der folgenden Geltungsbereiche erforderlich:
•https://www.googleapis.com/auth/calendar.readonly
•https://www.googleapis.com/auth/calendar
•https://www.googleapis.com/auth/calendar.events.readonly
•https://www.googleapis.com/auth/calendar.events
Ihr Mapping muss während der OAuth 2-Autorisierung einen dieser Geltungsbereiche angeben. Auch dieser wird in einem späteren Schritt konfiguriert. Für dieses Beispiel ist der erste Geltungsbereich "read-only" ausreichend.
Anforderung eines Autorisierungs-Token
Um in MapForce eine Vorschau auf das Mapping anzeigen zu können, benötigen Sie die OAuth 2.0-Autorisierungsinformationen für das Mapping und müssen, wie unten gezeigt, ein Autorisierungs-Token anfordern.
1.Klicken Sie in MapForce mit der rechten Maustaste in einen leeren Bereich des Mappings und wählen Sie im Kontextmenü den Befehl Anmeldeinformationen-Manager öffnen.
2.Klicken Sie auf 
Anmeldeinformationen hinzufügen.
3.Geben Sie einen Namen ein (in diesem Beispiel "my.oauth") und wählen Sie als Typ OAuth 2 aus.
4.Füllen Sie die Textfelder Autorisierungsendpunkt, Token-Endpunkt, Client ID, Client Secret mit den entsprechenden Werten aus der zuvor heruntergeladenen JSON-Datei aus.
5.Geben Sie https://www.googleapis.com/auth/calendar.readonly in das Textfeld Geltungsbereich ein.
6.Belassen Sie alle anderen Einstellungen unverändert.
7.Klicken Sie auf Access Token anfordern, um das Token vom Autorisierungsserver (in diesem Beispiel Google) anzufordern. Daraufhin wird ein Browser-Fenster geöffnet, in dem Sie gebeten werden, sich mit Ihrem Google-Konto zu verbinden.
8.Melden Sie sich bei Ihrem Google-Konto an. Da Sie noch keine App-Überprüfungsanforderungen an Google gesendet haben, wird die folgende Seite angezeigt.
9.Klicken Sie auf Erweitert und anschließend auf mapforce-demo öffnen (unsicher).
10.Klicken Sie auf Zulassen. Daraufhin wird eine Bestätigung im Browser angezeigt.
MapForce zeigt ebenfalls eine Meldung an, dass der OAuth 2.0-Autorisierungscode erfolgreich abgerufen wurde.
11.Klicken Sie auf OK. Beachten Sie, dass die Felder Access Token und Refresh Token nun ausgefüllt wurden.
12.Speichern Sie das Mapping unter dem Namen GetCalendarEvents.mfd.
In diesem Tutorial wurde das Kontrollkästchen Verschlüsselt in MFD-Datei speichern im Dialogfeld "Anmeldeinformationen bearbeiten" aktiviert. Daher werden die sensiblen Daten in den Feldern Client Secret, Autorisierungs-Token und Refresh Token beim Speichern des Mappings in verschlüsselter Form in der Mapping-Design-Datei (.mfd) gespeichert. |
Beachten Sie, dass das Autorisierungs-Token nach einem gewissen Zeitraum abläuft. Wenn dies passiert, können Sie das Mapping nicht mehr ausführen (derzeit wurde noch kein Mapping erstellt, dies geschieht in einem späteren Schritt). Wenn Sie manuell einen neuen Autorisierungscode anfordern möchten, klicken Sie auf Access Token anfordern gehen Sie vor, wie unten beschrieben.
Erstellen des Webservice-Aufrufs
Das bisher erstellte Mapping GetCalendarEvents.mfd hat noch keine Funktionen. Es enthält bisher nur OAuth 2.0-Anmeldeinformationen, die den Zugriff auf die Google Calender API aktivieren.
Wir werden nun den Webservice-Aufruf in MapForce folgendermaßen erstellen:
1.Öffnen Sie das Mapping GetCalendarEvents.mfd.
2.Klicken Sie im Menü Einfügen auf Webservice-Funktion. Daraufhin wird das Dialogfeld "Webservice-Call-Einstellungen" aufgerufen.
3.Klicken Sie auf Manuell.
4.Wählen Sie als Request-Methode GET aus und geben Sie die URL zu dem im vorigen Schritt erwähnten Webservice ein: https://www.googleapis.com/calendar/v3/calendars/calendarId/events.
5.Da calendarId ein Platzhalter ist, der in Form eines Parameters angegeben werden muss, setzen Sie ihn in geschweifte Klammern, wie unten gezeigt.
6.Klicken Sie auf die Schaltfläche 
Parameter hinzufügen und definieren Sie die folgenden Parameterinformationen:
Aufgrund des Stils "Vorlage" in der Konfiguration oben kann der in geschweifte Klammern gesetzte Teil der URL zur Laufzeit durch den Parameterwert ersetzt werden. "Mapbar" bedeutet, dass der Wert über das Mapping bereitgestellt werden kann (z.B. über eine Konstante oder eventuell einen Input-Parameter). Außerdem wurde der Parameter als "Obligatorisch" gekennzeichnet, da der API-Aufruf nicht ohne diesen Parameter durchgeführt werden kann. Nähere Informationen dazu finden Sie unter Definieren von Webservice-Parametern.
7.Klicken Sie neben HTTP-Sicherheitseinstellungen auf Bearbeiten.
8.Aktivieren Sie im Dialogfeld "HTTP-Sicherheitseinstellungen" die Option Anmeldeinformationen verwenden und wählen Sie den zuvor konfigurierten Datensatz "my.oauth" aus.
Der bisher konfigurierte Webservice wird im Mapping folgendermaßen angezeigt:
Sie können das Design nun folgendermaßen fertig stellen:
1.Klicken Sie im Menü Einfügen auf Input-Komponente einfügen und konfigurieren Sie die Komponente folgendermaßen:
Wie oben gezeigt, hat die Input-Komponente den Design-Zeit-Wert "primary". Laut API-Dokumentation bewirkt der Wert "primary", dass der API-Server den primären Google-Kalender des aktuell angemeldeten Benutzers aufruft. Beachten Sie dass dieser Wert ein Design-Zeit-Wert ist und nur gilt, wenn Sie in MapForce eine Vorschau auf das Mapping anzeigen. Wenn das Mapping in einer Server-Umgebung ausgeführt wird, muss der gewünschte Wert zur Laufzeit bereitgestellt werden.
2.Ziehen Sie die Funktion decode-mime-entity aus dem Fenster "Bibliotheken" in den Mapping-Bereich. Diese Funktion konvertiert den vom Server erhaltenen rohen MIME-Body in einen String.
3.Klicken Sie im Menü Einfügen auf Output-Komponente einfügen und fügen Sie eine einfache Output-Komponente hinzu, deren Aufgabe es ist, das Ergebnis als einfachen String auszugeben.
4.Verbinden Sie die Komponenten als nächstes wie unten gezeigt.
Damit ist der Design-Teil in MapForce abgeschlossen.
Testen der Mapping-Ausführung
Um die Ausführung des Mappings in MapForce zu testen, klicken Sie auf das Register Ausgabe, um das Ergebnis im Fenster "Meldungen" zu sehen.
Wenn Sie einen Autorisierungsfehler wie z.B. "Unauthorized (401)" erhalten, beachten Sie die folgenden Tipps zur Fehlerbehebung:
1.Stellen Sie sicher, dass die Google Calendar API aktiviert ist, siehe Aktivieren der Google Calender API.
2.Falls das zuvor erhaltene Access Token bereits abgelaufen ist, fordern Sie ein neues Autorisierungs-Token an.
3.Überprüfen Sie, ob alle OAuth 2.0-Informationen korrekt in MapForce eingegeben wurden.
Wenn das Mapping erfolgreich ausgeführt werden konnte und MapForce die OAuth 2.0-Autorisierung abrufen konnte, sollte die Mapping-Ausgabe ähnlich wie unten gezeigt aussehen:
Wenn Sie ein Google-Konto verwendet haben, das wie in diesem Beispiel keine Kalenderereignisse enthält, ist das Array "items" in der Antwort leer. Wenn Sie jedoch ein Ereignis zu Ihrem Google-Kalender hinzufügen und das Mapping erneut ausführen, wird dies in der Ausgabe entsprechend angezeigt. Sie können übrigens auch Ereignisse aus einem anderen Kalender, als dem Standardkalender abrufen. So könnten Sie z.B. Daten aus einem öffentlichen Kalender wie z.B. "Holidays in United States" abrufen. Setzen Sie zu diesem Zweck den Wert des Parameters calendarId auf en.usa#holiday@group.v.calendar.google.com anstelle von primary.
Informationen zu anderen Parametern, die Sie zum API-Aufruf hinzufügen können, finden Sie in der Dokumentation zur API-Methode unter https://developers.google.com/calendar/v3/reference/events/list.