Der Oracle BI Publisher verfügt seit vielen Jahren über ein sehr leistungsfähiges Web Service API auf der Basis von SOAP. Ich habe zusammen mit Kollegen mehrere White Paper geschrieben, die die Integration dieser Web Services in Oracle Forms und in Oracle ADF beinhalten.
Noch vor einiger Zeit bekam ich auf meine Frage nach einem REST Service API die Antwort, dass es keine Planung dafür gäbe. Umso größer war die Überraschung, dass mit dem Release 12c des BI Publisher eine REST Service-Schnittstelle veröffentlich wurde. Natürlich war die Neugier groß, das API zu testen.
Die Dokumentation ist knapp gehalten und enthält einige kleinere Fehler, die allerdings etwas zur Verwirrung beitragen. Die in der Dokumentation verwendeten Beispiele benutzen das Kommandozeilen-Werkzeug curl. Da ich mich in der Vergangenheit mit dem Postman, einer grafischen Umgebung zum Testen von REST Services angefreundet habe, wollte ich den Test mit diesem Werkzeug durchführen.
Es folgt eine kurze Beschreibung der notwendigen Schritte.
Um die REST Services nutzen zu können, muss der BI Publisher Server gestartet sein. Für die Aurufe stehen folgende HTTP-Methoden zur Verfügung.
| GET | Informationen über eine Oracle BI Publisher Ressource erhalten |
| POST | Anlegen einer BI Publisher Ressource, Informationen über eine Oracle BI Publisher Ressource erhalten |
| PUT | Aktualisieren einer BI Publisher Ressource |
| DELETE | Löschen einer BI Publisher Ressource |
Wir beginnen zunächst mit dem GET-Aufruf einer Reports-Ressource aus dem Verzeichnis Samples des BI Publisher Repository.
Die URL für einen Bericht lautet:
http://<hostname>:9502/xmlpserver/services/rest/v1/reports/Samples%2F2.%20Features%2FLast%20Page%20Handling%2FTelecom%20Bill
Zu beachten sind die Sonderzeichen %20 für ein Leerzeichen und %2F für den Forward Slash (beginnend erst ab dem Shared Folder !!).
Zusätzlich müssen wir im Postman zwei Header Variablen definieren:
Accept = application/json
Content-Type = application/json
Für die erfolgreiche Ausführung ist eine Authentifizierung beim BI Publisher Server erforderlich. Dazu wählen wir im Reiter Authorization den Typ Basic Authentication aus und tragen sowohl den User als auch das Passwort eines berechtigten Benutzers ein. Postman erzeugt daraus ein Token und fügt es automatisch als dritte Header-Variable hinzu.
Schicken wir diesen Request als GET ab, erhalten wir in einer JSON-Struktur detaillierte Informationen (Metadaten) über den Bericht „Last Page Handling Telecom Bill“.
Wollen wir diesen Bericht per REST Call ausführen, wird es komplizierter, denn wir müssen dem Aufruf zahlreiche Parameter mitgeben. Dazu verwenden wir die POST-Methode und übergeben beim Request eine JSON-Struktur mit allen erforderlichen Angaben, analog dem Formular einer Webseite.
Die URL für den POST ist leicht abgewandelt und lautet jetzt:
http://<hostname>:9502/xmlpserver/services/rest/v1/reports/Samples%2F2.%20Features%2FLast%20Page%20Handling%2FTelecom%20Bill/run
Auch die beiden Header Variablen müssen geändert werden:
Accept =multipart/form-data
Content-Type =multipart/form-data; boundary=“Boundary_1_1153447573_1465550731355″
Die Authentifizierung bleibt unverändert.
Zusätzlich muss beim POST die zu übergebende JSON-Struktur definiert werden. Sie enthält die notwendigen Parameter des Berichts und verwendet die im Content-Type angegebene Begrenzung (boundary).
Für unseren Bericht sieht diese Struktur folgendermaßen aus:
–Boundary_1_1153447573_1465550731355
Content-Type: application/json
Content-Disposition: form-data; name=“ReportRequest“
{
„byPassCache“:true,
„flattenXML“:false,
„attributeFormat“:“pdf“,
„attributeTemplate“:“Telecom Bill Layout“
}
–Boundary_1_1153447573_1465550731355–
Sind alle diese Angaben fehlerfrei, bekommen wir beim Aufruf über die Send-Funktion des Werkzeugs den HTTP-Statuscode 200 und eine PDF-Datei als Datenstrom zurück.
POST-Methode zum Aufruf eines BI Publisher Reports
Verwenden wir statt Send die Funktion Send and Download wird der Datenstrom heruntergeladen und mit einem PDF Viewer angezeigt.
Ein Vorteil des Werkzeugs Postman besteht darin, dass man die getesteten Aufrufe in einer Collection für die spätere Verwendung oder den Austausch über Export/Import abspeichern kann.
Jürgen Menge (Der IT-Macher)