REST Services und Application Express 5.1 - Teil 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

Im ersten Teil des Artikels wurde vorgestellt, wie man mit dem REST Client Assistant PL/SQL und SQL Code erzeugen kann, so dass die Daten des REST Service in einer Application Express-Anwendung dargestellt oder verarbeitet werden können. In diesem Artikel machen wir den nächsten Schritt: Viele REST-Services liefern große Ergebnismengen nicht komplett, sondern seitenweise aus.

Ein Beispiel für einen REST Service, der mit größeren Datenmengen arbeitet, lässt sich schnell in der eigenen Umgebung erstellen. Sie brauchen dazu lediglich eine Tabelle mit mehr als den 14 Zeilen, wie sie die wohlbekannte EMP Tabelle enthält. Einige hundert sollten es schon sein. Im Zweifelsfalle generieren Sie sich einfach eine solche.

Den REST Service stellen Sie dann mit Hilfe von Oracle REST Data Services (ORDS) bereit. Aber Achtung: Wir brauchen dazu die Version 3.0 oder höher (die aktuellste Version ist - Stand Mai 2017 - ORDS 3.0.9). Arbeiten Sie bitte nicht mehr mit den alten ORDS 2.x Versionen.

Erzeugen Sie dann einen REST Service für Ihre größere Tabelle. Nehmen Sie hierfür bitte ebenfalls nicht den Bereich RESTful Services im Application Express SQL Workshop - denn dieser beschränkt Ihre REST Services auf die Fähigkeiten von ORDS 2.0. Um den vollen Funktionsumfang von ORDS 3.0 nutzen zu können, sollte man das PL/SQL Paket ORDS verwenden - und das geht am besten mit einem Skript - was man im SQL Workshop dann immer wieder laufen lassen kann. Mit den folgenden Kommandos werden REST Services zuerst grundsätzlich für das Datenbankschema aktiviert, danach wird die REST API für eine Tabelle erzeugt (passen Sie die Platzhalter an Ihre Umgebung an).

begin
    ords.enable_schema(
        p_enabled        => true,
        p_schema         => '{schema-name}',
        p_auto_rest_auth => false );
    
    ords.enable_object(
        p_enabled        => true,
        p_schema         => '{schema-name}',
        p_object         => '{table-name}',
        p_object_type    => 'TABLE',
        p_object_alias   => 'my-rest-table',
        p_auto_rest_auth => false );
end;
/

commit
/

Unmittelbar nach dem Ausführen des Commit ist die REST-Schnittstelle für die Tabelle verfügbar; Sie können diese schon im Browser testen.

http://{server}:{port}/ords/{schema-name}/my-rest-table

Das Bild sollte in etwa wie folgt aussehen - die konkret sichtbaren Daten hängen natürlich von Ihrer Tabelle ab.

Abbildung 3: Erster Test der neuen REST-Schnittstelle auf eine Oracle-Tabelle

Das unterscheidet sich auf den ersten Blick nicht besonders vom "Earthquake"-Beispiel, welches im ersten Teil verwendet wurde. Interessant wird es aber, wenn man zum Ende des JSON-Feeds herunterscrollt.

Abbildung 4: Der REST Service liefert Daten seitenweise aus.

Wie man sehen kann, werden nur 25 Zeilen zurückgeliefert - um weitere Daten zu bekommen, muss man einen erneuten HTTP-Request durchführen. Praktischerweise ist die URL, die man für die nächste Seite aufrufen muss, auch schon in der REST-Antwort enthalten - im Attribut links[rel=next]. Auf diese Information ist man jedoch nicht zwingend angewiesen - schaut man sich den URL genauer an, sieht man schnell, dass die Seite mit den URL-Parametern offset und limit angesteuert wird.

http://{server}:{port}/ords/{schema-name}/my-rest-table?offset=100&limit=50
http://{server}:{port}/ords/{schema-name}/my-rest-table?limit=500

So ist es möglich, den URL selbst zusammenzusetzen und die Seitengröße so selbst zu bestimmen. Allerdings setzt der Server dabei Grenzen - standardmäßig sind 500 Zeilen die maximale Seitengröße. Grund dafür ist schlicht die Skalierbarkeit - um große Seiten mit vielen JSON-Daten ausliefern zu können, braucht es Ressourcen. Limitiert man die Seitengröße, so kann eine ORDS Instanz viele Anfragen bedienen, ohne dass es zu Engpässen kommt.

Die Tatsache, dass große Datenmengen seitenweise ausgeliefert werden, hat Konsequenzen, wenn man an das Einbinden des REST-Service in eine Application Express-Anwendung denkt. Stellt man die Daten als Bericht dar (wie im ersten Teil des Artikels geschehen), so bietet APEX standardmäßig eine Pagination an. Allerdings bezieht diese sich auf die dem Bericht zugrundeliegende SQL-Abfrage; man würde also nur innerhalb einer vom REST Service ausgelieferten Seite blättern - was wenig sinnvoll ist.

Das Blättern in einem solchen Bericht muss anders vor sich gehen. Navigiert der Endbenutzer auf die nächste Seite, so muss der REST Service erneut aufgerufen werden - die URL enthält dann andere Werte für die Parameter limit und offset, so dass die jeweils nächste oder vorherige Seite ausgeliefert wird.

Dass die URL-Parameter limit und offset das Abfragefenster für den REST Service festlegen, ist spezifisch für Oracle REST Services: In der Oracle Produktentwicklung gibt es einen REST Standard; alle Entwickler folgen diesem; daher funktionieren REST Services von Oracle in dieser Hinsicht stets gleich. Man kann sich also durch die Ergebnismenge eines ORDS Service genauso durchblättern wie durch die eines Oracle SaaS REST Service (zum Beispiel Oracle Sales Cloud).

REST Services anderer Anbieter funktionieren anders. Anstelle von limit oder offset werden u.U. andere Parameter verwendet; denkbar wäre auch, dass diese Werte als HTTP-Header oder auf andere Art und Weise übergeben werden. Um mit einem solchen REST Service arbeiten zu können, muss man wissen, wie er funktioniert; die Kenntnis, dass man mit einem REST Service arbeitet, reicht noch nicht aus.

Die Packaged Application REST Client Assistant unterstützt die Pagination, wenn es sich um einen Oracle REST Service handelt. Erkannt wird sowohl das Pagination-Schema von ORDS 3.0 als auch das von ORDS 2.0, auch wenn letzteres nicht dem Oracle REST Standard folgt. Das können Sie einfach testen. Starten Sie dazu nochmals den REST Client Assistant und erzeugen Sie eine neue REST Service Reference. Als Endpoint URL nehmen Sie die URL, mit der Sie ihren REST-Service auch schon im Browser getestet haben.

Abbildung 5: REST Client Assistant: REST Service Reference erzeugen

Nach dem Erzeugen der Reference können Sie wiederum auf dem Reiter REST Data testen, ob REST Client Assistant die Daten verarbeiten kann.

Abbildung 6: REST Client Assistant: Antwort des REST Service ansehen

Klickt man im Datenfenster oben rechts auf den Pfeil, so öffnet sich wiederum ein Dialog, der alle Daten zeigt. Im Gegensatz zum Earthquake-Beispiel aus dem ersten Teil des Artikels enthält dieser Dialog zusätzlich Schaltflächen, mit denen man vor- und zurückblättern kann. REST Client Assistant sorgt dafür, dass die angefragte Seite vor der Darstellung vom REST Service abgerufen wird.

Abbildung 7: Blättern in der Ergebnismenge des REST Service

Öffnet man den Reiter PL/SQL Code on Page Load supporting Pagination, so sieht man wiederum generierten PL/SQL-Code, der in eine eigene APEX-Anwendung übernommen werden kann. Allerdings reicht einfaches Copy & Paste nun nicht mehr aus, es braucht etwas mehr ...

Abbildung 8: Generierter PL/SQL Code für die eigene APEX-Anwendung: Mit Pagination Support

Erzeugen Sie also eine neue, leere Anwendung mit einer neuen Seite. Dann führen Sie folgende Schritte aus (ganz wie in den Kommentaren zu Beginn des generierten Code beschrieben):

• Zuerst erzeugen Sie, wie Sie es schon im ersten Teil des Artikels getan haben, einen klassischen Bericht mit der generierten SQL-Abfrage im Reiter SQL Query (Region Source).
• Erzeugen Sie dann drei Seitenelemente vom Typ "Hidden". Die Kommentare des generierten PL/SQL Codes enthalten einen Tipp für das Namensschema. Das Item {APEX_ITEM_URL_NEXT_PAGE} legen Sie auf Seite 1 als P1_URL_NEXT_PAGE an; die anderen beiden analog.
• Machen Sie im generierten Code dann ein Find & Replace. Tauschen Sie die Platzhalter {APEX_ITEM_...} (erkennbar an den geschweiften Klammern) durch die tatsächlichen Namen der Seitenelemente aus. Erzeugen Sie mit diesem Code dann einen neuen PL/SQL Prozess, der beim Laden der Seite - vor dem Header ausgeführt wird.
• Dann legen Sie, wie beschrieben, einen Button zum Vor- und einen zum Zurückblättern an. Die Buttons führen einen Redirect auf die gleiche Seite durch, wie im Kommentar beschrieben: Der Button zum Zurückblättern setzt P1_SHOW_PAGE auf prev, der zum Vorblättern setzt es auf next.
• Der Button zum Zurückblättern soll auf der ersten Seite natürlich nicht angezeigt werden; dazu dient die im Kommentar erwähnte Bedingung (Condition). Der Button zum Vorblättern darf auf der letzten Seite nicht mehr gezeigt werden; auch dies wird per Bedingung sichergestellt.

Wenn Sie all dies getan haben, sollte Ihre Anwendungsseite in etwa wie in der folgenden Abbildung aussehen. Interessant ist, dass die Berichts-Pagination nun mit "externen" Schaltflächen erfolgt - die im Bericht eingebaute Pagination kann hier nicht verwendet werden. Allerdings können Sie sich nun - in einem APEX-Bericht - durch die Ergebnisseiten eines REST-Service durchblättern.

Abbildung 9: Application Express Report auf einen REST Service: Mit Pagination

Der REST Client Assistant bietet noch mehr - so ist es denkbar, dass die gesamte Ergebnismenge, also alle Zeilen auf allen Seiten abgerufen werden sollen. Es braucht also eine SQL- oder PL/SQL Funktion, die sich durch alle Seiten durcharbeitet und alle Zeilen zurückliefert. Der REST Client Assistant kann eine solche generieren. Klicken Sie im Menü auf der rechten Seite den Eintrag Load Data.

Abbildung 10: REST Client Assistant: Load Data

Wählen Sie Table Function, vergeben Sie einen Namen für die zu generierende Funktion und klicken Sie auf Generate Code.

Abbildung 11: REST Client Assistant: Generierte Table Function

Spielen Sie die Table Function in einem Datenbankschema ein und testen Sie sie - Sie können nun alle Daten des REST Service mit einer einzigen SQL-Abfrage abrufen.

Abbildung 12: Alle Daten von einem REST Service abrufen mit SQL: Table Function im Einsatz

Die Table Function macht genau das, was Sie als Endanwender in der APEX-Anwendung machen würden: Es arbeitet sich Seite für Seite durch die Antwort des REST Service. Natürlich finden im Hintergrund einige HTTP-Anfragen statt - bei extrem großen Datenmengen sollte man sich das gut überlegen.

Experimentieren Sie ein wenig damit. Die Möglichkeiten zur Integration zwischen APEX und einem REST Service sind allerdings noch lange nicht zu Ende - im nächsten Teil stellen wir vor, wie man einen Abfragefilter zum REST Service sendet und so von vorneherein nur eine Teilmenge der Daten abrufen kann.

zurück zur Community-Seite