Herzlich Willkommen zu unserem neuen Newsletter. Heute zeigen wir Ihnen, wie Sie KeepTool 16 zur Konfiguration und zum Test von Oracle REST-Datenservices (ORDS) verwenden können.
REST ist eine Abkürzung für Representational State Transfer. Es handelt sich um ein zustandsloses, cachefähiges Client/Server-Kommunikationsprotokoll, das meist auf HTTP(S) basiert. ORDS ist hochgradig skalierbar. Es verwendet HTTP(S)-Methoden wie POST, PUT, GET, DELETE, um CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) zu implementieren.
ORDS ist die API von Oracle, die es Ihnen ermöglicht, Ihre Daten als RESTful-Datenservices bereitzustellen. Es handelt sich um eine Mid-Tier-Java-Anwendung, die HTTP(S)-Verben (GET, PUT, POST, DELETE, …) auf Datenbanktransaktionen abbildet. Die Ergebnisse werden als formatiertes JSON zurückgegeben.
ORDS wird hauptsächlich verwendet für
ORDS benutzt einen URL mit folgender Syntax:
http(s)://hostname:8080/ords/orcl/hr/module/template/:id
und besteht aus den folgenden Elementen:
Entdecken Sie die Möglichkeiten von KeepTool.
Sie können die neueste ORDS-Version von https://download.oracle.com/otn_software/java/ords/ords-latest.zip herunterladen.
Alle Installations- und Konfigurationsschritte sind im Kapitel Installing and Configuring Oracle REST Data Services des Oracle REST Data Services Installation and Configuration Guide beschrieben.
Im params-Verzeichnis Ihres ORDS-Homes finden Sie die Datei
ords_params.properties
mit der Sie vor der Installation die entsprechenden ORDS Parameter konfigurieren können. Für unsere Demo haben wir die Standardeinstellungen verwendet.
ORDS kann auf WebLogic oder Tomcat-Servern deployed oder im Standalone-Modus ausgeführt werden. Dieser Artikel beschreibt die Installation im Standalone-Modus.
Während des Installationsprozesses werden Sie aufgefordert, einen ORDS-Administrationsbenutzer anzugeben. Sie können entweder einen neuen Benutzer anlegen oder einen bestehenden Benutzer wie PDBADMIN verwenden.
Neben der ORDS-Anwendung legt der Installer zwei neue Datenbankschemas ORDS_METADATA und ORDS_PUBLIC_USER an. Die PL/SQL-Objekte, Views und Tabellen des Schemas ORDS_METADATA stellen die Logik zur Einrichtung von ORDS bereit. Die neuen ORDS-Dialoge von Hora bauen ebenfalls mit ihrer Benutzeroberfläche darauf auf.
Stellen Sie sicher, dass das Verzeichnis ORDS\bin zur PATH-Variable hinzugefügt wurde. Dann können Sie den ORDS-Server mit folgendem Befehl starten:
ords --config ${ORDS_CONFIG} serve
Sie finden die ORDS-Seite von Hora in der Gruppe “Additional”. Zunächst wollen wir die globale Tabellendarstellung “ORDS Schema” betrachten. Sie finden diese im unteren Teil der Seite. Diese Übersicht bleibt übergreifend für die meisten ORDS-Registerkarten sichtbar.
ORDS-Administratoren können damit ORDS-Schemata verwalten sowie zwischen mehreren ORDS-Schemen navigieren.
Für einen normalen Benutzer zeigt die Tabellendarstellung nur das aktuelle Schema an.
Die beiden Checkboxen rechts neben der Überschrift ORDS-Schema zeigen an, ob für die aktuelle Session die ORDS_ADMINISTRATOR_ROLE bzw. die ORDS_RUNTIME_ROLE aktiv ist.
Um mit ORDS zu arbeiten, muss für das entsprechende Datenbankschema ORDS zunächst freigeschaltet werden. Vergewissern Sie sich, dass Sie ORDS-Administrationsrechte haben. In unserem Fall sind wir als PDBADMIN angemeldet. Klicken Sie mit der rechten Maustaste auf die ORDS-Tabellendarstellung und wählen Sie den Menüpunkt “Enable Schema”. Damit öffnet sich ein modaler Dialog zum Aktivieren des Schemas.
Wir wählen in der Kombobox das HR-Demoschema (Human resources) und verwenden als URI-Pattern den Standard, d.h. den Schemanamen in Kleinbuchstaben. Nachdem Sie mit OK bestätigt haben, wird das HR-Schema in der Tabellendarstellung aufgelistet.
Da wir als ORDS-Admin-Benutzer verbunden sind, können wir mehrere Schemas in der Tabellendarstellung sehen. Wir können zu einem anderen Schema navigieren. Alle anderen Seiten wie z.B. ORDS-Module zeigen dann genau die ORDS-Objekte an, die zu dem ausgewählten Schema gehören. Wenn Sie ORDS-Objekte auch bearbeiten möchten, empfehlen wir Ihnen unbedingt, sich als der entsprechende ORDS-Benutzer zu verbinden.
Wir sind jetzt wieder als HR verbunden, wie Sie in der Hardcopy unten sehen können. Übrigens, in diesem Beispiel haben wir die Schaltfläche ORDS / REST in den Abschnitt “Favoriten” des Hauptmenüs aufgenommen, um einen schnelleren Zugriff zu ermöglichen.
Das Tabellendarstelung ORDS-Schema zeigt unten genau einen Datensatz für HR, da HR für ORDS aktiviert wurde und wir kein ORDS-Administrator-Benutzer mehr sind.
Zu Beginn zeigt die Seite ORDS-Module keine Daten an. Klicken Sie mit der rechten Maustaste und wählen Sie den Menüpunkt “Modul erstellen”. Daraufhin öffnet sich ein modaler Dialog zum Erstellen eines neuen Moduls:
Wählen Sie einen Modulnamen und einen URI-Basispfad. Letzterer wird auch URI-Präfix genannt und sollte sowohl führende als auch nachgestellte Schrägstriche enthalten.
Zwei Beispiel-URIs unter dem Textfeld zeigen für HTTPS bzw. HTTP die Aufrufsyntax an, wenn der Dienst auf localhost veröffentlicht wurde.
In der Datentabelle ist nun das Modul hr_demo aufgeführt:
Nun wechseln wir auf die nächste Registerkarte. In der Tabellendarstellung werden zunächst keine Templates für unser Modul angezeigt.
Klicken Sie mit der rechten Maustaste und wählen Sie den Menüpunkt “Template erstellen”.
Nun erscheint ein modaler Dialog. Es zeigt das Modul hr_demo an, dem eine neues Template hinzugefügt werden soll.
Geben Sie ein URI-Pattern für das Template ein. Wir haben “emp” gewählt, weil wir Daten aus der Tabelle HR.EMPLOYEES verarbeiten wollen.
Wir belassen alle Eingaben auf dem Standardwert, mit Ausnahme des Kommentars “employees demo template”.
Nachdem Sie auf OK geklickt haben, wird das Template in der Tabelle angezeigt.
Unterhalb des Templates finden Sie zwei Beispiel-URIs für HTTPS und HTTP, unter der Annahme, dass ORDS auf localhost installiert worden ist.
Bitte beachten Sie, dass unser Webservice noch nicht vollständig ist. Er besteht aus
Der nächste Schritt wird die Erzeugung eines Handlers sein.
Nun wechseln wir noch einmal auf die nächste Registerkarte. In der Datentabelle werden zunächst keine Handler für unser Modul angezeigt.
Klicken Sie mit der rechten Maustaste und wählen Sie den Menüpunkt “Create Handler”.
Nun erscheint ein modaler Dialog. Er zeigt das aktuelle Modul hr_demo als Eingabevorschlag an, zu dem eine neuer Handler hinzugefügt werden soll.
Wählen Sie aus der Kombobox das URI-Pattern “emp/”. Damit benutzen Sie das Template, das im vorigen Schritt erzeugt wurde.
Wählen Sie als Methode “GET” und das JSON-Datenformat sowohl für Source als auch Result.
Im Codeeditor fügen wir nun eine Select-Anweisung ein. Unsere Beispiel-Query fragt die Daten der Tabelle EMPLOYEES ab.
Die WHERE-Bedingung erlaubt die Eingabe von zwei optionalen Parametern :EMPLOYEE_ID und :SALERY.
Solange kein Parameter vorgegeben ist, wird nach der entsprechenden Spalte auch nicht gefiltert.
Nachdem der Handler angelegt wurde, müssen Sie die SQL-Parameter noch definieren und damit URI-Parametern zuordnen.
Klicken Sie dazu mit der rechten Maustaste in die Liste der Parameter, die unterhalb des Handlers angezeigt wird. Wählen Sie den Menüpunkt “define parameter”.
Daraufhin wird dieser modele Dialog angezeigt:
Zunächst definieren wir die erste Bindvariable “ID” und füllen den Dialog wie in der Hardcopy zu sehen ist aus.
Anschließend wiederholen wir die Definition für die zweite Variable “SAL”.
Damit sieht die Handler-Seite folgendermaßen aus:
Der rote Pfeil in der Hardcopy zeigt auf zwei Beispiel-URIs, die unter der Annahme einer ORDS-Installation auf localhost, automatisch erzeugt wurden. Der linke URI gilt für HTTPS, der rechte für HTTP, das möglicherweise von Ihnen im Rahmen der Entwicklung genutzt wird.
Nun sind wir soweit, dass wir den Webservice testen können. Öffnen Sie eine Windows-Kommandozeile und starten Sie
ords serve
Damit wird der ORDS-Server gestartet.
Sobald der Server gestartet ist, können Sie auf einen der beiden Beispiel-URIs klicken, in unserem Fall die HTTP-Version. Damit wird der URL in Ihrem Standardbrowser geöffnet. Sie können im Browser nun ein JSON-Ergebnis mit allen Datensätzen der Tabelle EMPLOYEES sehen.
Als Nächstes möchten wir auch Parameter benutzen. Getrennt durch ein Fragezeichen fügen wir eine Zuweisung für den Parameter “id” ein:
Wie Sie sehen, enthält das Ergebnis eine JSON-Struktur mit dem abgefragten einzelnen Datensatz der EMPLOYEE-Tabelle einschließlich weiterer zusätzlicher HTTP-Referenzen.
Alternativ können Sie auch nach dem Gehalt abfragen, indem Sie den Parameter “sal” in den URL aufnehmen.
Das Ergebnis zeigt nun alle Mitarbeiter, die ein Gehalt von über 10.000 $ bekommen.
Zusammenfassung
Unser ORDS Oracle REST-Datenservice ist jetzt arbeitsfähig. Das Beispiel zeigt, wie Sie mit Hora ORDS-Webservices konfigurieren und testen können. Auf Basis dieser Vorlage können Sie Ihre eigenen komplexeren Webservices erstellen.
Im nächsten Blogbeitrag werden wir ein weiteres neues Feature vorstellen, das mit KeepTool 16 eingeführt wurde. Bleiben Sie am Ball.