oracle ords – quickstart für entwickler · oracle ords – quickstart für entwickler 26.04.2016...
TRANSCRIPT
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 Page 2
DietmarAust
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 3
► 2015DatabaseDeveloperoftheyearintheORDScategory
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 4
Agenda
► WhatisREST?
► WhatisORDS?▪ ComponentsandArchitecture
► ManagementoftheRESTdefini=onswithSQLDeveloperandtheAPI
► UseCases▪ Naviga=on/Links/Filter/Sor=ng/Parameter(Input/Output)
► Security▪ Authen=ca=onandAuthoriza=on
Agenda
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 5
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 6
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 7
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 8
► Methodsimplementaspecificopera=on▪ Uniformopera=onsforallressources▪ GET,POST,PUT,DELETE,OPTIONS,HEAD
WhatisREST?Methods
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 9
► Communica=onofsuccessanderrormessagesthroughstandardHTTPResponsecodes1xx,2xx,3xx,4xx,5xx▪ h\p://www.restapitutorial.com/
h\pstatuscodes.html#
WhatisREST?Methods
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 10
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 11
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 12
WhatisORDS?
► OracleRestDataServices(ORDS)▪ MiddlewareJ2EEcomponentinthe
applica=onserver(WLS,Glassfish,Tomcat)▪ TranslatesURLsintoacallinthedatabase
(eitherselectorstoredprocedurecall)
► Threemajorusecases▪ SupportforOWAtoolkitapplica=ons(will
replacemod_plsql)▪ OracleApplica=onExpress(APEX)▪ RESTfulWebservices
WhatisORDS?
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 13
WhatisORDS?TheHistory
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 14
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 15
► 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
WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 16
► 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)
WhatisORDS?APEXRESTvs.ORDS_METADATARESTSupport
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 17
► HowisaRESTwebservicecallactuallyprocessed?
WhatisORDS?Architecture
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 18
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
WhatisORDS?Architecture
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 19
► TransformtoJSON▪ ReturnJSONbyusingbindvariables(declara=vely)orcreatetheJSONmanually
yourself▪ Declara=veFormats:JSONorCSV,manuallyyoucancreateanything▪ Canchangetheh\preturncodeorseth\pheadervariables
WhatisORDS?Architecture
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 20
► Connec=onPooling▪ ThetargetOracleuser(schema)isac=vatedusingaProxyConnect▪ TheuserORDS_PUBLIC_USERconnecttothedatabaseandthenswitchesitsiden=tyto
thetargetOracleuser▪ Thusweneedfewerconnec=onpoolsandeachconnec=onpoolbecomessmallersince
mul=pleOracleuserscanbeservedwiththesameconnec=onpool▪ EachSQLandPL/SQLstatementisexecutedusingthetheoriginalusersession
WhatisORDS?Architecture
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 21
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 22
ManagementoftheRESTdefini=onswithSQLDeveloperandtheAPI
► ManagementoftheRESTdefini=onswithSQLDeveloper
RESTDefini=onsManagementwithSQLDeveloper
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 23
► ManagementoftheRESTdefini=onswithSQLDeveloper=>connecttoORDSrepositorythroughJ2EEapp
RESTDefini=onsManagementwithSQLDeveloper
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 24
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
RESTDefini=onsManagementwithSQLDeveloper
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 25
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 26
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 27
► Handler–Typ:SQLQuery(legacy)(source_type_query)▪ Containsalinktoitself
RESTDefini=onsHandler-Typen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 28
selectemp.*fromemp
► Handler–TypSQL:SQLQuery(onerow)(legacy)(source_type_query_one_row)
RESTDefini=onsHandler-Typen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 29
selectemp.*fromempwhereempno=:empno
► Handler–TypSQL:Feed(source_type_feed)
RESTDefini=onsHandler-Typen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 30
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)
RESTDefini=onsHandler-Typen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 31
selectemp.*fromemp
► Handler–TypSQL:Collec=onItem(source_type_collec=on_item)▪ Containsalinktothecollec=onitself
RESTDefini=onsHandler-Typen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 32
selectemp.*fromempwhereempno=:empno
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 33
UseCases
Firststep:EnableRESTcapabili=esforaschemainthedatabase
► UsingtheGUI(right-clickontheconnec=on)
► Usingthecommandline/API
UseCasesEnableRESTinSchema
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 34
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 35
ModifyressourcesusingPOST,PUTandDELETE
► Createanewressource(POST)
► Updatearessource(PUT)
► Deletearessource(DELETE)
UseCasesModifyressourcesusingPOST,PUTandDELETE
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 36
Demo
► RendereverythingmanuallywithPL/SQLyourself▪ GETwithTypPL/SQL▪ UseOWAToolkittowriteitout
− APEX_JSON,PL/JSON
− 12cJSONFunk=onen
UseCasesPL/SQLHandler–implementeverythingyourself
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 37
► Displayanimage▪ GEThandler(typeMediaressource)
UseCasesMedia-Ressourcen
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 38
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 39
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 40
► Inputparameters▪ Implicit
− AllvariablesthatarepassedintheURLorinthecontentbody
− :content_type(varchar2,z.B.applica=on/json)
− :body(alsBLOB)
▪ Explicit(usingdeclara=veparameters)− Allregularh\pheadervariables
− AllvariablesthatarepassedintheURLorinthecontentbody
UseCasesParameter
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 41
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 42
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 43
Demo
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 44
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 45
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 46
Security
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 47
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 48
Demo
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 49
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 50
<entrykey="debug.debugger">true</entry><entrykey="debug.printDebugToScreen">true</entry>
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 51
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 52
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 53
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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 54
► 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
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 55
1TagesEntwicklerWorkshopORDS► InKölnam11.Juli
► Themen▪ Installa=on/Konfigura=onfürAPEX/mod_plsqlundREST▪ „RealWorld“Projekt(kompliziertesBeispiel)▪ VerschiedeneUseCasesmitvielenHands-Ons▪ Authen=fizierungmitWLS,GlassfishundTomcat▪ OAUTH2Implemen=erung
1-DayDeveloperWorkshop
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 56
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 57
Contact
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 58
DietmarAustOpal-Consul=ng,Kölnwww.opal-consul=ng.dedaust.blogspot.comdietmar.aust@opal-consul=ng.de
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 59
Auto-REST
QuicklyAuto-RESTenableadatabasetableorview
► Pros:▪ Fastandeasy▪ CandosomecleverthingsusingINSTEAD_OFtriggersontheview
► Cons:▪ Can’tusetheauthen=cated:current_uservariabletofigureouttheuseriden=ty
whichisrequiredforloggingpurposes▪ Currentlyafeatureisunderdiscussiontomake:current_useravailablethrough
sys_contextsimilartoapex.
Auto-REST
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 60
EnableRESTcapabili=esforatableorview
► UsingtheGUI(right-clickonthetable/view)▪ „EnableRESTService“
► Usingthecommandline/API
UseCasesEnableRESTinSchema
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 61
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;
26.04.2016 Oracle ORDS – Quickstart für Entwickler Page 62
Demo