Tabla de contenido
Introducción
Este pequeño taller se realizó para explicar el funcionamiento de un ejemplo básico de la utilización de Oracle Rest Data Services. Para este laboratorio se ha utilizado la siguiente máquina virtual (Creada con virtual box):
Hostname
|
oraclelab
|
Ips
|
10.10.10.101
|
S.O.
|
Oracle Linux 6.9
|
Passwords root
|
root
|
Passwords oracle
|
oracle
|
Oracle_SID
|
ora12cdb
|
PDB
|
pdb2
|
Puerto de listener
|
1521
|
Versión de BD
|
12.1.0.2
|
Path BD
|
/u01/app/oracle/product/12.1.0/db_1
|
Path de ORDS
|
/u01/app/oracle/product/12.1.0/db_1/ords
|
Versión de ORDS
|
18.4.0.r3541002
|
Puerto de ORDS
|
8443
|
Path de descarga de máquina virtual con el ambiente ya configurado (OVA)
|
En la máquina virtual existen variables de ambiente llamadas env_* (las que se encuentran en el directorio de /home/oracle). Cada una de esas variables permiten ingresar a los distintos ambientes ya sea el de grid (Oracle restart) o de los ORACLE_HOME de base de datos.
Prerrequisitos a tener en cuenta:
1.- Tener instalado oracle 12c con opcion de PDB, tener por lo menos 2 bases de datos en PDB (pdb1, pdb2)
2.- Registrar los siguientes nombres en el archivo tnsnames.ora de la base de datos 12c
ORA12CDB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = oraclelab)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = ora12cdb)
)
)
PDB2 =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = oraclelab)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = pdb2)
)
)
Instalación de ORDS (oracle rest data services)
La mayoria de los comandos siguientes es través de SQLPLUS, y serán realizados con el usuario oracle, ocupando el script de variables de ambiente para el motor de base de datos 12cpdb (está ubicado en el mismo $HOME del usuario oracle). La descarga de la ultima versión de ords se hace desde:
Para este ejemplo estamos ocupando la versión: 18.4.0.r3541002
Luego desde el mismo ambiente linux desbloqueamos los siguientes usuarios Atención que en este caso estamos ocupando el pdb2 como pluggable database para el actual ejercicio:
ALTER SESSION SET CONTAINER = pdb2;
ALTER USER APEX_LISTENER IDENTIFIED BY oracle ACCOUNT UNLOCK;
ALTER USER APEX_PUBLIC_USER IDENTIFIED BY oracle ACCOUNT UNLOCK;
ALTER USER APEX_REST_PUBLIC_USER IDENTIFIED BY oracle ACCOUNT UNLOCK;
-- si alguno de los comandos anteriores da error: ORA-65066 ejecutarlo a nivel de CDB con la opcion container=all
Posteriormente copiamos el zip de ords y lo copiamos al ORACLE_HOME de la base 12c. Dejaremos el zip en esta ruta:
$ORACLE_HOME/ords
Deberiamos comprobar que la version minima que tengamos instalada sea java 1.8
[oracle@oraclelab tmp]$ java -version
openjdk version "1.8.0_201"
OpenJDK Runtime Environment (build 1.8.0_201-b09)
OpenJDK 64-Bit Server VM (build 25.201-b09, mixed mode)
Comprobamos la versión de ords (Recordar que de ahora en adelante estaremos sobre la ruta $ORACLE_HOME/ords que es dónde dejamos descomprimido el ZIP)
[oracle@oraclelab ords]$ java -jar ords.war version
Oracle REST Data Services 18.4.0.r3541002
[oracle@oraclelab ords]$
Antes de continuar con lo siguiente verificar que el usuario ORDS_PUBLIC_USER no exista en el motor para que lo siguiente no falle. Poner mucha atención en los parámetros de entrada que le vamos pasando a la configuración. Comparar lo que vamos ingresando con lo que está en las siguientes evidencias:
[oracle@oraclelab ords]$ java -jar ords.war install advanced
Enter the name of the database server [localhost]:oraclelab
Enter the database listen port [1521]:
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Enter the database service name:ora12cdb
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:
Retrieving information.
Requires SYS AS SYSDBA to verify Oracle REST Data Services schema.
Enter the database password for SYS AS SYSDBA:
Confirm password:
Retrieving information....
Your database connection is to a CDB.
PDB PDB2 - install ORDS 18.4.0.r3541002
PDB PDB3 - install ORDS 18.4.0.r3541002
Enter 1 if you want to install ORDS or 2 to skip this step [1]:
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step.
If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]:
Enter the PL/SQL Gateway database user name [APEX_PUBLIC_USER]:oracle
Enter the database password for oracle:
Confirm password:
Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:oracle
Invalid value. Try again.
Enter 1 to specify passwords for Application Express RESTful Services database users (APEX_LISTENER, APEX_REST_PUBLIC_USER) or 2 to skip this step [1]:1
Enter the database password for APEX_LISTENER:
Confirm password:
Enter the database password for APEX_REST_PUBLIC_USER:
Confirm password:
Mar 07, 2019 1:02:06 PM
INFO: reloaded pools: []
Installing Oracle REST Data Services version 18.4.0.r3541002 in PDB2
... Log file written to /home/oracle/ords_cdb_upgrade_core_PDB2_2019-03-07_130207_00021.log
... Verified database prerequisites
... Created Oracle REST Data Services schema
... Created Oracle REST Data Services proxy user
... Granted privileges to Oracle REST Data Services
... Created Oracle REST Data Services database objects
... Log file written to /home/oracle/ords_cdb_upgrade_datamodel_PDB2_2019-03-07_130223_00979.log
... Log file written to /home/oracle/ords_cdb_upgrade_apex_PDB2_2019-03-07_130230_00615.log
Completed installation for Oracle REST Data Services version 18.4.0.r3541002. Elapsed time: 00:00:29.995
Installing Oracle REST Data Services version 18.4.0.r3541002 in PDB3
... Log file written to /home/oracle/ords_cdb_upgrade_core_PDB3_2019-03-07_130237_00009.log
... Verified database prerequisites
... Created Oracle REST Data Services schema
... Created Oracle REST Data Services proxy user
... Granted privileges to Oracle REST Data Services
... Created Oracle REST Data Services database objects
... Log file written to /home/oracle/ords_cdb_upgrade_datamodel_PDB3_2019-03-07_130254_00038.log
... Log file written to /home/oracle/ords_cdb_upgrade_apex_PDB3_2019-03-07_130300_00541.log
Completed installation for Oracle REST Data Services version 18.4.0.r3541002. Elapsed time: 00:00:27.873
Completed CDB upgrade for Oracle REST Data Services version 18.4.0.r3541002.
Total Elapsed time: 00:00:57.892
Enter 1 if you wish to start in standalone mode or 2 to exit [1]:2
Posteriormente omprobamos la configuracion anteriormente creada:
[oracle@oraclelab ords]$ java -jar ords.war configdir
Mar 07, 2019 1:05:47 PM
INFO: The config.dir value is /u01/app/oracle/product/12.1.0/dbhome_1/ords/config
Procedemos a evantar ords en modo standalone. Indicamos puerto y lo dejamos sin https para efectos de las pruebas básicas. Quedara tomada la ventana pues dejara arriba el servicio, luego lo podemos dejar con nohup si lo deseamos. (en este ejemplo ocupamos el puerto 8443):
[oracle@oraclelab ords]$ java -jar ords.war configdir
Mar 07, 2019 1:05:47 PM
INFO: The config.dir value is /u01/app/oracle/product/12.1.0/dbhome_1/ords/config
[oracle@oraclelab ords]$ java -jar ords.war standalone
Enter 1 if using HTTP or 2 if using HTTPS [1]:
Enter the HTTP port [8080]:8443
2019-03-07 13:06:42.568:INFO::main: Logging initialized @25852ms to org.eclipse.jetty.util.log.StdErrLog
Mar 07, 2019 1:06:42 PM
No olvidar lo siguiente:
[oracle@oraclelab ords]$ java -jar ords.war set-property db.serviceNameSuffix ''
Mar 07, 2019 2:21:38 PM oracle.dbtools.rt.config.setup.SetProperty execute
INFO: Modified: /u01/app/oracle/product/12.1.0/dbhome_1/ords/config/ords/defaults.xml, setting: db.serviceNameSuffix =
[oracle@oraclelab ords]$
Ahora agregamos nuestra pluggable pdb2 de prueba que usaremos. Atención que cuando pregunte por el servicename hay que poner pdb2 y no el ora12cdb. Queremos autenticar el Rest contra el pdb no contra el CDB:
[oracle@oraclelab ords]$ java -jar ords.war setup --database pdb2
Enter the name of the database server [oraclelab]:
Enter the database listen port [1521]:
Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Enter the database service name [pdb2]:
Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:1
Enter the database password for ORDS_PUBLIC_USER:
Confirm password:
Retrieving information.
Requires SYS AS SYSDBA to verify Oracle REST Data Services schema.
Enter the database password for SYS AS SYSDBA:
Confirm password:
Retrieving information....
Completed verifying Oracle REST Data Services schema version 18.4.0.r3541002.
Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step.
If using Oracle Application Express or migrating from mod_plsql then you must enter 1 [1]:2
Mar 07, 2019 2:25:01 PM
INFO: reloaded pools: [|apex||, |apex|al|, |apex|pu|, |apex|rt|, |pdb2|pu|]
Mar 07, 2019 2:25:01 PM oracle.dbtools.rt.config.setup.SchemaSetup install
INFO: Oracle REST Data Services schema version 18.4.0.r3541002 is installed.
Lo anterior ha creado el siguiente archivo descrito abajo. Verificar muy importante que tenga el servicename apuntando al pdb y no el Containerr (ora12cdb en nuestro caso):
[oracle@oraclelab ords]$ cat $ORACLE_HOME/ords/config/ords/conf/pdb2_pu.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>Saved on Thu Mar 07 14:25:01 CLST 2019</comment>
<entry key="db.password">@0515E443FFA06071EA4C7F0A422525B801</entry>
<entry key="db.servicename">pdb2</entry>
<entry key="db.username">ORDS_PUBLIC_USER</entry>
</properties>
Definimos la nueva ruta de url mapping:
[oracle@oraclelab ords]$ java -jar ords.war map-url --type base-path /pdb2 pdb2
Mar 07, 2019 2:27:10 PM
INFO: Creating new mapping from: [base-path,/pdb2] to map to: [pdb2, null, null]
[oracle@oraclelab ords]$
Lo anterior creará un nuevo url mapping en el siguiente archivo: (revisar que la ruta exista)
cat /u01/app/oracle/product/12.1.0/dbhome_1/ords/config/ords/url-mapping.xml
Configuración de primer test con ORDS
A continuación muchos de lo elementos siguientes se deben realizar con sqlplus (mismo usuario oracle bajo las variables de ambiente de la base 12c con PDB)
Nota: En este apartado estaremos ocupando los objetos del esquema SH. Pueden ocupar el que ustedes estimen conveniente, teniendo la precaución de reemplazar el esquema en cada comando que se usará de ahora en adelante.
sqlplus "sys@pdb2 as sysdba"
EXECUTE ORDS.DROP_REST_FOR_SCHEMA('SH');
exec ords.enable_schema(p_schema => 'SH', p_url_mapping_type => 'BASE_PATH', p_url_mapping_pattern => 'sh');
commit;
-- si lo anterior da error hay que ejecutarlo como una cuenta con rol DBA
Lo siguiente nos tiene que devolver la siguiente consulta:
SELECT parsing_schema, status, auto_rest_auth FROM ords_metadata.ords_schemas;
PARSING_SCHEMA STATUS AUTO_REST_AUTH
ORDS_METADATA DISABLED ENABLED
SH ENABLED DISABLED
Nos como el usuario SH para crear los nuevos servicios, siempre desde es el esquema y conectado al pdb2. No olvidar el commit:
conn sh@pdb2
EXEC ords.define_service(p_module_name => 'examples3', p_base_path => '/examples3/', p_method => 'GET', p_pattern => '/greeting/',p_source => 'select sysdate from dual');
commit;
EXEC ords.define_service(p_module_name => 'productos', p_base_path => '/productos/', p_method => 'GET', p_pattern => '/greeting/',p_source => 'select PROD_NAME from products');
commit;
En el ejemplo anterior hemos creado dos servicios uno que nos devolverá la hora y el otro que nos devolverá un listado de productos.
Verificamos las siguients consultas que nos deberian mostar los servicios creados:
SELECT id, parsing_schema, TYPE, pattern, status, auto_rest_auth FROM user_ords_schemas;
SELECT id, name, uri_prefix, items_per_page, status FROM user_ords_modules;
SELECT id, module_id, uri_template FROM user_ords_templates;
SELECT id, template_id, source_type, method, source FROM user_ords_handlers;
Verificamos con curl el funcionamiento de los servicios para ver sin problemas el contenido. Deberiamos ver la fecha y el listado de productos. Esto mismo lo pueden ver desde un browser de internet
Format: http://<hostname>:<puerto>/ords/<service_name_db>/<nombreservicio>/<patron_creado>
curl http://oraclelab:8443/ords/pdb2/sh/examples3/greeting/
curl http://oraclelab:8443/ords/pdb2/sh/productos/greeting/
Ante cualquier dificultad metemos un debug para ir viendo los posibles errores (problemas de privilegio, usuarios, objetos inexistentes, etc.)
java -jar ords.war set-property debug.debugger true
java -jar ords.war set-property debug.printDebugToScreen true
Bajamos y submimos el servicio nuevamente para que se active el debug.
Habilitación de Rest Enabled SQL Service
Existe una opción bastante interesante que se puede ocupar que es REST-Enabled SQL Service, que permite visualizar como servicio el restulado de querys dinamicas. Veamos como funciona:
Debemos habilitar la opción restEnabledSql a nivel del servicio para esto
[oracle@oraclelab ords]$ java -jar ords.war set-property restEnabledSql.active true
Mar 07, 2019 6:06:30 PM oracle.dbtools.rt.config.setup.SetProperty execute
INFO: Modified: /u01/app/oracle/product/12.1.0/dbhome_1/ords/config/ords/defaults.xml, setting: restEnabledSql.active = true
[oracle@oraclelab ords]$
A nivel de sqlplus habilitamos nuevamente el servicio para el esquema sh:
CONNECT sh@pdb2/sh;
exec ords.enable_schema;
commit;
Invocamos la url indicando --user username:password, en data-binary indicamos la query a ejecutar y en -h indicamos el tipo de contenido a tratar. Finalmente con el parámetro -k indicamos la ruta. El formato seria el siguinte: <hostname>:<puerto>/ords/<servicename>/<aliasdelesquema>/_/sql
Ejemplo del contenido:
[oracle@oraclelab ords]$ curl -i -X POST --user sh:sh --data-binary "select sysdate from dual" -H "Content-Type: application/sql" -k http://oraclelab:8443/ords/pdb2/sh/_/sql
HTTP/1.1 200 OK
Date: Thu, 07 Mar 2019 21:59:15 GMT
Content-Type: application/json
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked
{"env":{"defaultTimeZone":"America/Santiago"},"items":[{"statementId":1,"statementType":"query","statementPos":{"startLine":1,"endLine":2},"statementText":"select sysdate from dual","resultSet":{"metadata":[{"columnName":"SYSDATE","jsonColumnName":"sysdate","columnTypeName":"DATE","precision":0,"scale":0,"isNullable":1}],"items":[{"sysdate":"2019-03-07T21:59:15Z"}],"hasMore":false,"limit":10000,"offset":0,"count":1},"response":[],"result":0}]}[oracle@oraclelab ords]$
Revisar el siguiente link para más detalle acerca de esto último:
Espero que haya sido útil este brevísimo testing con ORDS.
Saludos, Felipe.
