Oracle REST Data Services er sannsynligvis den enkleste måten å dele data som ligger i en Oracle database.
Oracle REST Data Services
Mer deling av data er et uttalt mål for mange organisasjoner, spesielt i offentlig sektor. Tilbyr du et REST API til dine data åpner det for at mange kan hente ut det de trenger på en lettvint måte. Skal noen sende data til deg er REST også den enkleste måte å gjøre det på.
REST har mange fordeler, det er utbredt og enkelt, spesielt om man sammenligner med standarder som var mer utbredt før (feks SOAP). Nå tilbys REST stadig mer, se for eksempel på Felles datakatalog på data.norge.no , selv Chuck Norris vitser tilbys nå gjennom REST, se api.chucknorris.io
Oracle tilbyr Oracle REST Data Services (ORDS) uten ekstra lisenskostnader fra oracle.com/ords . Etter flere års erfaring har jeg ikke sett et REST API som henter data fra en Oracle database raskere enn hva ORDS presterer; ytelsen er imponerende selv på beskjeden infrastruktur.
En ferdig installasjon består av to deler, en Java servlet gående på en applikasjonsserver og et nytt API i databasen.
Om du vil overlate installasjon til andre og se på utviklingsmuligheter i ORDS så fortsett lenger nede i artikkelen.
Installasjon
Nedlasting består av kun en zip-fil som pakkes ut på en applikasjonsserver eller annet passende miljø. Bruk denne linken https://download.oracle.com/otn_software/java/ords/ords-latest.zip
så får du alltid siste versjon. Den kan lastes ned direkte med feks wget eller curl uten behov for å klikke seg gjennom en lisensavtale. Dagens versjon, 24.1 er på 116MB komprimert.
Kravene til ORDS er beskjedne, men du må ha Java versjon 11 eller nyere. ORDS installeres gjerne av en databaseadministrator; du trenger SYS passord til databasen som skal brukes. Det finnes noen varianter på hvordan man kan gjøre en installasjon, men her vises den enkleste mulige slik at du kan komme fort i gang og se hvor enkelt det kan gjøres; installasjon i en pluggable database (PDB). I eksempel under brukes wget, men curl -O gjør samme nytte. Miljøet må være klart slik at java ligger i PATH.
wget https://download.oracle.com/otn_software/java/ords/ords-latest.zip
mkdir ords-24.1
mkdir ordsconfig
ln -s ords-24.1 ords-latest
cd ords-latest
unzip ../ords-latest.zip
bin/ords --config ../ordsconfig install
Her får du tre valg:
Enter a number to select the database connection type to use
[1] Basic (host name, port, service name)
[2] TNS (TNS alias, TNS directory)
[3] Custom database URL
Choose [1]:
Velg 1 som foreslått. Oppgi navn til verten hvor databasen, port er typisk 1521 som vist, service navn er service som registrert i database listener. Her bruker jeg en database som jeg opprettet i forbindelse med konferansen neste uke, OUGN 2024
. På spørsmål Enter the administrator username: velg SYS:
Enter the database host name [localhost]: rio
Enter the database listen port [1521]:
Enter the database service name [orcl]: ougn2024
Provide database user name with administrator privileges.
Enter the administrator username: SYS
Enter the database password for SYS AS SYSDBA:
Retrieving information.
ORDS is not installed in the database. ORDS installation is required.
Enter a number to update the value or select option A to Accept and Continue
[1] Connection Type: Basic
[2] Basic Connection: HOST=rio PORT=1521 SERVICE_NAME=ougn2024
Administrator User: SYS AS SYSDBA
[3] Database password for ORDS runtime user (ORDS_PUBLIC_USER): <generate>
[4] ORDS runtime user and schema tablespaces: Default: SYSAUX Temporary TEMP
[5] Additional Feature: Database Actions
[6] Configure and start ORDS in Standalone Mode: Yes
[7] Protocol: HTTP
[8] HTTP Port: 8080
[A] Accept and Continue - Create configuration and Install ORDS in the database
[Q] Quit - Do not proceed. No changes
Choose [A]:
Valgene som foreslått her er OK (Database Actions gir andre muligheter som får bli tema en annen gang.) Den setter et generert passord for en ny bruker ORDS_PUBLIC_USER i databasen. Passordet blir liggende kryptert i en konfigurasjonsfil. Det kan lett endres senere, men bortsatt fra korrekt konfigurasjon så trenger du ikke dette passordet til noe annet. Standard er at ORDS lytter på port 8080, det kan også endres senere. Etter installasjon er ferdig så starter den i Standalone Mode (linje 6). Om du vil kan du avbryte den med Ctrl-C og starte den opp igjen med
bin/ords --config ../ordsconfig serve
I et produksjonsmiljø vil man naturligvis plassere denne i infrastruktur som man ellers vil gjøre med en applikasjon/servlet. I eksempel her kjøres ORDS i standalone mode, men det kan også deployes til Apache Tomcat eller Oracle Weblogic. Og siden den er stateless er det problemfritt å kjøre flere i parallel.
For mer informasjon om installasjon, se Installation and Configuration Guide
Enkel testing av REST i databasen
Eksempler under er gjort i SQL Developer .
Den absolutte enkleste måte å tilby REST på tabeller og views er å bruke AutoREST. Det gjør det mulig å bruke de vanlige operasjonene som GET, POST, PUT og DELETE på tabeller/views og det kan fungere greit til internt bruk om man ikke er redd for uautorisert oppdatering (det kan håndteres med roller senere eller i definisjon av et view som ikke tillater det).
En bruker ORDS_DEMO er opprettet og en CSV-fil med dagens kommuner er lastet ned fra SSB via data.norge.no.
Først aktiveres ORDS på skjemaet (bruker). Det gjøres ved å høyreklikke på connection til databasen og velge nest-siste linje i meny som vist her:
Huk av på Enable schema og ta bort hake ved Authorization required. Du kan velge et annet alias en brukernavn som foreslås, det kan være greit å ikke eksponere brukernavnet ut.
Klikk på Next og Finish for å fullføre denne delen.
Neste trinn er å aktivere REST på en tabell. Det gjøres ved å høyreklikke på tabellen som vist og velge nest-siste valg igjen:
På samme måte aktiveres det ved å klikke på Enable object og ta bort Authorization required
Nå kan data nås med nettleser, curl eller annet egnet verktøy for REST API (Postman, Insomnia og en haug med andre).
ORDS i denne demoen går på en server rio og port 8080. Context root til ORDS servlet er standard /ords/ (kan endres i konfigurasjon). I tillegg valgte jeg data som alias for brukeren og kommuner for denne tabellen. Hele URL-en blir i dette tilfellet http://rio:8080/ords/data/kommuner/. På linux bruker jeg gjerne jq til formatering av JSON:
curl http://rio:8080/ords/data/kommuner/ | jq
Denne vil hente de 25 første radene med linker som støtter paginering, kun de siste linjene er vist her:
Merk at denne inkluderer link til metadata-catalog. Den vil igjen referere til Open API catalog for datasettet.
I tabellen ble kolonnen code satt som primærnøkkel. (CSV-filen ble importert fra SSB med kolonnenavn som i CSV-fil, men tomme kolonner ble droppet). Dette er kommunenummer. Søk på Oslo-kommune som har nummer 0301 kan gjøres med http://rio:8080/ords/data/kommuner/0301. Kolonnen name inneholder kommunenavn. Et søk på eksakt verdi feks Sunnfjord kan gjøres med URL 'http://rio:8080/ords/data/kommuner/?q={"name":"Sunnfjord"}' Mer om søk er vist i Developer’s Guide, 2.3.2
Dersom man ønsker å slette Sunnfjord (hvem har vel ikke det?) som har nummer 4647 kan det gjøres med:
curl -X DELETE 'http://rio:8080/ords/data/kommuner/4647'
Definisjon av REST ved hjelp av SQL og PL/SQL
Om man ønsker større kontroll, som for eksempel bestemme hvilke HTTP operasjoner man tillater kan man bruke PL/SQL-pakken ORDS som ble lagt inn ved installasjon. Faktisk er det denne som blir brukt bak kulissene i SQL Developer. For å se SQL som kjøres klikk på fane SQL på siste side:
Bruk av ORDS-pakken er tema i neste post .