REST Services und Application Express 5.1 - Teil I
Erscheinungsmonat |
APEX-Version |
Datenbankversion |
April 2017 |
ab 5.1 |
ab 11.2 |
Die Anforderung, mit REST Services zu arbeiten, haben auch Application Express-Entwickler mehr und
mehr auf dem Schreibtisch. Zwar können Web Service Referenzen
für REST Services in den Gemeinsamen Komponenten eingerichtet
werden; die Unterstützung ist jedoch recht limitiert: So muss die JSON-Antwort, die der
REST Service sendet, typischerweise manuell geparst und verarbeitet werden.
Allerdings bringt Application Express 5.1 zwei neue Packaged Applications für REST Services mit:
- REST Client Assistant:
Abbildung 1: Packaged Application REST Client Assistant
- Sample REST Services:
Abbildung 2: Packaged Application REST Client Assistant
Sample REST Services zeigt beispielhaft eine Anwendung, die mit einem REST Service, anstelle einer
Tabelle, arbeitet. Der Bericht selektiert keine Tabelle, sondern zeigt die Daten des REST Service an.
Das Formular führt keine SQL DML-Anweisungen
aus, um die Änderungen zu speichern, es sendet hierfür vielmehr HTTP-Requests zum REST Service.
Schaut
man in die Anwendung hinein, so findet sich an einigen Stellen PL/SQL und SQL-Code zum Aufrufen der
REST Services oder zur Verarbeitung des JSON-Formats. Dieser Code wurde mit Hilfe der Anwendung
REST Client Assistant generiert - und genau deshalb ist der REST Client Assistant auch die
interessantere der beiden Anwendungen: Sie erlaubt es, den PL/SQL und SQL-Code, den man zum Ansprechen
eines REST-Service braucht, zu generieren. Wenn Sie es also noch nicht getan haben, installieren Sie
den REST Client Assistant in Ihrem Workspace und starten Sie die Anwendung.
Abbildung 3: Erster Start des REST Client Assistant
Beim ersten Start zeigt Ihnen die Anwendung an, welche Voraussetungen erfüllt sein müssen, damit man
damit arbeiten kann. REST Services aufrufen bedeutet, HTTP-Requests auszuführen: Der REST Service
muss für Application Express also über das Netzwerk erreichbar sein.
- Der Datenbankserver muss grundsätzlich in der Lage sein, die Netzwerkverbindung zum REST-Service
aufzubauen.
- Eine Netzwerk-ACL muss, mit dem PL/SQL Paket DBMS_NETWORK_ACL_ADMIN, für die Application Express-Engine (User APEX_050100) eingerichtet werden, so
dass die HTTP-Verbindung möglich wird. Hierzu braucht es ggfs. den Datenbankadministrator.
- Wenn der REST-Service sich, aus Sicht der Datenbank, hinter der Firewall befindet, muss ein
Proxy-Server gesetzt werden. Das kann in der Anwendung selbst (Administration) geschehen.
- Wenn Sie REST-Services über HTTPS ansprechen möchten, kann es sein, dass ein Wallet für die Datenbank eingerichtet
und in Application Express (Workspace INTERNAL, Instance Settings) konfiguriert werden muss.
Klicken Sie auf Continue, wenn diese Anforderungen verstanden und erfüllt sind. Sie werden zur Homepage
des REST Client Assistant geleitet. Zu Beginn ist die Anwendung noch leer. Klicken Sie auf
Add REST Service Reference, um mit einem REST Service zu arbeiten.
Abbildung 4: Homepage des REST Client Assistant
Um mit dem REST Service arbeiten zu können, sollte dieser seine Daten in einer "Tabellen-ähnlichen"
Struktur zurückgeben. Das bedeutet, dass die JSON-Antwort wenigstens ein Array mit den
einzelnen Objekten als Array-Elemente enthält. Application Express wird das Array dann als
Tabelle, die Array-Elemente als Zeilen und die einzelnen JSON-Attribute als Spalten auffassen. Viele
REST-Services liefern genau diese Struktur aus.
Als erstes wollen wir mit einem sehr einfachen Service arbeiten - die
GeoJSON Datafeeds des USGS sind
eigentlich gar keine REST Services, sondern einfache HTTP-Feeds. Dennoch lässt sich der
REST Client Assistant sehr schön anwenden. Nehmen Sie am besten den Feed, der alle
Erdbeben des vergangenen Tages enthält:
https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson.
Abbildung 5: REST Service Referenz im REST Client Assistant anlegen
Der REST Client Assistant wird die HTTP-URL aufrufen und die JSON-Antwort anzeigen. Das oben
beschriebene Array, welches als Äquivalent zur Tabelle dienen soll, ist im JSON-Attribut
features enthalten. Jedes Array-Element repräsentiert ein Erdbeben.
Tragen Sie als Row Selector
also features ein, stellen Sie sicher, dass
JSON als Response Format
eingestellt ist, und klicken Sie auf Add Service Reference.
Abbildung 6: "features" als "Row Selector" eintragen und Service-Referenz anlegen
Der REST Client Assistant ermittelt dann die einzelnen Attribute der Array-Elemente, also die Äquivalente
zu den Tabellenspalten, und deren Datentypen. Im dann folgenden Dialog bekommen
Sie diese angezeigt - Sie können den Vorschlag akzeptieren oder Änderungen vornehmen. In den
meisten Fällen wird man die Attribute, die man nicht braucht, entfernen. Sie können jedoch
auch zusätzliche hinzufügen oder Spaltennamen ändern. Klicken Sie auf
Save and Finish, um das Erstellen der REST Service Referenz abzuschließen.
Abbildung 7: Vom REST Client Assistant ermittelte JSON-Attribute
Sie werden auf die Homepage zurückverwiesen. Dort befindet sich nun ein Eintrag mit der neuen
REST Service Referenz. Klicken Sie darauf.
Abbildung 8: Homepage des REST Client Assistant mit der neuen REST Service Referenz
Nun bekommen Sie einen ersten Eindruck von dem, was der REST-Client Assistant für Sie tun kann.
Die Abschnitte PL/SQL Code (on Page Load) und
SQL Query (region source) zeigen Ihnen bereits die Code-Fragmente, die Sie brauchen, wenn Sie
die Daten des REST Service in einem Bericht in Ihrer Anwendung darstellen wollen.
Abbildung 9: Generierter SQL und PL/SQL Code zur Nutzung der neuen REST Service Referenz
Doch zuerst sollte
gerüft werden, ob die Daten wirklich korrekt angezeigt werden. Klicken Sie auf den
Reiter REST Data, und dann auf den Button
Fetch REST Service Data. Sie sehen die ersten vier Spalten der ersten fünf Zeilen. Um alle Daten zu sehen,
klicken Sie das "Expand" Symbol oben rechts in der Region.
Abbildung 10: Vom REST Service zurückgelieferte Daten betrachten
Wenn Sie soweit zufrieden sind, können Sie den generierten Code in Ihrer eigenen Anwendung
einsetzen: Erzeugen Sie eine neue, leere Anwendung mit einer leeren Seite. Wenn Sie
im REST Client Assistant einen Proxy-Server eingetragen haben, tragen Sie diesen auch
in Ihrer Anwendung bei den Gemeinsamen Komponenten in den
Application Definition Attributes ein.
Navigieren Sie dann zu Ihrer Anwendungseite und erzeugen Sie einen neuen Prozess, der im Bereich
Pre-Rendering ausgeführt werden soll. Kopieren Sie den PL/SQL-Code aus dem Reiter
PL/SQL Code (on Page Load) des REST Client Assistant.
Abbildung 11: Einen neuen PL/SQL Prozess mit dem Code des REST Client Assistant erzeugen
Erzeugen Sie dann eine Berichtsregion. Nehmen Sie am besten einen klassischen Bericht - und kopieren
Sie die SQL Abfrage des Reiters SQL Query (region source) des REST Client Assistant. Wenn die
SQL-Query zu viele Spalten zurückliefert, weil Sie beim Erstellen der REST Service Referenz alle
Attribute akzeptiert haben, können Sie die eine oder andere ruhig entfernen.
Abbildung 12: Eine Berichtsregion zur Anzeige der Daten des REST Service erstellen
Speichern Sie die Änderungen ab und starten Sie die Anwendung. Sie sollte in etwa wie folgt aussehen.
Abbildung 13: Die Daten eines REST Service - dargestellt in einem APEX-Bericht
Nun können Sie den Bericht formatieren, bis Sie mit dem Aussehen zufrieden sind. Natürlich kommen
auch andere Komponenten in Betracht. Wenn eine Datums-Komponente enthalten ist, können Sie mit
der gleichen SQL-Query auch eine Kalender-Region erzeugen. Charts sind ebenfalls unproblematisch - denn
die vom REST Client Assistant generierte SQL-Abfrage übersetzt die JSON-Antwort des REST-Service in
die für APEX erforderliche Tabellen-Struktur mit Zeilen und Spalten. Schauen wir uns nun noch einige
weitere Funktionen des REST Client Assistant an.
Öffnen Sie das rechte Menü auf der Detail-Seite zur REST Service Referenz durch Klick auf das
Menü-Icon oben rechts. Sie sehen verschiedene Aktionen, die der REST Client Assistant mit
dieser REST Service Referenz erlaubt.
Abbildung 14: REST Client Assistant: Mögliche Aktionen mit einer REST Service Referenz
Am interessantesten dürfte der Bereich Load Data sein. Hier bietet der REST Client Assistant verschiedene
Möglichkeiten an, die Daten des REST Service nicht nur anzuzeigen, sondern in eine Tabelle zu laden
oder mit SQL oder PL/SQL zu verarbeiten.
Abbildung 15: Daten mit dem REST Client Assistant in die lokale Datenbank laden.
Wählt man Load Data Now, so werden die Daten sofort in eine Tabelle geladen. Diese Tabelle liegt
im gleichen Schema, in dem auch die Tabellen des REST Client Assistant liegen. Interessanter
dürften die Varianten Generate PL/SQL block oder
Generate Table Function sein. Die Table Function
bietet sicherlich die größte Flexibilität - und sie ist besonders interessant, wenn man sie mit
REST Services verwendet, deren Ergebnisse seitenweise abgerufen werden müssen (Pagination).
Probieren Sie das einmal aus: Wählen Sie einen Namen
für die Table Function und klicken Sie auf Generate Code.
Abbildung 16: Eine vom REST Client Assitant generierte Table Function
Spielen Sie den generierten Code in das gewünschte Datenbankschema ein.
Schaut man sich den vom REST Client Assistant generierten SQL und PL/SQL Code etwas genauer
an, so sieht man, dass das JSON-Parsing mit SQL-Funktionen der Datenbank erfolgt. Welche genau
eingesetzt werden, hängt davon ab, auf welcher Datenbank der REST Client Assistant läuft. Auf
einer 11g-Datenbank wird das JSON zuerst mit dem Paket APEX_JSON in XML umgewandelt; das XML-Parsing
erfolgt dann mit der SQL-Funktion XMLTABLE.
Auf einer 12c-Datenbank (ab 12.1.0.2) wird die JSON_TABLE-Funktion
eingesetzt.
Es empfiehlt sich, den REST Client Assistant immer auf der Datenbankversion zu betreiben, auf der
auch die Anwendungen laufen, in denen man das generierte SQL und PL/SQL nutzen möchte. Wenn der REST
Client Assistant auf einer 12c-Datenbank läuft, können Sie auch erzwingen, dass Code für eine
11g-Datenbank generiert wird. Navigieren Sie dazu in den Bereich Administration
des REST Client Assistant.
Abbildung 17: Administrationsbereich des REST Client Assistant
Im Bereich Configure Oracle12c JSON Functions können Sie einstellen, ob die Oracle12c JSON-Funktionen
genutzt werden sollen - logischerweise nur dann, wenn der REST Client Assistant auf einer 12c-Datenbank
läuft. Diese Frage sollte eigentlich immer mit Ja beantwortet werden, es sei denn, sie müssen gezielt
SQL und PL/SQL-Code für eine 11g-Datenbank erzeugen.
Abbildung 18: Sollen die Oracle12c SQL/JSON-Funktionen genutzt werden?
Als Packaged Application ist der REST Client Assistant nach Installation gesperrt; Sie können ihn
also zunächst nur starten. Wie alle anderen Packaged Applications kann jedoch auch der REST Client
Assistant entsperrt werden - dann können Sie sich die Implementierung ansehen und bei Bedarf auch
ändern. Allerdings verliegen Sie mit dem Entsperren den Support für diese Anwendung
und die Möglichkeit, den REST Client Assistant künftig auf neue Releases zu aktualisieren.
Schauen Sie sich den REST Client Assistant einmal näher an und experimentieren Sie ein wenig damit.
Im nächsten Teil stellen wir vor, wie man mit dem REST Client Assistant auch POST, PUT oder DELETE
Requests ausführen kann und wie man REST Services anspricht, deren Ergebnisse seitenweise zurückgeliefert
werden.
zurück zur Community-Seite
|