Gunther Oracle APEX und Datenbank Wiki

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
=====Oracle ORDS 18 (Oracle REST Data Services) mit APEX 18 und als REST Interface verwenden=====
**März 2016 - auf 3.0.4 aktualisiert**

**Januar 2018 - auf 17 aktualisiert**

**Oktober 2018 - auf 18.3 aktualisiert-> klappt nicht!**

<note important>Achtung! ein Upgrade von der Version 17 auf die 18.2 bzw. 18.3 ist NICHT möglich, ein Bug verhindert das! D.h. es MUSS neu installiert werden! Zuvor daher alle Rest Services sorgfältig sichern und dann neu anlegen!</note>



**November 2019 - 19.2 aktualisiert**


----

====ORDS = Oracle REST Data Service====

Mit dem [[https://de.wikipedia.org/wiki/Representational_State_Transfer|Representational State Transfer (abgekürzt REST)]] wird ein Programmierparadigma für verteilte Systeme bezeichnet, das insbesondere für Webservices verwendet wird.

Der Oracle RESTful Data Service wurde früher unter dem Name Oracle Application Express Listener vermarktet.

APEX wird natürlich weiterhin unterstützt, ein neuer Fokus liegt aber auch auf der Bereitstellung eines REST Services für die Datenbank.

{{ :prog:plsql:ords_apex_overview_v01.png | Oracle Oracle REST Data Services Overviews}}

Bei der Installation wird der ORDS User "ORDS_PUBLIC_USER" angelegt, alle APEX relevanten User müssen bereits (zusammen **zuvor** mit der APEX Installation angelegt!) existieren.


----

==== Lizenz ====

Wird der ORDS nur für den Aufruf von APEX verwendet, kann der ORDS mit der DB kostenfrei eingesetzt werden.

Aus der Lizenz Dokumentation:

//"A restricted-use license for Oracle Application Express Listener is included with all editions (except for Oracle Database Express Edition) solely to support connectivity to Oracle Application Express, which may be installed in the Oracle Database. Running Oracle Application Express Listener on a different server does not require that that server be licensed to use the Oracle Database."//

siehe => http://docs.oracle.com/database/121/DBLIC/editions.htm#DBLIC2163


----

====Betrieb====

Der ORDS kann in einer Standalone Version mit dem integrierten [[http://www.eclipse.org/jetty/|Jetty Java Server]] gestartet werden. 


Dies ist aber mehr für Testumgebungen vorgesehen.

In einer produktiven Umgebungen können die folgenden Java Applikations Server verwendet werden:
  * Oracle WebLogic Server 11g Release 1 (10.3.6) or later
  * GlassFish Server Release 3.1.2 or later  (Wichtigen Security Hinweis in der Doku beachten!)
  * Apache Tomcat Release 7.0.56 => siehe auch [[oracle_rest_data_service_tomcat|ORDS mit Tomcat betreiben]]


Voraussetzungen für den Betrieb:
  * Java JDK 1.7 oder später (Test erfolgt mit Java 1.8.0)
  * Oracle Datenbank ab Oracle 11g R1
  * <fc #800000>Default Port 8080 noch frei!(an den XMLDB Listener der DB denken, falls im Einsatz!)</fc>

In der Datenbank werden bei der Installation die folgenden User angelegt:
  * ORDS_METADATA als ORDS Repository  Owner
  * ORDS_PUBLIC_USER als Zugriffschicht



----

====Apex für den ORDS konfigurieren ====

Die APEX Installation und der entsprechende Public User "APEX_PUBLIC_USER" müssen zuvor schon vorhanden sein!

Soll der Apex REST Service weiterhin verwendet werden, sind noch die Passwörter der DB User APEX_LISTENER und  APEX_REST_PUBLIC_USER notwendig. 

Diese sind zuvor bei der APEX Installation angelegt worden bzw. müssen VOR der ORDS Installation vorbereitet werden!


Bei Bedarf die Apex Passwörter setzen:

<code sql>
alter user APEX_PUBLIC_USER IDENTIFIED  by apex1234;
alter user APEX_PUBLIC_USER account unlock;

alter user APEX_LISTENER IDENTIFIED  by apex1234;
alter user APEX_LISTENER account unlock;

</code>
In der Produktion natürlich bessere Passwörter wählen! 

Bzw: die User überhaupt anlegen:
  * **APEX_LISTENER** und **APEX_PUBLIC_USER** User anlegen mit:<code sql>@apex_rest_config.sql</code>
 



----

----


===== ORDS als Standalone Variante aufsetzen=====

Im ersten Schritt wird der ORDS als Standalone Variante mit Jetty aufgesetzt
===Software auspacken===

  * Download der Zip Datei für alle Plattformen des Oracle REST Data Services 3.0.4 unter http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html
  * Datei auspacken zum Beispiel nach D:\oracle\products\ords.3.0.4



----

===Verzeichnis für den statischen Content anlegen===

Für den Statischen Content ein Verzeichnis wie **"D:\oracle\apex_public"** anlegen, bei Bedarf dort eine  Datei "index.html"  (Inhalt <nowiki><html><body>Hello World</body></html></nowiki>) zum Testen hinterlegen.



----

===Die APEX Bilder für die Verwendung mit dem ORDS referenzieren===

Der ORDS stellt auch die Bilder einer Oracle APEX Installation zur Verfügung, dazu müssen diese aber in einem WAR File referenziert werden. 


In meinen Beispiel liegt die entpackte Oracle Application Express 5.1 Version unter c:\oracle\apex. 

Hier müssen die Datein dann auch später noch liegen! In dem War File wird die Location nur referenziert!

Auf das richtige escapen des Pfades achten:
<code powershell>
#Bilder referenzieren

java -jar ords.war static C\:\\oracle\\apex\\images

WAR Generation complete
 WAR location     : C:\oracle\product\ords.17.4.1\i.war
 Context path     : /i
 Static resources : C\:\\oracle\\apex\\images
Ensure the static resources are available at path: D\:\\oracle\\apex\\images
on the server where the WAR is deployedPS


#Erzeugte Datei anzeigen
dir i.war


</code>

Die erzeugte Datei <fc #800000>**i.war**</fc> muss im gleichen Verzeichnis wie die ords.war Datei liegen!

Auch die standalone.properties auf den richtigen Pfad überprüfen

<code java>
jetty.port=9090
standalone.context.path=/ords
standalone.doc.root=C\:\\oracle\\apex_public
standalone.scheme.do.not.prompt=true
standalone.static.context.path=/i
standalone.static.path=C\:\\oracle\\apex\\images

</code>
----

=== Konfigurationsdatei Struktur anlegen / hinterlegen ===

Die Struktur der Konfiguration kann auch in einem anderen Ordner angelegt werden, die Referenz auf das Konfigurationsverzeichnis wird auch dann später im WAR File hinterlegt.

Da diese Information im War File steht, findet auch später der ORDS deployed im Tomcat immer noch seine Konfiguration.

Verzeichnis "D:\srv\ords" angelegt, dort wird die Konfiguration abgelegt.

<code powershell>

mkdir D:\srv\ords

cd D:\oracle\product\ords.3.0.4

java -jar ords.war configdir D:\srv

May 07, 2016 11:59:31 AM oracle.dbtools.cmdline.ModifyConfigDir execute
INFO: Set config.dir to D:\srv\ords in: D:\oracle\product\ords.3.0.4\ords.war

</code>

Im ersten Schritt wird aber nur die Referenz gesetzt und noch keine Konfiguration erzeugt.




----





===Install Parameter Konfigurieren des ORDS===

Die Datei %ORDS_HOME\params\ords_params.properties konfigurieren:

<code java>
db.hostname=10.10.10.1
db.port=1521
db.servicename=GPI
db.sid=GPI
db.username=APEX_PUBLIC_USER
migrate.apex.rest=false
rest.services.apex.add=true
rest.services.ords.add=true
schema.tablespace.default=SYSAUX
schema.tablespace.temp=TEMP
standalone.http.port=8080
standalone.static.images=D\:\\oracle\\apex\\images
user.tablespace.default=USERS
user.tablespace.temp=TEMP
</code>

Damit sind beim nächsten Schritt schon wichtige Antworten vorbelegt.

Nun mit SQL*Plus prüfen ob auch eine Verbindung zur Datenbank von diesem Host möglich ist und sys PWD usw. auch stimmt!


===Installation der ODS Schemas und Konfiguration===

Installation per Kommandozeile durchführen falls das sys User Password bekannt ist:
<code>

java -jar ords.war install advanced


Enter the name of the database server [10.10.10.1]:
Enter the database listen port [1521]:
Enter the database service name [GPI]:
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:

Please login with SYSDBA privileges to verify Oracle REST Data Services schema. Installation may be required.
Enter the username with SYSDBA privileges to verify the installation [SYS]:
Enter the database password for SYS:
Confirm password:
Nov 07, 2015 9:27:29 PM oracle.dbtools.rt.config.setup.SchemaSetup addSchemaParams
INFO:
Oracle REST Data Services schema does not exist and will be created.

Enter the default tablespace for ORDS_METADATA [SYSAUX]:
Enter the temporary tablespace for ORDS_METADATA [TEMP]:
Enter the default tablespace for ORDS_PUBLIC_USER [USERS]:
Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP]:
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step.

If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]:1
Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]:
Enter the database password for APEX_PUBLIC_USER:
Confirm password:
Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:1
Enter the database password for APEX_LISTENER:
Confirm password:
Enter the database password for APEX_REST_PUBLIC_USER:
Confirm password:
Nov 07, 2015 9:29:09 PM oracle.dbtools.common.config.file.ConfigurationFilesBase update
INFO: Updated configurations: defaults, apex, apex_pu, apex_al, apex_rt
Nov 07, 2015 9:29:09 PM oracle.dbtools.installer.Installer installORDS
INFO:
Installing Oracle REST Data Services version 3.0.2.294.08.40
... Log file written to D:\oracle\products\ords.3.0.2\logs\ordsinstall_2015-11-07_212909_00972.log
... Verified database prerequisites
... Created Oracle REST Data Services schema
... Created Oracle REST Data Services proxy user
... Granted privileges to Oracle REST Data Services
... Created Oracle REST Data Services database objects
Nov 07, 2015 9:29:30 PM oracle.dbtools.installer.Installer installORDS

INFO: Completed installation for Oracle REST Data Services version 3.0.2.294.08.40. Elapsed time: 00:00:21.422

Enter 1 if you wish to start in standalone mode or 2 to exit [1]:2

</code>

Alternatic nur die Datenbank Script erzeugen und dann manuell die User anlegen und dann die Konfiguration erzeugen:
<code>
java -jar ords.war ords-scripts --scriptdir d:\temp

#Datenbank Installationsscript aufrufen

sqlplus "sys as sysdba" @ords_manual_install SYSAUX TEMP D:/temp/log


# Konfiguration hinterlegen

java -jar ords.war setup advanced
</code>


----


===ORDS starten===


Der Oracle REST Data Services lässt sich im Standalone Mode mit den folgenden Befehl starten:

<code cmd>
"java -jar ords.war standalone [--port] [--apex-images] [--context-path] [--static-context-path] [--doc-root] [--parameterFile]"
</code>


In des ORDS Home wechseln und starten

Beim Start das Verzeichnis für die Konfigurationsdaten  und die Apex Bilder angeben:
<code dos>

# Hilfe anzeigen lassen:

java -jar ords.war help standalone


# Starten
java -jar ords.war standalone --parameterFile D:\oracle\product\ords.3.0.4\params\ords_params.properties --doc-root d:\oracle\apex_public --apex-images D:\oracle\apex\images

</code>

Script zum Starten des ORDS anlegen:
<code cmd startORDS.cmd>
set JAVA_HOME=D:\oracle\product\sqldeveloper\jdk\jre
set ORDS_HOME=D:\oracle\product\ords.3.0.4
set DOC_ROOT=D:\oracle\apex_public

echo ---------------------------------------
echo -- to connect use http://127.0.0.1:8080/ords  
echo -- Workspace internal, user admin
echo --
echo ---------------------------------------

%JAVA_HOME%\bin\java.exe -jar ords.war standalone --parameterFile %ORDS_HOME%\params\ords_params.properties --doc-root %DOC_ROOT% --apex-images D:\oracle\apex\images

</code>


----


===An APEX anmelden ===


<fc #800000>**Aufruf mit <nowiki>http://localhost:port/ords</nowiki> oder <nowiki>https://host:port/apex/apex_admin </nowiki>**</fc>.


Default Workspace "INTERNAL", Admin User + Passwort eingeben.


Ist dies die Entwicklungsumgebung, ist es oft sehr unpraktisch sich komplexe Passwörter zu merken und diese dann auch öfters zu ändern. 

Einstellungen anpassen wie hier beschrieben, in Apex 5 Lassen sich die gleichen Einstellungen finden
=> https://mikesmithers.wordpress.com/2013/07/28/turning-off-password-expiration-on-oracle-xe-and-apex/

----

==== Probleme ====


===Probleme - 404 Page Not found ===

Nach dem ersten Aufruf nur die Seite "404 Page Not found" erhalten, hier läuft etwas falsch .....

Debugging / logging aktivieren über die default.xml
<code xml>
<entry key="debug.debugger">true</entry>
<entry key="debug.printDebugToScreen">true</entry>
</code>

Logging einschalten:
<code xml>
<entry key="log.logging">true</entry>
<entry key="log.maxEntries">500</entry>
</code>





===Bilder Fehler ===

Beim Start wird im Browser angezeigt, das die Application Express Files nicht geladen weden können.


Testen ob dieser Aufruf ok ist:

** <nowiki>http://localhost:port//i/apex_version.txt</nowiki> **

Das solle den String "Application Express Version:  5.0.3" zurückgeben!


Ein Fehler kann nun sein das im Stand alone Mode das Apex  Bilder Verzeichnis nicht angeben wurde **"Parameter  --apex-images D:\oracle\apex\images "** beim Aufruf des ORDS im Standalone Mode

Ein weitere Fehler können fehlende Konfigurationsdateien unter $ORDS_HOME\ords\conf apex.xml und apex_pu.xml sein.

Konfiguration neu erzeugen mit:
<code cmd>
java -jar ords.war install
</code>

Weitere Problem in der Art:


<fc #800000>"There are issues with the configuration of the Static Files in your environment. Please consult the "Configuring Static File Support" section in the Application Express Installation Guide."</fc>

 see => https://community.oracle.com/message/13014173#13014173

APEX_LISTENER und APEX_PUBLIC_USER User angelegt mit:<code sql>
@apex_rest_config.sql
</code>


User Passwörter in der ORDS Propertie Datei gepfegt und ORDS neu initialisert mit (im ORDS HOME):
<code cmd>
 java -jar ords.war install
</code>
Anweisungen befolgen!

Danach ist der Fehler zwar verschwunden es stellt sich aber die Frage wie das dann eigentlich so funktioniert ....


Für eine produktive Umgebung sollte hier wohl noch etwas mehr nachgeforscht werden.

===Problem mit Theme roller generated CSS not found by ORDS ===

Eine neues Theme lässt sich zwar mit dem Theme roller erstellen, danach funktioniert es aber nicht, es wird kein Style mehr angewandt!

Fehlermeldung im ORDS mit "oracle.dbtools.url.mapping.db.targets.DatabaseSchemasProvider handleException" 

Lösung: Gleich wie oben, alles richtig einrichten!

Siehe =>  https://community.oracle.com/thread/3707981?start=0&tstart=0

Auch hier das Debuggen wie oben beschrieben aktivieren und dann die Ausgaben sorgfältig lesen:

<code>
SCHWERWIEGEND: *** The pool named: apex_pu is reporting no APEX workspaces are enabled for RESTful Services,
 but the pool named: apex_al is reporting 1 workspaces are enabled.
This implies APEX was installed after Oracle REST Data Services. Please run the following command and restart Oracle REST Data Ser
vices:
        java -jar ords.war validate --database apex
</code>

Reparieren:
<code cmd>
java -jar ords.war validate --database apex
</code>

Leider hat das das Problem noch nicht gelöst .... BUG???? => https://community.oracle.com/thread/3885041?start=0&tstart=0

Bin nun wieder auf der 3.0.2 Version gelandet, alles neu gleich wie unter 3.0.2 konfiguriert, und nun funktioniert es, warten wir dann wohl auf die Version 3.0.4 und teste dort erneut.

----

==== Parameter optimieren ====

Je nach dem wieviele User mit dem System arbeiten wollen, kann es Sinn machen die Pool Größen anzupassen.

=== Übersicht über die Konfigurationsdateien===

Übersicht über die Konfigurations Dateien im ORDS (in unseren Fall unter D:\srv\ords\ords):

**defaults.xml**
  * Allgemeine Einstellungen und Defaults für alle Connection Pools

**standalone\standalone.properties**
  * Jetty Standalone Einstellungen wie die Ports und der /i/ Pfad

**conf/apex.xml**
  * APEX_PUBLIC_USER

**conf/apex_al.xml**
  * APEX_LISTENER

**conf/apex_pu.xml**
  * APEX_REST_PUBLIC_USER

**conf/apex_rt.xml**
  * ORDS_REST_PUBLIC_USER


===Optimieren der Pool Settings===

default.xml:
<code xml>
<!-- von 3 auf 10 -->
<!-- Anzahl der Connections beim Startup -->
<entry key="jdbc.InitialLimit">10</entry>

<!-- von 10 auf 50 -->
<!-- Maximale Anzahl von gleichzeitigen Sessions -->
<entry key="jdbc.MaxLimit">50</entry>

<!-- von 1 auf 10 -->
<!-- Minimal Anzahl auch wenn inaktiv --> 
<entry key="jdbc.MinLimit">10</entry>
</code>

Security Function:
<code>

For an APEX install, the security function should always be set. This blocks non-apex procedures.  These could be procedures that happen to be granted to public by accident or intentionally.


<entry key="apex.security.requestValidationFunction">wwv_flow_epg_include_modules.authorize</entry>

</code>

siehe => http://krisrice.io/2012-05-14-apex-listener-jdbcsecurity-setup/



----

==== In Apache Tomcat integrieren ====


Läuft nun der ORDS wie erwartet, kann die Integration in den Applikation Server durchgeführt werden.

siehe dazu => [[prog:oracle_rest_data_service_tomcat|Oracle ORDS 3.0 (Oracle REST Data Services) mit dem Apache Application Server Tomcat unter Windows 2012 betreiben]]


----

----

=====ORDS Update =====


**Aktuell Oracle REST Data Services Version 19.2, Updated November, 2019**

  * Neue Version herunterladen von => http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html 
  * Auspacken z.B. nach D:\oracle\products\ords19.2
  * Liegt die Konfiguration im ORDS Home, Ordner "ords" aus dem alten Home in das neue Home kopieren
  * Liegt der Pfad zur Konfiguration in einer eigenen Verzeichnisstruktur muss nur dieser Pfad neu angegeben werden (darauf achten das unter diesem Pfad dann ein Ordner ords mit der eigentlichen Config existieren muss!)
    * Pfad zur Konfiguration im War File hinterlegen <code>
# Alten Pfad testen im alten Home!!!
# java -jar ords.war configdir
#
java -jar ords.war configdir  C:\oracle\ords
</code>
  * Die alte Datei ords_params.properties aus alten Home, z.B. D:\oracle\products\ords.3.0.12\params,  nach dem neuen NEW_ORDS_HOME\params kopieren, z.B. D:\oracle\products\ords19.2\params
  * Der alte ORDS kann nun gestoppt werden 
  * Starten und das neues ORDS_HOME angeben:<code powershell>
set-item -path ENV:JAVA_HOME -value "C:\Program Files\Java\jdk1.8.0_112"
set-item -path ENV:ORDS_HOME -value "D:\oracle\products\ords19.2"
set-item -path ENV:DOC_ROOT  -value "D:\oracle\apex_public"

# Starten um zu testen das die Konfiguration auch wieder richtige gelesen werden kann

java.exe -jar ords.war standalone --parameterFile $ENV:ORDS_HOME\params\ords_params.properties --doc-root $ENV:DOC_ROOT


</code> Dann wieder stoppen!
  * Datenbank Resporitory upgraden:<code powershell>
 java -jar ords.war install
# User entsprechende angeben und durchlaufen lassen

Verify ORDS schema in Database Configuration apex with connection host: 10.10.10.1 port: 1521 sid: GPI


Retrieving information.
Requires to login with administrator privileges to verify Oracle REST Data Services schema.

Enter the administrator username:sys
Enter the database password for SYS AS SYSDBA:
Confirm password:

Retrieving information.
Upgrading Oracle REST Data Services schema 18.3.0.r2701456 to version 19.2.0.r1991647
... Log file written to C:\Users\gpipperr\ords_upgrade_2019-11-06_133214_00488.log
... Upgrading ORDS schema to 19.2.0.r1991647
Completed upgrade for Oracle REST Data Services version 19.2.0.r1991647.  Elapsed time: 00:00:14.484


</code> 
  * Normal wieder starten und testen:<code powershell>java.exe -jar ords.war standalone --parameterFile $ENV:ORDS_HOME\params\ords_params.properties --doc-root $ENV:DOC_ROOT
</code>
  * Wird der ORDS unter Tomcat betrieben **muss die War noch in das Webapps Verzeichnis kopiert** werden! FAlls mit Links auf das ORDS Verzeichnis gearbeitet wurde diese entsprechend anpassen!


----


===== Quellen =====

Oracle:

Dokumentation:
  * http://docs.oracle.com/cd/E56351_01/index.htm
  * http://www.oracle.com/technetwork/developer-tools/apex/learnmore/apex-example-deployment-wp-2214343.pdf

Home Page ORDS
  * http://www.oracle.com/technetwork/developer-tools/rest-data-services/overview/index.html


Web:
  * http://www.explorer-development.uk.com/ordsinary/
  * https://blogs.oracle.com/newgendbaccess/
  * https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-3-installation-on-tomcat-7
  * http://www.sqlsnippets.com/en/topic-11686.html


Artikel:

  * http://www.doag.org/home/aktuelle-news/article/rest-services-fuer-die-oracle-datenbank-ords.html