Oracle ORDS – Quickstart für Entwickler · Oracle ORDS – Quickstart für Entwickler 26.04.2016...

OracleORDS–QuickstartfürEntwickler

DietmarAustOpal-Consul=ng,Kölnwww.opal-consul=ng.de

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

► BuildingOraclebasedWebApplica=onssince1997▪  Portal,Forms,Reports,OWAToolkit,nowAPEX!

► 1997-2000:ConsultantatOracleGermany

► Since09/2000:FreelanceConsultant,Since2006–APEXonly!

► Blog:h\p://daust.blogspot.com/

► RegularpresenteratOracleconferences(ODTUG,DOAG,OOW)

► AuthoroftheJasperReportsIntegra=ontoolkit▪  h\p://www.opal-consul=ng.de/tools

DietmarAust

26.04.2016 Oracle ORDS – Quickstart für Entwickler

DietmarAust


► 2015DatabaseDeveloperoftheyearintheORDScategory


Agenda

► WhatisREST?

► WhatisORDS?▪  ComponentsandArchitecture

► ManagementoftheRESTdefini=onswithSQLDeveloperandtheAPI

► UseCases▪  Naviga=on/Links/Filter/Sor=ng/Parameter(Input/Output)

► Security▪  Authen=ca=onandAuthoriza=on

Agenda



WhatisREST?

► Itisanarchitecturalstyleforapplica=ons,neitheraprotocolnoraW3Cstandard

► REST:=Representa=onalStateTransfertermcoinedin2000byRoyFielding▪  h\ps://en.wikipedia.org/wiki/Representa=onal_state_transfer

► Characteris=cs:▪  Stateless(100%oftheapplica=onstateismanagedbytheclient)▪  Basedontheh\pprotocol▪  Highlyscaleable▪  RESTusesh\pmethods(POST,PUT,GET,DELETE,…)toimplementCRUD

opera=ons(Create/Read/Update/Delete)

► Why?▪  Lightweightalterna=vetoRPC(RemoteProcedureCalls)andotherWebServices

(SOAP,WSDL,…)▪  IncreasinglypopularthroughAPIsprovidedbyGoogle,Facebook,Twi\erand

others.

WhatisREST?Defini=on


► Ressourcesprovideservicesandareuniquelyiden=fyable▪  h\p://api.example.com/customers/▪  h\p://api.example.com/customers/1234▪  h\p://api.example.com/customers/1234/orders/

► Mul=pleURIscanpointtothesameressource:▪  h\p://example.org/NewOrleans/traffic/I10▪  h\p://example.org/traffic/NewOrleans/I10

► Wemodeltheressource,nottheac=on!▪  Useofnounsinpluralform▪  PUTh\p://example.com/accounts/12345▪  PUTh\p://example.com/accounts/edit/12345▪  POSTh\p://example.com/accounts/▪  POSTh\p://example.com/accounts/addaccount

WhatisREST?Ressources


► Methodsimplementaspecificopera=on▪  Uniformopera=onsforallressources▪  GET,POST,PUT,DELETE,OPTIONS,HEAD

WhatisREST?Methods


► Communica=onofsuccessanderrormessagesthroughstandardHTTPResponsecodes1xx,2xx,3xx,4xx,5xx▪  h\p://www.restapitutorial.com/

h\pstatuscodes.html#

WhatisREST?Methods


► Representa=onsdeterminehowtheanswerwillbeinterpreted▪  XMLrepresenta=onusingmime-type:text/xml▪  JSONrepresenta=onusingmime-type:

applica=on/json

► Asingleressourcecanprovidemul=pledifferentrepresenta=ons▪  JSON,XML,CSV…▪  Therightrepresenta=onisac=vely„nego=ated“▪  Theclientsendsalistofpreferredmime-types–

theserverrespondswiththebestanswerandsendsthechosenmime-typeinthe„Content-Type“h\pheader.

WhatisREST?Representa=ons



WhatisORDS?

► OracleRestDataServices(ORDS)▪  MiddlewareJ2EEcomponentinthe

applica=onserver(WLS,Glassfish,Tomcat)▪  TranslatesURLsintoacallinthedatabase

(eitherselectorstoredprocedurecall)

► Threemajorusecases▪  SupportforOWAtoolkitapplica=ons(will

replacemod_plsql)▪  OracleApplica=onExpress(APEX)▪  RESTfulWebservices

WhatisORDS?


WhatisORDS?TheHistory


Version Date Description

1.0 2010 First release as Oracle APEX Listener with with support for OWA toolkit used by APEX

1.1 2011 First release with REST support for JSON, Microdata, CSV, Pagination. Also added FOP

2.0 2012 OAuth2 support, Integrated with APEX, Multi Database, SQL Developer integration

2.0.5 2013 Added support for Oracle Pluggable Databases (12c)

2.0.6 2014 Renamed to Oracle REST Data Services to emphasize REST commitment, integration with APEX 4.2 in SQL Workshop

2.0.8 2014 Added REST Filtering

3.0.0 2015 REST AutoTable, NoSQL, DB12 JSON, Bulk loading over REST,…

ORDSiscurrentlytransi2oningawayfromthedependencyonAPEX

► ORDSrequiresarepositorytostorethewebservicedefini=ons

WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport


► ORDS2.0

► Schemas▪  APEX_040200/APEX_050000▪  APEX_LISTENER▪  APEX_REST_PUBLIC_USER

► Configurationusing▪  APEXSQLWorkshop

► ORDS3.0

► Schemas▪  ORDS_METADATA▪  ORDS_PUBLIC_USER

► Configurationusing▪  SQLDeveloper▪  PL/SQLAPI

► APEXRESTsupportintheAPEXSQLWorkshop



► Twodifferentrepositories:APEXRESTandORDS_METADATAREST▪  TypicallybothareinstalledwhenusingAPEX5▪  APEX5requiresthatyourunapex_rest_config.sqlwhichcreatesAPEX_LISTENER

andAPEX_REST_PUBLIC_USER

► TheFuture?▪  NewfeatureswillonlybeaddedtoORDS_METADATAREST

► InwhichrepositorydoIcreatethewebservice?

► APEXREST▪  Integra=onwithAPEXSession

► ORDS_METADATAREST▪  ThenewRESTfunc=onalitybasedonthenewmetadatarepository▪  PL/SQLAPIs(defineandoauth)



► HowisaRESTwebservicecallactuallyprocessed?

WhatisORDS?Architecture


http://myhost/ords/employees/7536SELECT*FROMEMPWHEREEMPNO=:b1

Oracle DB

3. SQL Call over JDBC

Browser

1. Browser RESTful get request

2. ORDS maps to “EMPLOYEES” SQL

4. DB returns JDBC Results

5. JSON

ORDS Runs in WLS, Tomcat, Glassfish container

Oracle REST Data Services

► MapandBind:▪  ImplicitlyaccessallURIparametersintheURLorinthebody(e.g.POSTrequest)

−  Happensautoma=cally,evenJSONParameters(usingContent-Type:applica=on/json)

−  AllparametersareSTRINGs

▪  Explicitparameterspossible−  Properdatatypes

−  Accessheadervariables



► TransformtoJSON▪  ReturnJSONbyusingbindvariables(declara=vely)orcreatetheJSONmanually

yourself▪  Declara=veFormats:JSONorCSV,manuallyyoucancreateanything▪  Canchangetheh\preturncodeorseth\pheadervariables



► Connec=onPooling▪  ThetargetOracleuser(schema)isac=vatedusingaProxyConnect▪  TheuserORDS_PUBLIC_USERconnecttothedatabaseandthenswitchesitsiden=tyto

thetargetOracleuser▪  Thusweneedfewerconnec=onpoolsandeachconnec=onpoolbecomessmallersince

mul=pleOracleuserscanbeservedwiththesameconnec=onpool▪  EachSQLandPL/SQLstatementisexecutedusingthetheoriginalusersession




ManagementoftheRESTdefini=onswithSQLDeveloperandtheAPI

► ManagementoftheRESTdefini=onswithSQLDeveloper

RESTDefini=onsManagementwithSQLDeveloper


► ManagementoftheRESTdefini=onswithSQLDeveloper=>connecttoORDSrepositorythroughJ2EEapp



Oracle REST Data Services

SQL Developer

http/https

APEX_050000

ORDS_METADATA

jdbc

jdbc authenticate and authorize user

Local filestore, Admin user needs role „SQLDeveloper“

► ManagementoftheRESTdefini=onswithSQLDeveloper

► Createuseroncommandline



Schema/Workspace will decide between APEX REST and ORDS REST

##UsertomanageRESTdefinitionsinSQLDeveloperjava-jarords.waruserdietmar.aust"SQLDeveloper”

► ManagementthroughthePL/SQLAPI

► Simplefile…containsallresourcetemplatesandmethodsforamoduleinasingleplace

► Firstwedeletetheexis=ngdefini=onandthenwerecreateitfromscratch

► Verywellsuitedforscriptbaseddeployment

► APIreference(PackageORDS):h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/ords_ref.htm#AELIG90180

RESTDefini=onsManagementthroughtheAPI


► Handler–types▪  SQLQuery(legacy)(source_type_query)▪  SQLQuery(eineZeile)(legacy)(source_type_query_one_row)▪  Feed(source_type_feed)▪  Collec=on(source_type_collec=on_feed)▪  Collec=onItem(source_type_collec=on_item)▪  PL/SQL(source_type_plsql)

−  Generateeverythingmanuallymyself

▪  Media(source_type_media)−  Binaryrepresenta=ons

RESTDefini=onsHandler-Types


► Handler–Typ:SQLQuery(legacy)(source_type_query)▪  Containsalinktoitself

RESTDefini=onsHandler-Typen


selectemp.*fromemp

► Handler–TypSQL:SQLQuery(onerow)(legacy)(source_type_query_one_row)



selectemp.*fromempwhereempno=:empno

► Handler–TypSQL:Feed(source_type_feed)



selectemp.*fromemp

► Handler–TypSQL:Collec=on(source_type_collec=on_feed)

► Completeincl.naviga=onlinks:▪  Self▪  Describedby▪  First(onlybypagina=onorlimit)▪  Next(onlybypagina=onorlimit)▪  Previous(onlybypagina=onorlimit)



selectemp.*fromemp

► Handler–TypSQL:Collec=onItem(source_type_collec=on_item)▪  Containsalinktothecollec=onitself



selectemp.*fromempwhereempno=:empno


UseCases

Firststep:EnableRESTcapabili=esforaschemainthedatabase

► UsingtheGUI(right-clickontheconnec=on)

► Usingthecommandline/API

UseCasesEnableRESTinSchema


BEGINORDS.ENABLE_SCHEMA(p_enabled=>TRUE,p_schema=>'ORDSTEST',p_url_mapping_type=>'BASE_PATH',p_url_mapping_pattern=>'ordstest',p_auto_rest_auth=>FALSE);COMMIT;END;

Implementnaviga=onlinkstonavigatebetweenthedifferentressources

► Linksusedfor:▪  Linktothecurrentrow▪  Linktoanimageoranembeddedlist(ressourceorderscancontainalisttothe

relatedorderitems)▪  Linktotheparent▪  Linktoother“siblings”usingrela=vepaths,e.g.../..

UseCasesNaviga=onandLinks


ModifyressourcesusingPOST,PUTandDELETE

► Createanewressource(POST)

► Updatearessource(PUT)

► Deletearessource(DELETE)

UseCasesModifyressourcesusingPOST,PUTandDELETE


Demo

► RendereverythingmanuallywithPL/SQLyourself▪  GETwithTypPL/SQL▪  UseOWAToolkittowriteitout

−  APEX_JSON,PL/JSON

−  12cJSONFunk=onen

UseCasesPL/SQLHandler–implementeverythingyourself


► Displayanimage▪  GEThandler(typeMediaressource)

UseCasesMedia-Ressourcen


selectmimetype,product_imagefromdemo_product_infowhereproduct_id=to_number(:product_id)

► Pagina=on▪  Allowstopaginatethroughtheresultset▪  Onlyapplicableforhandlertypecollec=on(source_type_collec=on_feed)▪  h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#BABIHBDH▪  Pa\ern:GEThttp://<HOST>:<PORT>/ords/<SchemaAlias>/

<ObjectAlias>/?offset=<Offset>&limit=<Limit>▪  Alsocreatesthelinks“NEXT”,“PREVIOUS”und“FIRST”mit

► Example:

UseCasesPagina=on


► ResultSetFiltering▪  QuerySyntaxtofilteracollec=on▪  Onlyapplicableforhandlertypecollec=on(source_type_collec=on_feed)▪  h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#AELIG90104

► Sor=ng/OrderBy▪  QuerySyntaxtosortacollec=on▪  Onlyapplicableforhandlertypecollec=on(source_type_collec=on_feed)▪  h\p://docs.oracle.com/cd/E56351_01/doc.30/e56293/develop.htm#AELIG90104

UseCasesFilterandSort


► Inputparameters▪  Implicit

−  AllvariablesthatarepassedintheURLorinthecontentbody

−  :content_type(varchar2,z.B.applica=on/json)

−  :body(alsBLOB)

▪  Explicit(usingdeclara=veparameters)−  Allregularh\pheadervariables

−  AllvariablesthatarepassedintheURLorinthecontentbody

UseCasesParameter


► Outputparameters▪  ONLYExplicit(usingdeclara=veparameters)

−  Returnaresponsebysezngasimplebindvariablewhichisthenconvertedautoma=callytoJSONbyORDS(:empno:=99)

−  Setanh\pResponseCode(Pseudo-Header:X-APEX-STATUS-CODE),e.g.:status:=201,403

−  RedirecttoadifferentURL(Pseudo-Header:X-APEX-FORWARD)

−  Setah\pheadervariable

UseCasesParameter



Demo


Security

► Differentwaysofauthen=ca=ngthecurrentuser▪  Authen=ca=onusingtheintegratedpasswordstore(“creden=als”file–just

recommendedfordevelopmentandtestenvironments)▪  Authen=ca=onusingtheapplica=onserver(authen=ca=onisdelegated,e.g.to

Glassfish)

► Authen=ca=onusingOAUTH2▪  Establishedstandard–usedwidely▪  Basicallycontrolsa“session”betweenclient/serverandyous=llneedto

authen=catewiththeappserver

► MoredetailstousingOAUTH2withORDS:Ar=clesfromCarstenCzarski(inGerman,butcanbetranslatedusingGoogleTranslator)▪  h\p://json-rest-oracledb.blogspot.de/2015/12/vorher-anmelden-bi\e-

authen=fizierung.html▪  h\p://json-rest-oracledb.blogspot.de/2016/01/ords-und-3-legged-oauth-so-

gehts.html

Security


► Authoriza=on:=Protectaccesstoressourcesforcertainuserroles

► CreateaROLEfirst(onlypossiblethroughtheAPI)

► CreateaprivilegetoprotectafullmoduleorjustaURIpa\ern

► Cannotrequireprotec=onjustforaspecificmethod,e.g.limitaccesstoPUT,POST,DELETEandallowGETforeverybody.▪  Perhapsusingtwomodules:

−  /public/departments/(implementGEThandler)

−  /protected/departments/(implementGET,POST,PUT,DELETEhandler)

Security


Security



Demo


Debugging/Troubleshoo=ng

► Displayerrormessagesdirectlyinthebrowser(onlyuseondevelopment/testenvironments,notproduc=on!)▪  Modifydefault.xml

► Fullloggingwithalldetailsusingjava.u=l.logging▪  h\ps://cdivilly.wordpress.com/2013/03/08/configuring-logging-in-oracle-

applica=on-express-listener-2-0-1/

Debugging/Troubleshoo=ng


<entrykey="debug.debugger">true</entry><entrykey="debug.printDebugToScreen">true</entry>


Tools

► Commandlinetool:curl-h\ps://curl.haxx.se/

► AdvancedRESTClient(forGoogleChrome)▪  h\ps://chrome.google.com/webstore/detail/advanced-rest-client/

hgmloofddffdnphfgcellkd{{jeloo

► PLSQLlogger▪  h\ps://github.com/OraOpenSource/Logger

Tools



FurtherReading

► Slidestodownload:h\p://daust.blogspot.de

► Wikipedia:h\p://en.wikipedia.org/wiki/Representa=onal_State_Transfer

► REST–APIDesign▪  h\p://www.vinaysahni.com/best-prac=ces-for-a-pragma=c-res|ul-api▪  h\ps://www.thoughtworks.com/de/insights/blog/rest-api-design-resource-

modeling▪  h\p://blog.octo.com/en/design-a-rest-api/▪  h\ps://res|ul-api-design.readthedocs.org/en/latest/intro.html▪  h\p://blog.mwaysolu=ons.com/2014/06/05/10-best-prac=ces-for-be\er-res|ul-

api/

► CarstenCzarskiBlogaboutREST:h\p://json-rest-oracledb.blogspot.de/(canbetranslatedusinggoogletranslator)

FurtherReading


► RESTfulWebServices,byLeonardRichardsonandSamRuby,availablefromO’ReillyMediaath\p://oreilly.com/catalog/9780596529260/

► Thesource:h\p://www.ics.uci.edu/~fielding/pubs/disserta=on/top.htmmostlychapters5and6

► Anice14minutevideointroduc=on:h\p://www.youtube.com/watch?v=YCcAE2SCQ6k

► HTTPspec:h\p://tools.ie|.org/html/rfc2616

► URIspec:h\p://tools.ie|.org/html/rfc3986

► JSONformat:h\p://json.org/

WeitereInforma=onsquellen


1TagesEntwicklerWorkshopORDS► InKölnam11.Juli

► Themen▪  Installa=on/Konfigura=onfürAPEX/mod_plsqlundREST▪  „RealWorld“Projekt(kompliziertesBeispiel)▪  VerschiedeneUseCasesmitvielenHands-Ons▪  Authen=fizierungmitWLS,GlassfishundTomcat▪  OAUTH2Implemen=erung

1-DayDeveloperWorkshop


Contact


DietmarAustOpal-Consul=ng,Kölnwww.opal-consul=ng.dedaust.blogspot.comdietmar.aust@opal-consul=ng.de


Auto-REST

QuicklyAuto-RESTenableadatabasetableorview

► Pros:▪  Fastandeasy▪  CandosomecleverthingsusingINSTEAD_OFtriggersontheview

► Cons:▪  Can’tusetheauthen=cated:current_uservariabletofigureouttheuseriden=ty

whichisrequiredforloggingpurposes▪  Currentlyafeatureisunderdiscussiontomake:current_useravailablethrough

sys_contextsimilartoapex.

Auto-REST


EnableRESTcapabili=esforatableorview

► UsingtheGUI(right-clickonthetable/view)▪  „EnableRESTService“

► Usingthecommandline/API

UseCasesEnableRESTinSchema


BEGINORDS.ENABLE_OBJECT(p_enabled=>TRUE,p_schema=>'ORDSTEST',p_object=>'DEPT',p_object_type=>'TABLE',p_object_alias=>'dept',p_auto_rest_auth=>FALSE);COMMIT;END;


Demo

Oracle ORDS – Quickstart für Entwickler · Oracle ORDS – Quickstart für Entwickler 26.04.2016...

Documents

Transcript of Oracle ORDS – Quickstart für Entwickler · Oracle ORDS – Quickstart für Entwickler 26.04.2016...