Altova FlowForce Server 2024 Advanced Edition

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 FlowForce Server-Auftrag. Darin werden über die Google Calendar API (https://developers.google.com/calendar/) Kalenderereignisse abgerufen. Aus Gründen der Einfachheit ruft der -Auftrag die Kalenderinformationen im Istzustand ab und gibt nur das rohe JSON-Result aus, ohne dieses weiter zu verarbeiten.

Voraussetzungen:

•MapForce Enterprise Edition

•MapForce Server Advanced Edition

•FlowForce Server Advanced 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.

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.

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.

Bereitstellen des Mappings auf FlowForce Server

In diesem Abschnitt wird beschrieben, wie Sie das Demo-OAuth 2.0-Mapping mit MapForce Server unter FlowForce Server-Verwaltung ausführen. Es gelten die folgenden Voraussetzungen:

1.Die FlowForce Server Advanced Edition muss installiert und lizenziert sein.

2.Die MapForce Server Advanced Edition muss installiert und lizenziert sein.

3.Der "FlowForce Web Server"-Dienst muss unter der vorgesehenen Adresse und am angegebenen Port gestartet und empfangsbereit sein. Wenn FlowForce Server mit den Standardeinstellungen auf dem aktuellen Rechner installiert wurde, lautet die Adresse http://localhost:8082.

4.Sie benötigen ein FlowForce Server-Benutzerkonto und Schreibzugriff auf einen der FlowForce Server Container. Aus Gründen der Einfachheit wurde in diesem Beispiel das FlowForce Server Standard-root-Konto verwendet. Das Mapping wurde im Standardcontainer public bereitgestellt; diese Informationen können andernfalls konfiguriert werden.

Um das Mapping als Auftrag in einer Server-Umgebung ausführen zu können, müssen Sie es für die angegebene FlowForce Server-Instanz bereitstellen. Bevor Sie das Mapping bereitstellen, müssen die OAuth 2.0-Anmeldeinformationen auf eine der folgenden Arten behandelt werden.

•Inkludieren Sie das OAuth 2.0-Token (in verschlüsselter Form) in dem auf FlowForce Server bereitgestellten Paket. Bei dieser Methode müssen Sie die OAuth 2.0-Anmeldeinformationen nicht während der Ausführung des Auftrag angeben, da das eingebettete Token verwendet wird. Der FlowForce-Auftrag kann solange ausgeführt werden, bis das Autorisierungs-Token abläuft oder der Autorisierungsserver es widerruft. Beachten Sie, dass Sie die OAuth 2.0-Autorisierungsinformationen jederzeit durch neue außer Kraft setzen können (siehe nächster Punkt).

•Inkludieren Sie das OAuth 2.0-Token nicht in dem auf FlowForce bereitgestellten Paket. In diesem Fall müssen Sie den Pfad zu einem OAuth 2.0-Anmeldedatensatz im Auftrag angeben, wenn Sie diesen konfigurieren. So können Sie zu diesem Zweck in FlowForce Server einen völlig neuen OAuth 2.0-Anmeldedatensatz erstellen oder von MapForce aus einen vorhandenen OAuth 2.0-Anmeldedatensatz auf FlowForce Server bereitstellen.

Um dies zu beschreiben, werden die OAuth 2.0-Anmeldeinformationen in diesem Tutorial nicht im bereitgestellten Paket inkludiert. Stattdessen werden wir diese separat bereitstellen und anschließend den FlowForce-Auftrag konfigurieren, der diese referenziert. Gehen Sie zu diesem Zweck folgendermaßen vor:

1.Klicken Sie in MapForce mit der rechten Maustaste in einen leeren Bereich des Mappings und wählen Sie den Befehl Anmeldeinformationen-Manager öffnen.

2.Doppelklicken Sie auf den Anmeldedatensatz (in diesem Beispiel "my.oauth") und deaktivieren Sie das Kontrollkästchen Verschlüsselt in MapForce Server-Ausführungsdatei und Mapping-Bereitstellung inkludieren.

3.Speichern Sie die Mapping-Design-Datei (.mfd).

Wir wollen das Mapping nun auf FlowForce Server bereitstellen:

1.Klicken Sie im Menü Datei auf Auf FlowForce Server bereitstellen.

2.Füllen Sie die entsprechenden FlowForce Server-Informationen aus und klicken Sie auf OK. Bei erfolgreicher Bereitstellung wird eine entsprechende Meldung im Fenster "Meldungen" angezeigt:

Separat dazu wollen wir nun die vorhandenen OAuth 2.0-Anmeldeinformationen ebenfalls bereitstellen:

1.Klicken Sie in MapForce mit der rechten Maustaste in einen leeren Bereich des Mappings und wählen Sie den Befehl Anmeldeinformationen-Manager öffnen.

2.Klicken Sie im Anmeldeinformationen-Manager mit der rechten Maustaste auf den Datensatz "my.oauth" und wählen Sie im Kontextmenü den Befehl Anmeldeinformationen auf FlowForce Server bereitstellen.

3.Füllen Sie die entsprechenden FlowForce Server-Informationen aus und klicken Sie auf OK. Bei erfolgreicher Bereitstellung wird eine entsprechende Meldung im Fenster "Meldungen" angezeigt:

Um die bereitgestellten Anmeldeinformationen anzuzeigen, melden Sie sich bei FlowForce Server an und öffnen Sie die Seite für die Anmeldeinformationen unter dem oben gezeigten Pfad.

Konfigurieren des FlowForce Server-Auftrags

In einem der vorherigen Schritte haben Sie das Mapping GetCalendarEvents.mfd in einer lokal ausgeführten FlowForce Server-Instanz bereitgestellt. In diesem Schritt werden Sie das bereitgestellte Mapping in einen FlowForce-Auftrag verwandeln. Der Auftrag wird in diesem Beispiel als Webservice aufgerufen, damit er jederzeit bei Bedarf ausgelöst werden kann.

1.Melden Sie sich bei FlowForce Server an und öffnen Sie das GetCalendarEvents.mapping aus dem Container "Public". Bereitgestellte Mappings werden in FlowForce Server zu Funktionen, daher die Terminologie auf der unten stehenden Benutzeroberfläche. Beachten Sie, dass die Funktion Anmeldeinformationen als Input-Parameter erwartet. Der Name der Anmeldeinformationen ist derselbe, den diese in MapForce erhalten haben, nämlich "my.oauth".

2.Klicken Sie auf Auftrag erstellen. Daraufhin wird die Auftragskonfigurationsseite geöffnet.

3.Klicken Sie unter "Auftrags-Input-Parameter" auf und erstellen Sie einen neuen Parameter namens calendarId mit dem Standardwert en.usa#holiday@group.v.calendar.google.com (alternativ dazu können Sie als Standardwert primary, denselben Wert, der in der vorherigen Ausführung verwendet wurde, eingeben).

4.Suchen Sie unter "Ausführungsschritte" den Parameter calendarId, klicken Sie auf "Setzen auf" und wählen Sie calendarId aus.

5.Klicken Sie für den Parameter my.oauth auf die Schaltfläche , klicken Sie auf Anmeldeinformationen auswählen und navigieren Sie zu den zuvor bereitgestellten OAuth 2.0-Anmeldeinformationen. Sie finden diese im Container public, wenn Sie die Standardeinstellungen bei der Bereitstellung nicht geändert haben:

6.Aktivieren Sie unter "Dienst" das Kontrollkästchen Diesen Auftrag über HTTP...zur Verfügung stellen und geben Sie den Namen des Diensts ein (in diesem Beispiel "GetCalendarEvents").

7.Wählen Sie unter "Anmeldeinformationen" Lokale Anmeldeinformationen definieren aus und geben Sie die Anmeldeinformationen für Ihr Betriebssystem ein. Beachten Sie, dass diese nicht dieselben sind, wie die Anmeldeinformationen für Ihr FlowForce Server-Konto und dass Sie diese benötigen, um den Auftrag ausführen zu können.

8.Belassen Sie alle anderen Einstellungen unverändert und speichern Sie den Auftrag.

Sie können den Auftrag nun folgendermaßen ausführen:

1.Klicken Sie unter "Dienst" auf die Schaltfläche Auftrags-URL in neuem Fenster starten.

2.Wenn Sie nach den Anmeldeinformationen gefragt werden, geben Sie die Anmeldeinformationen für Ihr FlowForce Server-Konto ein.

Bei erfolgreicher Ausführung und OAuth 2.0-Autorisierung wird im Browser die von der Google Calender API retournierte JSON Antwort angezeigt, z.B:

Im oben gezeigten Webservice-Aufruf wurde der Standardwert von calendarId verwendet. Optional können Sie einen Input-Parameter zur URL hinzufügen, z.B: http://localhost:4646/service/GetCalendarEvents?calendarId=primary. Bei Aufruf des Webservice würden nun für die als Parameter angegebene Kalender-ID Daten aus der Google Calender API abgerufen.

In diesem Beispiel wurde der calendarId-Parameter über eine HTTP GET-Methode bereitgestellt, da Sie den Webservice direkt über den Browser aufrufen. Wenn Sie einen Webservice programmatisch aufrufen, kann auch eine HTTP POST-Methode verwendet werden. Nähere Informationen dazu finden Sie unter Bereitstellen von Aufträgen als Web-Dienste.