REST Services und Application Express 5.1 - Teil I

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.

SQL> select title, mag from table("USGS_EQ_TABFUNC"());

TITLE                                                       MAG    
----------------------------------------------------------- ------
M 1.8 - 32km ENE of Fritz Creek, Alaska                     1.8    
M 0.9 - 5km NW of Glen Avon, CA                             0.89   
M 2.3 - 5km WSW of Volcano, Hawaii                          2.26   
M 1.5 - 52km WSW of Anchor Point, Alaska                    1.5    
M 4.8 - 134km ESE of Pondaguitan, Philippines               4.8    
M -0.3 - 59km N of Pahrump, Nevada                          -0.3   
M 0.8 - 10km ENE of Cloverdale, California                  0.78   
M 4.5 - Sea of Japan                                        4.5    
M 1.7 - 31km WNW of Ester, Alaska                           1.7    
M 1.3 - 52km WNW of Willow, Alaska                          1.3    
:

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