API de REST de DBMS

Requisitos

Como desarrollador, puede utilizar procedimientos DBMS_CLOUD con instancias de Autonomous Database desplegadas en Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

En función de la opción de despliegue, se deben cumplir los siguientes requisitos para utilizar las API de REST DBMS_CLOUD con proveedores de servicios de Amazon S3, Azure Blob Storage y Google Cloud Storage.

Oracle Public Cloud o multinube
Exadata Cloud at Customer

El administrador del conjunto debe haber configurado una conectividad saliente mediante un gateway de NAT, como se describe a continuación:

Cree un gateway de NAT en la red virtual en la nube (VCN) en la que residan los recursos de Autonomous Database siguiendo las instrucciones de Creación de un gateway de NAT de la Documentación de Oracle Cloud Infrastructure.
Después de crear el gateway de NAT, agregue una regla de ruta y una regla de seguridad de salida a cada subred (en la VCN) en la que residan los recursos de Autonomous Database para que estos recursos puedan utilizar el gateway para obtener una clave pública de la instancia de Azure AD:
1. Vaya a la página Detalles de subred de la subred.
2. En el separador Información de Subred, haga clic en el nombre de la Tabla de Direcciones de la subred para mostrar su página Detalles de Tabla de Direcciones.
3. En la tabla de Reglas de ruta existentes, compruebe si ya hay una regla con las siguientes características:
  - Destino: 0.0.0.0/0
  - Tipo de destino: gateway de NAT
  - Destino: nombre del gateway de NAT que acaba de crear en la VCN
  Si dicha regla no existe, haga clic en Agregar reglas de ruta y agregue una regla de ruta con estas características.
4. Vuelva a la página Detalles de subred de la subred.
5. En la tabla Listas de seguridad de la subred, haga clic en el nombre de la lista de seguridad de la subred para mostrar su página Detalles de lista de seguridad.
6. En el menú lateral, en Recursos, haga clic en Reglas de salida.
7. En la tabla de Reglas de salida existentes, compruebe si ya hay una regla con las siguientes características:
  - Tipo de destino: CIDR
  - Destino: 0.0.0.0/0
  - Protocolo IP: TCP
  - Rango de puertos de origen: 443
  - Rango de puertos de destino: todos
  Si dicha regla no existe, haga clic en Agregar Reglas de Salida y agregue una regla de salida con estas características.

La configuración del proxy HTTP en el entorno debe permitir que la base de datos acceda al proveedor de servicios en la nube.

El administrador del conjunto define esta configuración al crear la infraestructura de Exadata Cloud@Customer, como se describe en Uso de la consola para aprovisionar Exadata Database Service on Cloud@Customer.

Note:

La configuración de red, incluido el proxy HTTP, solo se puede editar hasta que la infraestructura de Exadata tenga el estado Necesita activación. Una vez activada, no puede editar esa configuración.

La configuración de un proxy HTTP para una infraestructura de Exadata ya aprovisionada necesita una solicitud de servicio (SR) en My Oracle Support. Consulte Creación de una solicitud de servicio en My Oracle Support para obtener más información.

API de REST de DBMS_CLOUD

En esta sección se tratan las API de REST de DBMS_CLOUD que se proporcionan con Autonomous Database.

API de REST	Descripción
Función GET_RESPONSE_HEADERS	Esta función devuelve las cabeceras de respuesta HTTP como datos de JSON en un objeto JSON en Autonomous Database.
Función GET_RESPONSE_TEXT	Esta función devuelve la respuesta HTTP en formato TEXT (`VARCHAR2` o `CLOB`) en Autonomous Database. Normalmente, la mayoría de las API de REST en la nube devuelven una respuesta JSON en formato de texto. Esta función es útil si espera que la respuesta HTTP esté en formato de texto.
Función GET_API_RESULT_CACHE_SIZE	Esta función devuelve el tamaño de caché de resultados configurado.
Función y procedimiento SEND_REQUEST	Esta función inicia una solicitud HTTP, obtiene la respuesta y finaliza la respuesta en Autonomous Database. Esta función proporciona un flujo de trabajo para enviar una solicitud de API de REST en la nube con argumentos y un código de respuesta de devolución y carga útil.
Procedimiento SET_API_RESULT_CACHE_SIZE	Con este procedimiento se define el tamaño máximo de caché para la sesión actual.

Visión general de la API de REST de DBMS_CLOUD

Cuando utilice PL/SQL en su aplicación y necesite llamar a las API de REST en la nube, puede utilizar DBMS_CLOUD.SEND_REQUEST para enviar las solicitudes de la API de REST.

Las funciones de la API de REST de DBMS_CLOUD permiten realizar solicitudes HTTP mediante DBMS_CLOUD.SEND_REQUEST, así como obtener y guardar resultados. Estas funciones proporcionan una API genérica que permite llamar a cualquier API de REST con los siguientes servicios en la nube soportados:

Oracle Cloud Infrastructure
Consulte Puntos finales y referencia de API para obtener información sobre las API de REST de Oracle Cloud Infrastructure.
Azure Cloud ^{Nota al pie 1}
Consulte Referencia de API de REST de Azure para obtener información sobre las API de REST de Azure.

Constantes de la API de REST de DBMS_CLOUD

Describe las constantes de DBMS_CLOUD para realizar solicitudes HTTP mediante DBMS_CLOUD.SEND_REQUEST.

DBMS_CLOUD soporta los métodos HTTP GET, PUT, POST, HEAD y DELETE. El método de la API de REST que se va a utilizar para una solicitud HTTP se suele documentar en la documentación de la API de REST de Cloud.

Nombre	Tipo	Valor
`METHOD_DELETE`	`VARCHAR2(6)`	`'DELETE'`
`METHOD_GET`	`VARCHAR2(3)`	`'GET'`
`METHOD_HEAD`	`VARCHAR2(4)`	`'HEAD'`
`METHOD_POST`	`VARCHAR2(4)`	`'POST'`
`METHOD_PUT`	`VARCHAR2(3)`	`'PUT'`

Caché de resultados de la API de REST de DBMS_CLOUD

Puede guardar los resultados de la API de REST de DBMS_CLOUD cuando defina el parámetro cache en true con DBMS_CLOUD.SEND_REQUEST. En la vista SESSION_CLOUD_API_RESULTS se describen las columnas que puede utilizar al guardar los resultados de la API de REST.

Por defecto, las llamadas a la API de REST DBMS_CLOUD no guardan los resultados de la sesión. En este caso, utilice la función DBMS_CLOUD.SEND_REQUEST para devolver los resultados.

Al utilizar DBMS_CLOUD.SEND_REQUEST y definir el parámetro cache en TRUE, los resultados se guardan y puede ver los resultados anteriores en la vista SESSION_CLOUD_API_RESULTS. Guardar y consultar los resultados históricos de las solicitudes de la API de REST DBMS_CLOUD puede ser útil cuando necesite trabajar con los resultados anteriores en sus aplicaciones.

Por ejemplo, para consultar los resultados recientes de la API de REST DBMS_CLOUD, utilice la vista SESSION_CLOUD_API_RESULTS:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

Al guardar los resultados de la API de REST DBMS_CLOUD con DBMS_CLOUD.SEND_REQUEST, los datos guardados solo están disponibles en la misma sesión (conexión). Una vez finalizada esta, los datos guardados ya no estarán disponibles.

Utilice DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE y DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE para ver y definir el tamaño de la caché de la API de REST DBMS_CLOUD y para desactivar el almacenamiento en caché.

DBMS_CLOUD Parámetro cache_scope de resultados de la API de REST

Al guardar los resultados de la API de REST DBMS_CLOUD con DBMS_CLOUD.SEND_REQUEST, se proporciona acceso a los resultados en SESSION_CLOUD_API_RESULTS según el valor de cache_scope.

Por defecto, el valor de cache_scope es 'PRIVATE' y solo el usuario actual de la sesión puede acceder a los resultados. Si define cache_scope en 'PUBLIC', todos los usuarios de la sesión pueden acceder a los resultados. El valor por defecto para cache_scope especifica que cada usuario solo puede ver los resultados de la API de REST de DBMS_CLOUD.SEND_REQUEST generados por los procedimientos que llaman con derechos del que hace la llamada. Al llamar a DBMS_CLOUD.SEND_REQUEST en una sesión, hay tres posibilidades que determinan si el usuario actual puede ver los resultados en la caché, según el valor cache_scope:

Ejecute directamente DBMS_CLOUD.SEND_REQUEST como sentencia de nivel superior y la llamada a DBMS_CLOUD.SEND_REQUEST y los resultados de la API de REST se guardan con el mismo nombre de usuario. En este caso, tiene acceso a todos los resultados con el valor por defecto, 'PRIVATE', definido para cache_scope.
Usted escribe un procedimiento de derechos del responsable de llamada de envoltorio y, como usuario actual, la llamada con DBMS_CLOUD.SEND_REQUEST llama al procedimiento y los resultados de la API de REST se guardan con el mismo nombre de usuario. En este caso, y tiene acceso a todos los resultados con el valor por defecto, 'PRIVATE', definido para cache_scope.
Escribe un procedimiento de derechos del responsable de la definición de envoltorio y el procedimiento es propiedad de otro usuario. Al llamar a DBMS_CLOUD.SEND_REQUEST dentro del procedimiento, los resultados se guardan con el nombre de usuario del propietario del procedimiento.

En este caso, un usuario con derechos de otro responsable de la definición llama a DBMS_CLOUD.SEND_REQUEST, y los resultados de la API de REST se guardan con ese propietario del procedimiento de definición. En este caso, por defecto, cuando cache_scope es PRIVATE', la sesión del invocador no puede ver los resultados.

Si el propietario del procedimiento del responsable de la definición desea que los resultados estén disponibles para cualquier usuario de sesión de llamada, debe definir cache_scope en 'PUBLIC' en DBMS_CLOUD.SEND_REQUEST.

Vista SESSION_CLOUD_API_RESULTS de la API de REST de DBMS_CLOUD

Puede guardar los resultados de la API de REST de DBMS_CLOUD cuando defina el parámetro cache en true con DBMS_CLOUD.SEND_REQUEST. En la vista SESSION_CLOUD_API_RESULTS se describen las columnas que puede utilizar al guardar los resultados de la API de REST.

La vista SESSION_CLOUD_API_RESULTS es la vista creada si almacena en caché los resultados con DBMS_CLOUD.SEND_REQUEST. Puede consultar los resultados históricos que pertenecen a la sesión de usuario. Cuando finaliza la sesión, se depuran los datos de SESSION_CLOUD_API_RESULTS.

Columna	Descripción
`URI`	URL de solicitud de la API de REST de `DBMS_CLOUD`
`TIMESTAMP`	Registro de tiempo de respuesta de la API de REST de `DBMS_CLOUD`
`CLOUD_TYPE`	El tipo de nube de la API de REST de `DBMS_CLOUD`, como Oracle Cloud Infrastructure y AZURE_BLOB
`REQUEST_METHOD`	Método de solicitud de la API de REST de `DBMS_CLOUD`, como `GET`, `PUT`, `HEAD`
`REQUEST_HEADERS`	Cabeceras de solicitud de la API de REST de `DBMS_CLOUD`
`REQUEST_BODY_TEXT`	Cuerpo de solicitud de la API de REST de `DBMS_CLOUD` en `CLOB`
`RESPONSE_STATUS_CODE`	Código de estado de la respuesta de la API de REST de `DBMS_CLOUD`, como `200(OK)`, `404(Not Found)`
`RESPONSE_HEADERS`	Cabeceras de respuesta de la API de REST de `DBMS_CLOUD`
`RESPONSE_BODY_TEXT`	Cuerpo de respuesta de la API de REST de `DBMS_CLOUD` en `CLOB`
`SCOPE`	`cache_scope` definido por `DBMS_CLOUD.SEND_REQUEST`. Los valores válidos son `PUBLIC` o `PRIVATE`.

Función GET_RESPONSE_HEADERS

Esta función devuelve las cabeceras de respuesta HTTP como datos de JSON en un objeto JSON.

Sintaxis

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

Parámetros

parámetro	Descripción
`resp`	Tipo de respuesta HTTP devuelta de `DBMS_CLOUD.SEND_REQUEST`.

Excepciones

Excepción	Error	Descripción
`invalid_response`	`ORA-20025`	Se ha transferido un objeto de tipo de respuesta no válido a `DBMS_CLOUD.GET_RESPONSE_HEADERS`.

Función GET_RESPONSE_TEXT

Esta función devuelve la respuesta HTTP en formato TEXT (VARCHAR2 o CLOB). Normalmente, la mayoría de las API de REST en la nube devuelven una respuesta JSON en formato de texto. Esta función es útil si espera que la respuesta HTTP esté en formato de texto.

Sintaxis

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

Parámetros

parámetro	Descripción
`resp`	Tipo de respuesta HTTP devuelta de `DBMS_CLOUD.SEND_REQUEST`.

Excepciones

Excepción	Error	Descripción
`invalid_response`	`ORA-20025`	Se ha transferido un objeto de tipo de respuesta no válido a `DBMS_CLOUD.GET_RESPONSE_TEXT`.

Función GET_API_RESULT_CACHE_SIZE

Esta función devuelve el tamaño de caché de resultados configurado. El valor de tamaño de caché solo se aplica a la sesión actual.

Sintaxis

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

Función y procedimiento SEND_REQUEST

Esta función y procedimiento inicia una solicitud HTTP, obtiene la respuesta y finaliza la respuesta. Esta función proporciona un flujo de trabajo para enviar una solicitud de API de REST en la nube con argumentos y la función devuelve un código de respuesta y una carga útil. Si utiliza el procedimiento, puede ver los resultados y los detalles de respuesta de los resultados guardados con la vista SESSION_CLOUD_API_RESULTS.

Sintaxis

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

Parámetros

parámetro	Descripción
`credential_name`	Nombre de la credencial para la autenticación con la API nativa en la nube correspondiente.
`uri`	URI HTTP para realizar la solicitud.
`method`	Método de solicitud HTTP: `GET`, `PUT`, `POST`, `HEAD` o `DELETE`. Utilice la constante de paquete `DBMS_CLOUD` para especificar el método. Consulte Constantes de la API de REST de DBMS_CLOUD para obtener más información.
`headers`	Cabeceras de solicitud HTTP para la API nativa en la nube correspondiente en formato JSON. Las cabeceras de autenticación se definen automáticamente; solo se transfieren cabeceras personalizadas.
`async_request_url`	Una URL de solicitud asíncrona. Para obtener la URL, seleccione la API de solicitud de la lista de API (consulte https://docs.cloud.oracle.com/en-us/iaas/api/). A continuación, desplácese para buscar la API para su solicitud en el panel izquierdo. Por ejemplo, API de Database Services → Autonomous Database → StopAutonomousDatabase. En esta página se muestra el directorio raíz de la API (y el punto final base). A continuación, agregue el punto final base con la ruta relativa obtenida para el enlace WorkRequest de la solicitud de trabajo.
`wait_for_states`	La espera de estados es un estado de tipo: `DBMS_CLOUD_TYPES.wait_for_states_t`. Los siguientes son valores válidos para los estados esperados: '`ACTIVE`', '`CANCELED`', '`COMPLETED`', '`DELETED`', '`FAILED`' y '`SUCCEEDED`'. Se permiten varios estados para `wait_for_states`. El valor por defecto de `wait_for_states` es esperar a cualquiera de los estados esperados: '`ACTIVE`', '`CANCELED`', '`COMPLETED`', '`DELETED`', '`FAILED`' o '`SUCCEEDED`'.
`timeout`	Especifica el timeout, en segundos, para solicitudes asíncronas con los parámetros `async_request_url` y `wait_for_states`. El valor por defecto es `0`. Esto indica que se debe esperar a que finalice la solicitud sin que se produzca ningún timeout.
`cache`	Si `TRUE` especifica que la solicitud se debe almacenar en la caché de API de resultados de REST. El valor por defecto es `FALSE`, lo que significa que las solicitudes de API de REST no se almacenan en caché.
`cache_scope`	Especifica si todos pueden tener acceso a esta caché de resultados de solicitud. Valores válidos: `"PRIVATE"` y `"PUBLIC"`. El valor por defecto es `"PRIVATE"`.
`body`	Cuerpo de solicitud HTTP para las solicitudes `PUT` y `POST`.

Excepciones

Excepción	Error	Descripción
`invalid_req_method`	`ORA-20023`	El método de solicitud transferido a `DBMS_CLOUD.SEND_REQUEST` no es válido.
`invalid_req_header`	`ORA-20024`	Las cabeceras de solicitud transferidas a `DBMS_CLOUD.SEND_REQUEST` no tienen un formato JSON válido.

Notas de uso

Si utiliza Oracle Cloud Infrastructure, debe utilizar un valor de credencial basada en clave de firma para credential_name. Consulte Procedimiento CREATE_CREDENTIAL para obtener más información.
Los parámetros opcionales async_request_url, wait_for_states y timeout permiten gestionar las solicitudes de larga ejecución. Con este formato asíncrono de send_request, la función espera el estado de finalización especificado en wait_for_states antes de volver. Con estos parámetros en la solicitud de envío, transfiera los estados de devolución esperados en el parámetro wait_for_states y utilice el parámetro async_request_url para especificar una solicitud de trabajo asociada, la solicitud no se devuelve inmediatamente. En su lugar, la solicitud sondea async_request_url hasta que el estado de devolución sea uno de los estados esperados o se supere timeout (timeout es opcional). Si no se especifica timeout, la solicitud espera hasta que se produzca un estado encontrado en wait_for_states.

Procedimiento SET_API_RESULT_CACHE_SIZE

Con este procedimiento se define el tamaño máximo de caché para la sesión actual. El valor de tamaño de caché solo se aplica a la sesión actual.

Sintaxis

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

Parámetros

parámetro Descripción

parámetro	Descripción
`cache_size`	Defina el tamaño máximo de caché en el valor especificado `cache_size`. Si el nuevo tamaño máximo de caché es menor que el tamaño de caché actual, los registros más antiguos se borran hasta que el número de filas sea igual al tamaño máximo de caché especificado. El valor máximo es `10000`. Si el tamaño de caché se define en `0`, el almacenamiento en caché se desactiva en la sesión. El tamaño de caché por defecto es `10`.

cache_size

Defina el tamaño máximo de caché en el valor especificado cache_size. Si el nuevo tamaño máximo de caché es menor que el tamaño de caché actual, los registros más antiguos se borran hasta que el número de filas sea igual al tamaño máximo de caché especificado. El valor máximo es 10000.

Si el tamaño de caché se define en 0, el almacenamiento en caché se desactiva en la sesión.

El tamaño de caché por defecto es 10.

Excepciones

Excepción	Error	Descripción
`invalid API result cache size`	`ORA-20032`	El valor mínimo es 0 y el valor máximo es 10000. Esta excepción se muestra cuando el valor de entrada es menor que 0 o mayor que 10000.

Ejemplo

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);