Seit Dezember 2016 ist Application Express 5.1 verfügbar. Wie immer gibt es eine Menge neuer Features für Entwickler und Endbenutzer. Aber auch für den Administrator, der mit Installation, Upgrade oder dem Betrieb von APEX-Instanzen oder Anwendungen verantwortlich ist, bringt das neue Release einige Verbesserungen mit. Dieser Community Tipp stellt einige dieser neuen Funktionen vor.

Installation und Upgrade

Auf den ersten Blick sehen Installation und Upgrade von APEX 5.1 aus, wie immer. Beides erfolgt, indem man als SYS das Skript apexins.sql ausführt - ein typischer Aufruf sieht wie folgt aus.

$ apexins SYSAUX SYSAUX TEMP /i/

Der erste Parameter bestimmt das Tablespace für die APEX-Engine selbst (welches ins Datenbankschema APEX_050100 installiert wird); der zweite legt das Tablespace für FLOWS_FILES (hält die Tabelle mit hochgeladenen Dateien) fest. Der dritte Parameter bestimmt den temporären Tablespace für beide Schemas und der letzte Parameter legt den URL-Präfix fest, der vom Browser zum Ansprechen der statischen Dateien verwendet wird. Letzterer muss zur Konfiguration des APEX-Webservers passen und kann bei Bedarf mit dem Skript utilities/reset_image_prefix.sql geändert werden.

apexins.sql installiert die APEX-Umgebung komplett, also Laufzeit- und Entwicklungsumgebung. Auf Produktionssystemen besteht oft der Wunsch, nur die Laufzeitumgebung zu installieren und auf die Entwicklungsumgebung (den Workspace-Login) zu verzichten. Dazu dient das Skript apxrtins.sql.

Ist Application Express bereits in der Datenbank installiert, so erkennt apexins.sql das automatisch und es wird ein Upgrade durchgeführt. An dieser Stelle lohnt es sich, das Thema "APEX Upgrade" etwas genauer betrachten.

Unmittelbar nach dem Upgrade hat man demnach zwei APEX-Versionen in seiner Datenbank: die Alte und die Neue - mit den gleichen Workspaces, Anwendungen und Nutzern. So wird das im Installation Guide beschriebene Verfahren möglich, wieder auf die alte Version zurückzugehen. Im wesentlichen werden die Public Synonyms dazu einfach wieder auf die alte APEX-Version "zurückgebogen".

Bislang war es so, dass die APEX-Instanz für die gesamte Laufzeit des Upgrade nicht zur Verfügung steht: Der Installation Guide sagt zu Beginn des Upgrade folgerichtig: Prevent Access to Application Express. Erst nach dem vollständigem Upgrade wird der Webserver wieder gestartet. Die Dauer eines APEX-Upgrade richtet sich vor allem nach der Anzahl der vorhandenen Workspaces und Anwendungen: Projektspezifische Instanzen mit wenigen, Workspaces und Anwendungen sind schnell auf eine neue Version gebracht. Hostet eine APEX-Instanz dagegen sehr viele Anwendungen und Workspaces (beispielsweise der öffentliche Demoserver apex.oracle.com), so kann ein Upgrade durchaus einige Stunden in Anspruch nehmen. In solchen Umgebungen kann eine stundenlange Downtime durchaus zum Problem werden.

Zur Minimierung der Downtime stellt APEX 5.1 daher die Möglichkeit bereit, das Upgrade schrittweise, in vier Phasen, durchzuführen. Das gilt sowohl für die Vollinstallation als auch für die Runtime-Only Installation.

1. Erstellen des Schemas APEX_050100 und Installation der APEX-Engine
2. Migrieren der Anwendungs-Metadaten auf die neue APEX-Version
3. Migrieren von Runtime-Metadaten wie die Einstellungen von interaktiven Berichten, auf die neue APEX-Version
4. Migrieren archivierter Daten (bspw. das APEX Activity Log) auf die neue APEX-Version

Die erste Phase betrifft die bestehende APEX-Version in keinster Weise; so lange dieser Prozess läuft, können sowohl Endbenutzer als auch Entwickler normal weiterarbeiten. Wenn Phase 2 läuft, können die Anwendungen zwar noch genutzt, aber nicht mehr vom Entwickler verändert werden. Also muss nur die APEX-Entwicklungsumgebung gesperrt werden; die Anwendungen selbst können problemlos weiterlaufen.

Allein für Phase 3 muss der Zufriff auf APEX als Ganzes gestoppt werden; da dies jedoch nur einen kleinen Teil der Anwendungs-Metadaten betrifft, dürfte der Zeitraum eher kurz ausfallen. Nach Phase 3 kann APEX wieder komplett für alle Entwickler und Benutzer geöffnet werden, da Phase 4 (das Kopieren der archivierten Log-Informationen) keinerlei Downtime erfordert.

Möchte man dieses Upgrade in Phasen durchführen, so nutzt man für die Vollinstallation nicht mehr das Skript apexins.sql, sondern die Skripte apexins1.sql bis apexins3.sql. Alle Skripte erhalten die vier Parameter, die auch apexins.sql erhalten würde. Für die Runtime-Only-Installation stehen entsprechend die Skripte apxrtins1.sql bis apxrtins3.sql anstelle von apxrtins.sql bereit.

• Zuerst wird apexins1.sql / apxrtins1.sql gestartet. Der Webserver wird nicht heruntergefahren; die alte APEX-Version bleibt verfügbar.
• Danach wird apexins2.sql / apxrtins2.sql gestartet. Der Webserver wird ebenfalls nicht gestoppt; auch Entwickler können sich noch am APEX-Workspace anmelden. Wird jedoch versucht, eine Anwendung zu verändern, so bekommt man eine Fehlermeldung präsentiert.
  

  Abbildung 1: Applikationen können nicht verändert werden, wenn Phase 2 läuft

• Bevor das Skript apexins3.sql bzw. apxrtins3.sql gestartet wird, muss der Webserver gestoppt werden, denn nun beginnt die Downtime. Nach Ablauf des Skripts stellt man die neuen statischen Dateien auf dem APEX-Webserver (URL-Präfix /i/) bereit. Anschließend kann der Webserver wieder gestartet werden. Die neue APEX-Version 5.1 steht nun für Entwickler und Endbenutzer bereit.
• Die vierte und letzte Phase wird vom Skript apexins3.sql / apxrtins3.sql automatisch im Hintergrund (als DBMS_SCHEDULER-Job) gestartet. Entwickler und Endbenutzer können die APEX-Instanz schon verwenden, auch wenn dieser Job noch läuft.

REST Services zum Abrufen von Zugriffsstatistiken aus Application Express

Mit APEX 5.1 wird erstmals eine REST-API für administrative Zwecke eingeführt. Als erster Schritt stehen REST-Services zum Abrufen von Zugriffsstatistiken bereit. Um diese nutzen zu können, braucht es allerdings Oracle REST Data Services (ORDS) als APEX-Webserver; und es muss mindestens die Version 3.0.5 sein.

Zunächst sind die REST Services deaktiviert; zur Nutzung müssen sie also aktiviert werden. Navigieren Sie dazu zum Workspace INTERNAL und dort zum Bereich Manage Instance.

Abbildung 2: Workspace INTERNAL - Manage Instance

Klicken Sie dann auf REST Administration Interface. Ein Dialog sollte sich öffnen, mit der Meldung, dass die REST Services deaktiviert sind (Abbildung 3).

Abbildung 3: REST Administration Interface ist deaktiviert

Klicken Sie auf den Button Enable Services. Daraufhin werden die REST Services aktiviert.

Abbildung 4: REST Administration Interface wurde aktiviert

Um die REST Services nutzen zu können, muss man OAuth-Clients registrieren - die Authentifizierung erfolgt allerdings nicht mit Username und Passwort; vielmehr wird der OAuth-Verfahren Client Credentials verwendet. Mehr Informationen dazu finden Sie in der Dokumentation zu Oracle REST Data Services. Klicken Sie dazu auf den Button Create OAuth Client.

Abbildung 5: Einen neuem OAuth Client erzeugen

Geben Sie dem OAuth Client einen Namen und hinterlegen Sie eine Mailadresse als Kontaktinformation. Derzeit steht nur das Privileg View Usage Statistics zur Verfügung. Clicken Sie dann Create OAuth Client, um den Client zu registrieren.

Abbildung 6: Der neue OAuth-Client wurde registriert

Wenn Sie nun auf den Namen des Clients klicken, bekommen Sie die Details angezeigt; wichtig sind hier die Client-ID und das Client-Secret.

Abbildung 7: Der neue OAuth-Client wurde registriert

Das OAuth Verfahren Client Credentials sieht vor, dass man mit diesen beiden Angaben zuerst ein Access Token vom Server abholt. Dieses Token ist dann eine Stunde lang gültig und dient zur Authentifizierung beim Aufrufen der eigentlichen REST Services. Ist die Stunde abgelaufen, muss man sich ein neues Token holen. Die folgenden Anweisungen zeigen den Prozess mit dem Kommandozeilentool "curl". Mit dem ersten Request wird das Access Token abgeholt:

$ curl -u eQWP0rf84osHamhhLeFfUQ..:ZqRZMJ2BuUo7i8rad2GKzQ.. 
       --data "grant_type=client_credentials"  
       http://localhost:18080/ords/apex_instance_admin_user/oauth/token

{"access_token":"eT-I3nA9peooabMa0F1Ikw..","token_type":"bearer","expires_in":3600}

Die Antwort erfolgt im JSON-Format - das Attribut access_token enthält das gewünschte Token. Damit kann nun der eigentliche Request gemacht werden.

curl -H"Authorization: Bearer eT-I3nA9peooabMa0F1Ikw.." 
     http://localhost:18080/ords/apex_instance_admin_user/stats/latest/instance

Die Metriken werden wiederum im JSON-Format ausgeliefert.

{
  "items": [
    {
       "log_day": "2016-09-15T00:00:00Z",
       "workspace_id": 1809074264671554,
       "workspace_name": "SOMEWORKSPACE",
       "workspace_link": {
          "$ref": "http://application-express-host:port/ords/apex_instance_admin_user/stats/latest/workspace/someworkspace"
       },
       "application_id": 4750,
       "application_name": "Oracle APEX Packaged Applications",
       "application_link": {
       :

Die zur Verfügung stehenden REST Services sind im Application Express Administrators Guide aufgelistet; Metriken können auf Ebene der Instanz, des Workspace oder einer Anwendung abgerufen werden. Die Einschränkung nach bestimmten Tagen oder nur bestimmter Metriken ist ebenfalls möglich. Das JSON Format und die offene REST-Service Architektur macht es einfach, die Metriken in anderen Systemen zu konsumieren; denn JSON kann überall problemlos verarbeitet werden.

• APEX_UTIL.SET_APPLICATION_STATUS:
  Damit lässt sich per Kommandozeile (SQL*Plus) festlegen, ob eine APEX-Anwendung verfügbar sein soll oder nicht. Der separate Login in den APEX-Workspace und das Navigieren zu den Applikationsattributen der jeweiligen Anwendung entfällt. Der folgende Code setzt die Applikation 101 im Workspace TESTIT auf Unavailable, also "nicht verfügbar".

  begin
      apex_util.set_workspace( 'TESTIT' );
      apex_util.set_application_status( 
          p_application_id     => 101, 
          p_application_status => 'UNAVAILABLE', 
          p_unavailable_value  => 'This Application is not available!' );
  end;
  /
  
  commit;
  

  Ruft man die Anwendung 101 nun im Browser auf, so sieht man nur noch eine Meldung, dass die Anwendung nicht verfügbar ist.
  
  
• Neues Paket APEX_SESSION:
  Mit diesem Package kann man den Debug-Modus für eine bestimmte APEX-Session aktivieren. Das ist besonders hilfreich, wenn eine konkrete Session ein Problem hat - man muss den Endanwender nun nicht mehr bitten, den Debug-Modus durch Einfügen von YES an der richtigen Stelle der URL zu aktivieren.
  
  Alles, was man braucht, ist die jeweilige Session ID, die man aus der URL entnehmen oder vom Endanwender (per Telefon) erfragen kann. Damit lässt sich der Debug-Modus ganz bequem aus der Ferne einschalten. Das Feature funktioniert auch, wenn Debugging an der Anwendung eigentlich deaktiviert ist; schließlich kann es nur per API, also von einem Entwickler oder Administrator, genutzt werden. Diese Funktion ist natürlich auch für den Entwickler interessant. Das folgende Kommando (als DBA abgesetzt) setzt Debug-Level 9 für eine konkrete APEX-Session. Vergessen Sie das COMMIT nicht.

  begin
    apex_session.set_debug( 2364850177865, 9 );
  end;
  /
  
  commit;
  

  Alle nachfolgenden Aktionen dieser Session werden nun auf der höchsten Debug-Ebene 9 protokolliert. Ebenfalls als DBA kann man sich diese Einträge nun in der View APEX_DEBUG_MESSAGES ansehen.

    select APPLICATION_ID, PAGE_ID, ELAPSED_TIME, MESSAGE_TIMESTAMP, substr(message, 1,40)  
      from apex_debug_messages 
     where session_id = 2364850177865
  order by MESSAGE_TIMESTAMP;
  
  APPLICATION_ID    PAGE_ID ELAPSED_TIME MESSAGE_TIMESTAMP                  SUBSTR(MESSAGE,1,60)                                        
  -------------- ---------- ------------ ---------------------------------- ------------------------------------------------------------
            4050          3 ,041524      18.01.17 04:43:36,715794000 -08:00 DEPRECATED: public_check_authorization                      
             101            ,003383      18.01.17 05:50:34,536311000 -08:00 Reset NLS settings                                          
             101            ,004057      18.01.17 05:50:34,536965000 -08:00 alter session set  NLS_LANGUAGE='AMERICAN' NLS_TERRITORY='AM
             101            ,004553      18.01.17 05:50:34,537481000 -08:00 ...NLS: Set Decimal separator="."                           
             101            ,00469       18.01.17 05:50:34,537621000 -08:00 ...NLS: Set NLS Group separator=","                         
             101            ,004817      18.01.17 05:50:34,537751000 -08:00 ...NLS: Set g_nls_date_format="DD-MON-RR"                   
             101            ,004968      18.01.17 05:50:34,537899000 -08:00 ...NLS: Set g_nls_timestamp_format="DD-MON-RR HH.MI.SSXFF AM
             101            ,005101      18.01.17 05:50:34,538033000 -08:00 ...NLS: Set g_nls_timestamp_tz_format="DD-MON-RR HH.MI.SSXFF
             101            ,005308      18.01.17 05:50:34,538242000 -08:00 no characterset conversion needed             
               :                  :      :                                  :
  

  Mit der Prozedur SET_TRACE lässt sich, analog zu SET_DEBUG, ein SQL Trace für eine konkrete APEX-Session aktivieren. Ein SQL Trace schreibt seine Daten in die Tracefiles, welche man als DBA in Verzeichnis der user-dump-destination findet.
• Wie in früheren Versionen, können Sie auch in APEX 5.1 administrative Aufgaben mit dem Paket APEX_INSTANCE_ADMIN durchführen; dazu wurde vor einiger Zeit bereits ein Community-Tipp veröffentlicht: APEX und die Kommandozeile: Da geht mehr als man denkt.

Wie beim Release von APEX 5.0 angekündigt, wurde alte PL/SQL Paket APEX_PLSQL_JOB mit APEX 5.1 entfernt, da es auf dem veralteten veralteten DBMS_JOB-Paket basiert. APEX_PLSQL_JOB wurde verwendet, um PL/SQL-Logik im Hintergrund auszuführen. Schon seit der Oracle Datenbank 10g steht dafür das Paket DBMS_SCHEDULER bereit - welches eine wesentlich bessere Job-Steuerung und viele Informationen in Data Dictionary-Views anbietet. Code, der noch mit APEX_PLSQL_JOB arbeitet, sollte also möglichst bald auf DBMS_SCHEDULER umgestellt werden. Dazu ein Beispiel - angenommen, eine der APEX-Anwendungen nutzt folgenden Code, um PL/SQL-Prozeduren im Hintergrund zu starten.

DECLARE
    l_sql  VARCHAR2(4000);
    l_job  NUMBER;
BEGIN
    l_sql := 'begin plsql_to_run_as_job( :P1_ITEM ); end;';
    l_job := APEX_PLSQL_JOB.SUBMIT_PROCESS(
        p_sql    => l_sql,
        p_status => 'Background process submitted' );

    :P1_JOB_ID := l_job;
END;

Der folgende Code tut das gleiche, nutzt aber DBMS_SCHEDULER.

DECLARE
    l_sql varchar2(4000);
    l_job varchar2(4000);
BEGIN
    l_sql := 'begin plsql_to_run_as_job( ' || 
              dbms_assert.enquote_literal( :P1_ITEM ) || 
             ' ); end';
    l_job := dbms_scheduler.generate_job_name ( 
        prefix => 'MY_APEX_JOB' );

    dbms_scheduler.create_job(
        job_name =>   l_job,
        job_type =>   'PLSQL_BLOCK',
        job_action => l_sql,
        comments =>   'Background process submitted',
        enabled =>    true );
END;

Auch wenn Sie das Upgrade auf APEX 5.1 erst etwas später planen, so ist es sehr empfehlenswert, vorhandene Applikationen auf die Verwendung von APEX_PLSQL_JOB hin zu prüfen und - schon in APEX 5.0 - den Umstieg auf DBMS_SCHEDULER vorzunehmen.

Zurück zur Community-Seite