API de REST de DBMS_CLOUD

En esta sección se tratan las API de REST DBMS_CLOUD que se proporcionan con Autonomous AI Database en una infraestructura de Exadata dedicada.

Requisitos

Como desarrollador, puede utilizar procedimientos DBMS_CLOUD con bases de datos de IA autónomas desplegadas en Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

Según la opción de despliegue, se deben cumplir los siguientes requisitos previos para utilizar los procedimientos DBMS_CLOUD con los proveedores de servicios Amazon S3, Azure Blob Storage y Google Cloud Storage.

Resumen de API REST de DBMS_CLOUD

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

API de REST Descripción
Función GET_RESPONSE_HEADERS Esta función devuelve las cabeceras de respuesta HTTP como datos JSON en un objeto JSON de Autonomous AI Database.
Función GET_RESPONSE_TEXT Esta función devuelve la respuesta HTTP en formato TEXT (VARCHAR2 o CLOB) en la base de datos de IA autónoma. 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 la base de datos de IA autónoma. Esta función proporciona un flujo de trabajo para enviar una solicitud de API de REST en la nube con argumentos, un código de respuesta de retorno y una carga útil.
Procedimiento SET_API_RESULT_CACHE_SIZE Este procedimiento define el tamaño máximo de caché para la sesión actual.

Visión general de API de REST de DBMS_CLOUD

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

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

Constantes de API de REST de DBMS_CLOUD

Describe las constantes 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 utilizará para una solicitud HTTP se suele documentar en la documentación de la API de REST en la nube.

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 API de REST DBMS_CLOUD

Puede guardar los resultados de la API de REST DBMS_CLOUD al definir el parámetro cache en true con DBMS_CLOUD.SEND_REQUEST. La vista SESSION_CLOUD_API_RESULTS describe las columnas que puede utilizar cuando se guardan 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, utilizará la función DBMS_CLOUD.SEND_REQUEST para devolver 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 resultados históricos de solicitudes de API de REST DBMS_CLOUD puede ayudarle 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 que se cierra la sesión, los datos guardados ya no está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 caché de la API de REST DBMS_CLOUD y para desactivar el almacenamiento en caché.

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

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

Por defecto, 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 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 DBMS_CLOUD.SEND_REQUEST generados por los procedimientos que llama con los derechos del invocador. 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:

Vista de DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS

Puede guardar los resultados de la API de REST DBMS_CLOUD al definir el parámetro cache en true con DBMS_CLOUD.SEND_REQUEST. La vista SESSION_CLOUD_API_RESULTS describe las columnas que puede utilizar cuando se guardan 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, los datos de SESSION_CLOUD_API_RESULTS se depuran.

Columna Descripción
URI URL de solicitud de API de REST DBMS_CLOUD
TIMESTAMP Registro de hora de respuesta de la API de REST DBMS_CLOUD
CLOUD_TYPE Tipo de nube de API de REST DBMS_CLOUD, como Oracle Cloud Infrastructure y AZURE_BLOB
REQUEST_METHOD Método de solicitud de la API de REST DBMS_CLOUD, como GET, PUT, HEAD
REQUEST_HEADERS Cabeceras de solicitud de la API de REST DBMS_CLOUD
REQUEST_BODY_TEXT Cuerpo de solicitud de la API de REST DBMS_CLOUD en CLOB
RESPONSE_STATUS_CODE Código de estado de respuesta de la API de REST DBMS_CLOUD, como 200(OK), 404(Not Found)
RESPONSE_HEADERS Cabeceras de respuesta de la API de REST DBMS_CLOUD
RESPONSE_BODY_TEXT Cuerpo de respuesta de la API de REST 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 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 devuelto 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 devuelto 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 autenticarse 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, DELETE. Utilice la constante de paquete DBMS_CLOUD para especificar el método.

Consulte Constantes de 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 transfieren cabeceras personalizadas.
async_request_url

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, navegue para buscar la API para su solicitud en el panel izquierdo. Por ejemplo, API de servicios de base de datos -> Base de datos de IA autónoma -> StopAutonomousDatabase. Esta página muestra el directorio raíz de API (y el punto final base). A continuación, agregue el punto final base con la ruta de acceso relativa obtenida para el enlace WorkRequest de la solicitud de trabajo.

wait_for_states

Los estados de espera son de tipo: DBMS_CLOUD_TYPES.wait_for_states_t. Los siguientes son valores válidos para los estados esperados: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

Se permiten varios estados para wait_for_states. El valor por defecto para wait_for_states es esperar a cualquiera de los estados esperados: 'ACTIVE', 'CANCELED', 'COMPLETED', 'DELETED', 'FAILED', 'SUCCEEDED'.

timeout

Especifica el timeout, en segundos, para las 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 un timeout.

cache

Si TRUE especifica que la solicitud se debe almacenar en caché en la caché de API de resultados de REST.

El valor por defecto es FALSE, lo que significa que las solicitudes de la 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 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

Procedimiento SET_API_RESULT_CACHE_SIZE

Este procedimiento 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
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 anteriores 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);

Contenido relacionado