Oracle ORDS - dietmaraust.comdietmaraust.com/wp-content/uploads/2019/06/D_Aust... · mod_plsql...

2

OracleORDSNewfeaturesyoucan'tignore

DietmarAustOpal-Consulting,Köln

www.opal-consulting.de

3AboutDietmar.

•  Dipl.-Inform.DietmarAust,FreelanceConsultant•  Master'sDegreeinComputerScience(MSCS)

•  BuildingOraclebasedWebApplicationssince1997•  Portal,Forms,Reports,OWAToolkit,nowAPEX!

•  1997-2000:ConsultantatOracleGermany

•  Since09/2000:FreelanceConsultant,Since2006–APEXonly!

•  AuthoroftheJasperReportsIntegrationtoolkit•  http://www.opal-consulting.de/tools

•  2015DatabaseDeveloperoftheyearintheORDScategory

4AboutDietmar

•  OracleACEfrom2012–2019•  http://dietmaraust.com/quitting-the-oracle-ace-program-explained

•  ContributingtotheOracle/APEXcommunityfrom2006...2050?

5Agenda

Coveringnewfeaturesfrom17.4to19.1•  PreHook•  mod_plsqlmigrationsupport•  RESTenabledSQL•  DatabaseRESTAPI•  Smallerfeatures•  Changed,deprecatedandremoved

6Versioninformationinlowerleftcorner

•  Whenwasthatnewfeatureintroduced?

7

PreHook

8PreHook

APreHookimplementsapl/sqlhandlerBEFOREaRESTfulcallisprocessedAuthenticatingusers(firstpartyauthentication)hadchallengespreviously:•  Hadtobedoneattheapplicationserverlevel

–  toocomplicatedformanydevelopers–  differentimplementationforeachapplicationserver(Tomcat/Weblogic/Glassfish)

ORDS18.3

9PreHook

MajorUseCases:•  Setupuser/roleswithpl/sqlandnotintheapplicationserver

–  APEXauthenticationschemesareeasytoimplementwithpl/sql•  ImplementVPDrequirementsforRESTfulhandlers

–  Collectionandcollectionitemquerieswithoutvpdcontext=>emptyresultset

•  Autorestenabledobjectscanaccesstheuseridentity(:current_user)inatrigger

ORDS18.3

10PreHook

1.  ConfigurationinORDS/defaults.xml:

– DefinedonconnectionpoollevelforallRESTenabledschemasinthatdatabase

2.  Createplsqlfunction

–  MustbeexecutablebyallRESTenabledschemasorglobally–  ExceptionHandlerisREALLYIMPORTANT–  Mayaffectperformance,iscalledbeforeEVERYrequest.

ORDS18.3

�<entrykey="procedure.rest.preHook">myPLSQLFunction</entry>

�FUNCTIONords_prehookRETURNBOOLEAN

11PreHook-Flowofevents

Oracle REST Data

Services

ORDSRunsinWLS,Tomcatcontainer

OracleDB5.DBreturnsJDBCResults

6.ReturnJSON/CSV

1./ords/<RESTfulURI>

2.CallpreHook()

3.Return(yes/no),headersX-ORDS-USERX-ORDS-USER_ROLES

4.CallRESTfulservice()

ORDS18.3

12

ORDS18.3

13PreHook-Flowofevents

Oracle REST Data

Services

ORDSRunsinWLS,Tomcatcontainer

OracleDB5.DBreturnsJDBCResults

6.ReturnJSON/CSV

1./ords/<RESTfulURI>

2.CallpreHook()

3.Return(yes/no),headersX-ORDS-USERX-ORDS-USER_ROLES

4.CallRESTfulservice()

UsesIDENTICALsessionfromconnectionpool

ORDS18.3

⇒ Detectthecallcontext⇒ parsingschema,⇒ URI,httpheaders,basicauth,...

14PreHook–Detectingthecallcontext

http://localhost:8080/ords/rest/ordstest/opal/nf/v1/user-info?x=1

ORDS18.3

15PreHook–DifferentHandlersperSchema

•  ImplementingdifferenthandlersperRESTenabledschema?1.  UsedifferentconnectionpoolsandURLsforeachREST

enabledschema2.  DifferentPL/SQLfunctionsperORDSenabledschema

•  Globallyexecutableprehookfunctionwithpublicsynonym•  Differentlocalfunction(withidenticalname)ineachschemaleveragingOraclenameresolution

3.  Singleglobalfunctionwithdifferentcodebasedoncallcontext(parsingschema,module,etc.)

ORDS18.3

16PreHook–IntegrationwithActiveDirectory

•  LeveragingSSOHeaderintegrationwithActiveDirectory–  https://www.edocr.com/v/lv1rvxvx/nielsdebruijn/Single-Sign-On-for-Oracle-Application-Express-APEX

•  BasicIdea:ConnectWebServer/ApplicationServertoActiveDirectoryandsethttpheadervariableSSO_USER

ORDS18.3

17PreHook–IntegrationwithActiveDirectory

•  ImplementationinPreHook– worksacrossapplicationservers!

createorreplacefunctionords_prehookreturnbooleanisbeginowa_util.status_line(200,'OK',FALSE);htp.prn('X-ORDS-HOOK-USER:'||owa_util.get_cgi_env('SSO_USER'));returntrue;EXCEPTIONWHENOTHERSTHEN--THISISIMPORTANT!!!ElseORDSmightnotreturnonceanerroroccured.RETURNfalse;END;

ORDS18.3

18

mod_plsqlMigrationSupport

19mod_plsqlDesupport

•  DeprecatedsinceOracleHTTPServer(OHS)12.1.3•  RemovedinOracleHTTPServer12cversion12.2.1

20mod_plsqlMigrationSupport

•  NewfeaturesaddedtoOracleORDStoease1:1migrationfrommod_plsql

•  Upuntil17.4–  somefeatureswerenotsupported(mainlyauthenticationchoices),

–  somehadtoberewritten(e.g.fileupload)

21HTTPBasicauthenticationwithDBuser/pwd

Usingdatabaseaccounts(username/password)toauthenticatePL/SQLgatewaycalls.Inmod_plsqltheusername/pwdwasempty/plsql/logmeofftodeauthenticate

ORDS18.1


SetupinORDS1.  Createadummyuserwhichhasnoexecuteprivilegeson

anything(oruseAPEX_PUBLIC_USERforexample)2.  Createaplsqlconnectionpoolwiththisuser3.  Definejdbc.auth.enabledinplsqlconnectionpool

ORDS18.1

<properties><comment>SavedonFriApr1210:52:47CEST2019</comment><entrykey="db.password">@058A4EE0DA652E95D5BCA4A0B55895AF3B</entry><entrykey="db.servicename">XE</entry><entrykey="db.username">APEX_PUBLIC_USER</entry><entrykey="jdbc.auth.enabled">true</entry></properties>


•  Whencallingapublicprocedure–  http://vm1/ords/basic_dyn_auth/apex_login–  Itwilljustproceedandyouwillnotbeprompted

•  Callingaprivateprocedurewilltriggerthechallenge–  http://vm1/ords/basic_dyn_auth/opal_demo_ords.user_info

–  Thenenterdbuser/pwdforthesession

ORDS18.1


ImportantConstraints•  UserMUSTNOTbeREST-enabled•  UserMUSTNOThaveexecuteprivilegesonthetargetprocedure

Restrictions•  Logout(/pls/logmeoff)isnotsupported,browsermustbeclosed

•  Anadditionalroundtripforloginrequired(connectionpoolcannotbeused),mightaffectinitialperformance

ORDS18.1

25CustomAuthentication

Customauthenticationwasusedinmod_plsqlapplicationstoauthenticateusersdynamicallyagainstusertables•  Canusebasicauthenticationorloginform•  Theauthorize()functioniscalledforeveryrequestImplementationinORDS•  Addsettingtoconnectionpool

ORDS18.3

�<entrykey="security.requestAuthenticationFunction">custom_auth_authorize_simple</entry>

26PL/SQLGatewaysupportforcustomauthentication

ORDS18.3

27PerRequestvalidation

Cachingoftherequestvalidationfunctioncanbedisabled.Thefunctionlimitswhichpublicprocedurescanbecalled.

–  Bydefaultthefunctionresultiscached(assumption:listofallowedprocsisfixed)

–  ProvidemeanstodisablecachingofPL/SQLGatewayprocedurevalidation

•  CustomersuseIPAddresses,Userinfoandheaderstoauthorizeeachrequest

<entrykey="security.requestValidationFunction">wwv_flow_epg_include_modules.authorize</entry>

<entrykey="security.maxEntries">0</entry>

ORDS18.3

28

RESTenabledSQL

29RESTenabledSQL

RESTenabledSQLprovidesaccesstotheSQLengineviaHTTPSUseCases

–  Runsqlstatementsonthecloudviahttps(nosqlnet/jdbcaccess)

–  AlternativetoJDBC/ODBCconnectivityand/ordatabaselinks–  „Three-tier“APEXapplicationswherethedatatables/proceduresdon‘thavetoresideinAPEXDB.

ORDS17.4

30RESTenabledSQL–mechanics

HttpPOSTthestatement(s)andgettheresultinJSON

ORDS17.4

31RESTenabledSQL–mechanics

ORDS17.4

32RESTenabledSQL–SetupinORDS

1.  Addentrytoconnectionpool

2.  (optional)Limitmaxnumberofrows(default:500)

3.  RESTenableallaccessibleschemas4.  AccessschemaswithURL:https://server:port/ords/<schema_alias>/_/sql

<entrykey="restEnabledSql.active">true</entry>

<entrykey="misc.pagination.maxRows">1500</entry>

ORDS17.4

33RESTenabledSQL-Authentication

•  Firstpartyauthentication– ORDScredentialsfile,grantrole„SQLDeveloper“

–  AuthenticationinAppserver,grantrole„SQLDeveloper“–  =>accesstoALLRESTenabledschemas

•  OAuth2ClientCredentials– Grantrole„SQLDeveloper“

•  Schemaauthentication(user/passwordforDBschema)–  Role„SQLDeveloper“willbeassignedautomatically

ORDS17.4

java–jarords.waruserSQLDEV"SQLDeveloper"

34RESTenabledSQL–GettingStarted

•  Documentation:–  https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.4/aelig/rest-enabled-sql-service.html

•  Commands:SQL,PL/SQL,SQLPlus,SQLclcommands–  https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.4/aelig/rest-enabled-sql-service.html#GUID-AE7F4291-02B1-4608-B5B2-F783A15D8AEB

– Nocommandstoaccesshostornetwork

ORDS17.4

35RESTenabledSQL

SampleapplicationbyKrisRice•  http://krisrice.io/2017-09-14-demo-app-for-rest-enabled-sql/

•  https://github.com/oracle/oracle-db-tools/tree/master/ords/rest-sql

ORDS17.4

36

Database REST API

37DatabaseRESTAPI

RESTfulAPIforadministeringtheOracleDatabase.Supportsversions11gR2through19c.UseCases•  YetanotherinterfaceformanagingyourenvironmentsandautomatingthingsinaDevOpsworldusingcURL,REST,andJSON

ORDS19.1

38DatabaseRESTAPI

CurrentlymostlyGETsPOST/DELETEonlyfor

–  Creatingdatapumpjobs

–  PluggableDBlifecyclemanagement

–  Fleetpatching

ORDS19.1

39DatabaseRESTAPI–Setupindatabase

1.  CreateDBAuser

2.  RESTenableDBAuser

createuserdbadmin...;grantdbatodbadmin;grantPDB_DBAtodbadmin;--for>=12c

ORDS_ADMIN.ENABLE_SCHEMA(p_schema=>'DBADMIN',p_url_mapping_pattern=>'dbadmin');

ORDS19.1

40DatabaseRESTAPI–SetupinORDS

1.  Addentrytoconnectionpool

2.  (optional)EnabledatabaseauthenticationifusingDBSchemaauthentication(username/pwd)

or

<entrykey="database.api.enabled">true</entry>

<entrykey="jdbc.auth.enabled">true</entry>

<entrykey="restEnabledSql.active">true</entry>

ORDS19.1

41DatabaseRESTAPI-Authentication

•  Firstpartyauthentication– ORDScredentialsfile,grantrole„SQLAdministrator“

–  AuthenticationinAppserver,grantrole„SQLAdministrator“•  OAuth2ClientCredentials•  Schemaauthentication(user/passwordforDBschema)

–  Role„SQLAdministrator“willbeassignedautomatically

java–jarords.waruserDBADMIN"SQLAdministrator"

ORDS19.1

42DatabaseRESTAPI–URLs

BaseURLfortheAPI(e.g.sampledbauserdbadmin)–  https://server:port/ords/dbadmin/_/db-api/19.1.0/or–  https://server:port/ords/dbadmin/_/db-api/latest/

UsequeryfilterinURL–  https://server:port/ords/dbadmin/_/db-api/latest/database/

objects/indexes/?q={"$eq":{"table_owner":"MDSYS"}}

ORDS19.1

43DatabaseRESTAPI–Documentation

OpenAPI3.0documentation•  https://server:port/ords/dbadmin/_/db-api/latest/metadata-catalog/openapi.json

•  Copy/pastetohttps://editor.swagger.io/

ORDS19.1

44DatabaseRESTAPI–GettingStarted

•  JeffSmith–  https://www.thatjeffsmith.com/archive/2019/04/introducing-the-database-management-rest-api-for-your-oracle-database/

•  OracleDocumentation

ORDS19.1

45

Smaller Features

46InternalHttp-HeaderNameChange

HeaderNameChange,X-APEX*Headersdeprecated–  Internalheadersnotvisibletotheclient...justbetweendatabaseandmidtier

– Movingforward,ORDSsupportsOracleRDBMSindependentofAPEXinstallation

Implementation–  X-APEX-STATUS-CODE=>X-ORDS-STATUS-CODE–  X-APEX-FORWARD=>X-ORDS-FORWARD

ORDS18.3

47Newimplicitvariables

NewimplicitvariableshavebeenaddedtosimplifycodingofRESTfulhandlers.

–  Variables:status_code=>HeaderX-ORDS-STATUS-CODE:forward_location=>HeaderX-ORDS-FORWARD:body_text=>implicitCLOBlike:body

ORDS18.3


ORDS18.3


InaPOSThandleryoucouldaccessthebodyofthepostasaBLOB

ORDS18.3


Gettingstarted–  https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.4/aelig/implicit-parameters.html

–  https://www.thatjeffsmith.com/archive/2018/10/x-ords-forward-ords-response-forward-to-another-resource/

ORDS18.3

51DispatchPL/SQLGatewaycallsviaORDS_PUBLIC_USER

BUG:29197220-DispatchPL/SQLGatewaycallsviaORDS_PUBLIC_USERtominimizenumberofpoolsrequired

ORDS19.2(safe-harbor)

Previously:separatepools–  apex_public_user–  apex_listener–  apex_rest_public_user–  ords_public_user

>=19.2(presumably):unifiedpool–  ords_public_user

Transparentproxyconnecttoapex_public_user

52DispatchPL/SQLGatewaycallsviaORDS_PUBLIC_USER

SetupinORDS1.  Addtoconnectionpool(apex_pu.xml)ordefaults.xml

2.  Deleteallconnectionpoolsbutapex_pu.xml(>=19.2thewizardswillchangeandnotcreatetheotherpoolsanymore)

<entrykey="plsql.gateway.enabled">true</entry>

ORDS19.2(safe-harbor)

53

Changes

54JDKRuntimeRequirement

•  Runtimeenvironment–  Java8(JDK)isarequirement(>=ORDS17.4)–  Java9(JDK)issupported(>=ORDS18.1)

•  SupportedforallJava9certifiedAppServers

55DeprecatedFeatures

•  17.4–  DeprecationofGlassfishSupport

•  18.1–  RemovalofNoSQLsupport–  Parameterapex.docTabledeprecated

•  =>insteaduseowa.docTable

•  Emptycolumnsfixedin19.1


•  18.4– DeprecationofApacheFOPPDFSupport

• Willberemovedin19.2.0•  FutureversionsofOracleApplicationExpresswillmovetoanewmechanismtogeneratePDFresources.


•  18.4– DeprecationofURITemplateSyntaxforORDSBasedRESTServices(e.g/employees/{p_empno})

• Willberemovedin19.4.0•  =>usemoreexpressivenewersyntax:•  (e.g/employees/:p_empno)•  https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.3/ordjv/doc-files/route-patterns.html


•  18.4– DeprecationofRegularExpressionbasedURLMappings

• Willberemovedin19.4.0•  SupportfordefiningURLmappingsusingusingregularexpressionsisdeprecated:

•  Use--typebase-pathor--typebase-urlinstead.java-jarords.warmap-url--typeregex

59Questions?

Opal Consulting Zum Tilmeshof 11 50859 Köln Germany

Email / Website [email protected] www.opal-consulting.de

Haveaproblemyoucannotsolve?OracleAPEXOracleORDS

Scheduleacallwithme!

www.opal-consulting.de/contact

60

Backup

61OptimisticLockingSupport

ORDSimplementsout-of-the-boxstandardsbasedoptimisticlockingsupport.Thisbehavioristotallyoptionalandtheclienthasto„request“it.


1.  GETRequestproducesEtagforresource


2.  PUTRequestsendsEtaginIf-MatchHeader

ORDSchecksIf-MatchHeaderagainstcurrentversion(generatesEtagontheflyfortheresource)

curl-i-XPUT"localhost:8080/ords/ordstest/demo/departments/99"\-H'If-Match:"cBSgLwEXxB9KuQTj+Xtvx0gmONBDvVCK...zIAdEPaLyI8Uw=="'\-H'Content-Type:application/json'\-d'{"deptno":99,"dname":"Accounting","loc":"Cologne"}'


•  Iftheresourcewaschangedinthemeantime,ORDSwillreturnanhttperror

•  ThisishandledbyORDSonly...Nocodingisrequiredbyus

65OptimisticLockingSupport–EnforcingtheIf-MatchHeader

66

OPENAPI2.0documentation(akaswagger)

67OpenAPI2.0(Swagger)Support

ProvidesautomaticdocumentationofRESTfulservicesbasedontheOpenAPI2.0(formerlyswagger)specificationUseCases

–  Facilitatecollaborationandearlytesting–  InteractiveUIhttps://editor.swagger.io/toexploreAPI

ORDS17.4


How/Requirements–  Availableoutofthebox–  ListingofallavailableRESTfulservices(andautorestenabledobjects)

– OriginalMetadataCatalog:http://server:port/ords/<connection>/<schema-alias>/metadata-catalog/

– OpenAPI2.0MetadataCatalog:http://server:port/ords/<connection>/<schema-alias>/open-api-catalog/

ORDS17.4


– Documentationforamodulehttp://server:port/ords/<connection>/<schema-alias>/open-api-catalog/<module_url_path>/

ORDS17.4


Pros/Cons–  AutomaticdocumentationofRESTfulservicesandautorest-objects–  NiceintegrationwithAPEXSQLWorkshop–  InteractiveUIwithswagger-uiand/orhttp://editor.swagger.io–  Itisastart...butthesupportislimited

•  Cannotchangeversionno•  Cannotaddhttpreturncodes...always200•  Notagssupported,onlyuses„default“tag•  Togetthedatatypesright,youwillneedtodeclareallparameters

explicitly•  OnGETrequeststhereisnomodel(columnsandtypes)forthe

resultset

ORDS17.4

71

71

Oracle ORDS - dietmaraust.comdietmaraust.com/wp-content/uploads/2019/06/D_Aust... · mod_plsql...

Documents

Transcript of Oracle ORDS - dietmaraust.comdietmaraust.com/wp-content/uploads/2019/06/D_Aust... · mod_plsql...