Documentación de Oracle Cloud Infrastructure

Paquete DBMS_DATA_ACCESS

El paquete DBMS_DATA_ACCESS proporciona rutinas para generar y gestionar hipervínculos de tabla para juegos de datos.

Tema principal: Referencia de paquete proporcionado por Autonomous Database

Visión general de DBMS_DATA_ACCESS

Describe el uso del paquete DBMS_DATA_ACCESS.

DBMS_DATA_ACCESS soporta estas operaciones:

  • Generación de un hiperenlace de tabla
  • Invalidación manual de un hipervínculo de tabla
  • Listado de hipervínculos de tabla activos

Tema principal: Paquete DBMS_DATA_ACCESS

DBMS_DATA_ACCESS Modelo de Seguridad

La seguridad de este paquete se puede controlar otorgando EXECUTE en este paquete a los usuarios o roles seleccionados.

Cuando se le ha otorgado a un usuario EXECUTE en DBMS_DATA_ACCESS, puede crear, mostrar o invalidar los hiperenlaces de tabla que crea el usuario. Además, por defecto, el usuario ADMIN tiene los siguientes privilegios:
  • El usuario ADMIN con el rol PDB_DBA tiene el privilegio EXECUTE en DBMS_DATA_ACCESS.
  • El usuario ADMIN con el rol PDB_DBA puede mostrar o invalidar cualquier hiperenlace de tabla en una instancia de Autonomous Database.

Tema principal: Paquete DBMS_DATA_ACCESS

Resumen de los subprogramas DBMS_DATA_ACCESS

En esta sección se tratan los subprogramas DBMS_DATA_ACCESS que proporciona Autonomous Database.

Subprograma Descripción

Procedimiento GET_PREAUTHENTICATED_URL

Este procedimiento genera un hipervínculo de tabla.

Procedimiento EXTEND_URL

Este procedimiento amplía la vida útil de un hipervínculo de tabla.

Procedimiento INVALIDATE_URL

Este procedimiento invalida un hiperenlace de tabla.

Función LIST_ACTIVE_URLS

Esta función muestra todos los hipervínculos de tabla activos actualmente.

Tema principal: Paquete DBMS_DATA_ACCESS

Procedimiento GET_PREAUTHENTICATED_URL

Este procedimiento genera un hipervínculo de tabla.

Hay dos formularios, uno para generar el hiperenlace de tabla para un objeto específico (tabla o vista). La pantalla sobrecargada, mediante el parámetro sql_statement, genera un hiperenlace de tabla para una sentencia SQL.

Sintaxis

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    schema_name           IN VARCHAR2,
    schema_object_name    IN VARCHAR2,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    sql_statement         IN CLOB,
    application_user_id   IN VARCHAR2,
    default_bind_values   IN CLOB,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

Parámetros

parámetro Descripción

schema_name

Especifica el propietario del objeto.

schema_object_name

Especifica el objeto de esquema (tabla o vista).

sql_statement

Especifica el texto de la consulta de la sentencia SELECT. El soporte de variables de enlace está disponible para los tipos de columna NUMBER y VARCHAR2.

application_user_id

Especifica un valor de ID de usuario de aplicación. Cuando se accede al hiperenlace de tabla, el valor de application_user_id especificado durante la generación del hiperenlace de tabla está disponible a través de:

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

Puede definir políticas de VPD que utilicen este valor en el contexto de aplicación para restringir las filas visibles para el usuario de la aplicación.

default_bind_values

Especifica los valores por defecto de una o más variables de enlace (para un sql_statement especificado con variables de enlace).

Esto permite a un consumidor de hiperenlace de tabla acceder a los datos de hiperenlace de tabla con valores de enlace por defecto, sin proporcionar los valores de enlace como parámetros de consulta.

expiration_minutes

Duración en minutos de validez del hipervínculo de tabla.

El tiempo de caducidad máximo permitido es de 90 días (129600 minutos). Si el valor se establece en mayor que 129600, el valor utilizado es 129600 minutos (90 días).

Si se especifica expiration_minutes como un valor no nulo, expiration_count no se debe definir en un valor no nulo. Ambos no pueden ser no nulos al mismo tiempo.

Valor por defecto: cuando no se proporciona expiration_minutes o cuando se proporciona expiration_minutes como NULL, el valor se define en 90 días (129600 minutos).

expiration_count

Número de accesos permitidos en el hiperenlace de tabla.

No hay ningún valor por defecto.

Si no se especifica expiration_count y no se especifica expiration_minutes, expiration_minutes se define en 90 días (129600 minutos).

Si se especifica expiration_count como un valor no nulo, expiration_minutes no se debe definir en un valor no nulo. Ambos no pueden ser no nulos al mismo tiempo.

service_name

Servicio de base de datos que se utilizará para la recuperación de datos al utilizar el hiperenlace de tabla. Especifique la garantía de nivel de servicio y los recursos utilizados para dar servicio a este hiperenlace de tabla. Por ejemplo, el acceso a un objeto o sentencia SQL se puede asignar a los servicios HIGH o MEDIUM, mientras que el acceso a otro objeto o sentencia SQL se puede asignar al servicio LOW. Los valores soportados son HIGH, MEDIUM, LOW.

El valor por defecto es LOW.

column_lists

Valor JSON que especifica opciones por columna. Las opciones soportadas especificadas en el parámetro column_lists son una o más de las siguientes:

  • order_by_columns: especifica las columnas que soportan la ordenación.

  • filter_columns: especifica las columnas que soportan el filtrado

  • default_color_columns: especifica que solo se utilice el color por defecto para las columnas especificadas.

  • group_by_columns: especifica que se permite agrupar por para las columnas especificadas (se permite ver los datos agrupando la columna especificada).

El parámetro column_lists es JSON que contiene una lista de matrices JSON de columnas que definen la funcionalidad de hiperenlace de tabla. Utilice este parámetro para especificar las columnas de una o más de las opciones: order_by_columns, filter_columns, default_color_columns o group_by_columns.

La fórmula es:

"column_lists" : {
        "order_by_columns": [order_by_columns_list],
        "filter_columns": [filter_columns_list],
        "default_color_columns": [default_color_columns_list],
        "group_by_columns": [group_by_columns_list]
},

Por ejemplo: 

"column_lists" : {
            "order_by_columns": ["NAME", "DEPARTMENT"],
            "filter_columns": ["ID", "NAME", "DEPARTMENT"],
            "default_color_columns": ["DEPARTMENT"],
            "group_by_columns": ["DEPARTMENT"]
},

Valores por Defecto:

Si no se especifica column_lists para las opciones order_by_columns y filter_columns, la ordenación y el filtrado están activados para todas las columnas.

Si no se especifica column_lists para group_by_columns, la opción group by no está activada para ninguna columna. Por defecto, las columnas definidas para activarse como group_by_columns también se activan como filter_columns.

inherit_acl

Defina el valor de este parámetro en TRUE para que herede las ACL. Cuando la herencia es verdadera, la dirección IP de un consumidor de hiperenlace de tabla entrante se valida con las listas de ACL en la base de datos del productor antes de permitir el acceso a los datos.

Cuando no se proporciona el parámetro o el valor del parámetro se define en FALSE, no se aplican las comprobaciones de ACL.

Si la base de datos del productor no tiene ACL configuradas, se ignora el valor inherit_acl y se permite el acceso a los datos sin ninguna comprobación de ACL.

El valor por defecto es FALSE.

result

JSON que indica el resultado de la operación.

Notas de uso

  • Hay un límite de 128 hiperenlaces de tabla activos en una instancia de Autonomous Database.

  • Al utilizar un hiperenlace de tabla desde un explorador, se admiten las siguientes opciones:
    • Visualice los datos devueltos en formato de tabla sin color (por defecto) agregando el parámetro de consulta ?view=table al hiperenlace de tabla.
    • Visualice los datos devueltos en formato de tabla y seleccione la columna o columnas que desea colorear con colores predefinidos según los valores de columna. Para ello, agregue el parámetro de consulta ?view=table&colored_column_names=column_name_1,column_name_2,...column_name_n al hiperenlace de tabla, donde column_name_1 a column_name_n son los nombres de las columnas que desea colorear.
    • Para ver los datos devueltos en formato de tabla y seleccionar un tipo de dato de columna específico con colores predefinidos, agregue el parámetro de consulta ?view=table&colored_column_types=data_type. Los valores de parámetro data_type soportados son VARCHAR y NONE.

    • El valor del parámetro sql_statement debe ser una sentencia SELECT. La sentencia SELECT soporta variables ligadas.

      Si las variables de enlace se incluyen en la sentencia select y los valores no se definen en el parámetro default_bind_values, los valores de las variables de enlace se deben agregar al hiperenlace de tabla generado como parámetro de consulta al acceder a los datos.

      Al incluir el parámetro default_bind_values, al acceder a los datos, puede omitir los valores de variable de enlace cuando se especifican valores por defecto en el parámetro default_bind_values. Puede sustituir un valor de variable de enlace por defecto especificado con default_bind_values proporcionando explícitamente el valor de variable de enlace como parámetro de consulta.

  • Al generar un hiperenlace de tabla en una instancia de Autonomous Database con un punto final privado, el resultado incluye un nombre private_preauth_url con el valor del formulario: "https://private-endpoint/adb/p/parurl-token/data".

    Al generar un hiperenlace de tabla en una instancia de Autonomous Database con un punto final privado y el punto final privado está configurado con Permitir acceso público activado, el resultado incluye tanto preauth_url para el punto final público como private_preauth_url.

    Consulte Configuración de puntos finales privados y Uso de un punto final privado con acceso público permitido para obtener más información.

Ejemplo - Hiperenlace de tabla generado para un objeto específico

En el siguiente ejemplo se genera un hiperenlace de tabla para STUDENTS_VIEW: 

DECLARE
   status CLOB;
   BEGIN
   DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
      schema_name => 'USER1',
      schema_object_name => 'STUDENTS_VIEW',
      expiration_minutes => 120,
      service_name => 'HIGH',
      result => status);
   dbms_output.put_line(status);
END;
/

Ejemplo - Hiperenlace de tabla generado para una sentencia SQL

En el siguiente ejemplo se genera un hiperenlace de tabla para una sentencia SQL SELECT: 

DECLARE
   status CLOB;
   par_url_app_string CLOB;
   BEGIN
       par_url_app_string := 1919292929;
       DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
            sql_statement => 'SELECT student_id, student_name FROM STUDENTS_VIEW ORDER BY student_id',
            application_user_id => par_url_app_string,
            expiration_count => 25,
            result => status);
END;
/

Ejemplo - Hiperenlace de tabla generado para una sentencia SQL con una variable de enlace

En el siguiente ejemplo se utiliza una variable de enlace en la sentencia SELECT para generar el hiperenlace de tabla: 

set serveroutput on 
DECLARE
  status clob; 
BEGIN
  DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
    sql_statement => 'select * from TREE_DATA WHERE COUNTY = :countyNAME',
    expiration_minutes => 3000,
    result => status);
    dbms_output.put_line('status : '||status);
END;
/

Para utilizar el hiperenlace de tabla generado, se debe transferir el valor de variable de enlace. El siguiente ejemplo utiliza el hipervínculo de tabla generado para acceder a los datos de árbol del primer condado:

https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/gTlbq...example/data?countyNAME=First

Uso del Hiperenlace de Tabla para Acceder a Datos con Variables de Enlace

En el siguiente ejemplo se utiliza una variable de enlace en la sentencia SELECT e incluye el parámetro default_bind_values para generar el hiperenlace de tabla: 

set serveroutput on 
DECLARE
  status clob; 
BEGIN
  DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
    sql_statement = 'SELECT * FROM TREE_DATA WHERE COUNTY = :countyNAME',
    default_bind_values => '{"countyNAME" : "First"}',
    expiration_minutes => 3000,
    result => status);
    dbms_output.put_line('status : '||status);
END;
/

En este caso, si se utiliza el valor de variable de enlace por defecto y no es necesario que proporcione el valor como parámetro de consulta. Por ejemplo:

curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data
curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data

{"items":[
{"COUNTY":"First","SPECIES":"Pine","HEIGHT":16},
{"COUNTY":"First","SPECIES":"Spruce","HEIGHT":6},
{"COUNTY":"First","SPECIES":"Hawthorn","HEIGHT":19},
{"COUNTY":"First","SPECIES":"Cherry","HEIGHT":20},
{"COUNTY":"First","SPECIES":"Chestnut","HEIGHT":51}],
"hasMore":false,
"limit":100,
"offset":0,
"count":6,
"links":
[
{"rel":"self",
"href":"https://dataaccess.adb.us-ashburn-1.oraclecloudapps.com/adb/p/gTlbq...example/data"}
]}

Puede sustituir el valor de variable de enlace por defecto especificando explícitamente el valor como parámetro de consulta. Por ejemplo:

curl https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6X...example/data?countyNAME=MAIN

Consulte GET_PREAUTHENTICATED_URL Procedure para obtener más información.

Ejemplo - Hiperenlace de tabla generado para un objeto específico con columnas Agrupar por

El siguiente ejemplo genera un hiperenlace de tabla para una tabla específica con las columnas Agrupar por especificadas:

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
          schema_name => 'ADMIN',
          schema_object_name    => 'TREE_DATA',
          expiration_minutes    => 360,
          service_name          => 'HIGH',
          column_lists          => {"group_by_columns": ["COUNTY", "SPECIES"]}',
          result                => status);

       dbms_output.put_line(status);
    END;
/

Procedimiento EXTEND_URL

Este procedimiento amplía la vida útil de un hipervínculo de tabla.

Sintaxis:

DBMS_DATA_ACCESS.EXTEND_URL( 
    id                              IN VARCHAR2,
    extend_expiration_minutes_by    IN NUMBER,
    extend_expiration_count_by      IN NUMBER,
    result                          OUT CLOB);

Parámetros

parámetro Descripción

id

Especifica el ID del hiperenlace de tabla que se va a ampliar.

extend_expiration_minutes_by

Número de minutos para ampliar el tiempo de caducidad del hiperenlace de tabla. La hora de caducidad se define en la hora de caducidad actual más el valor de extend_expiration_minutes_by.

El valor de extend_expiration_minutes_by más la hora de caducidad actual no debe superar 129600 (que corresponde a 90 días).

Si extend_expiration_minutes_by es nulo, extend_expiration_count_by no puede ser nulo. Ambos no pueden ser nulos al mismo tiempo.

El valor por defecto es NULL.

extend_expiration_count_by

Este recuento amplía el número de accesos en el hiperenlace de tabla. El recuento de caducidad se define en el recuento de caducidad actual más el valor extend_expiration_count_by.

Si extend_expiration_count_by es nulo, extend_expiration_minutes_by no puede ser nulo. Ambos no pueden ser nulos al mismo tiempo.

El valor por defecto es nulo.

result

JSON que indica el resultado de la operación.

Ejemplo - Ampliar minutos de vencimiento de hiperenlace de tabla

set serveroutput on
declare
  status clob;
  js_status json_object_t;
  js_arr    json_array_t;
  url_id varchar2(4000);
begin
  -- Initially sets the expiration time to 60 minutes
  dbms_data_access.get_preauthenticated_url(
    schema_name        => 'SCOTT',     -- Schema name
    schema_object_name => 'EMPLOYEE',  -- Schema object name
    expiration_minutes => 60,          -- Expiration minutes
    service_name       => 'HIGH',
    result             => status);
   js_status := json_object_t.parse(status);
  url_id := js_status.get_string('id');
  dbms_output.put_line('The url id of url: ' || url_id);
  dbms_output.put_line('Initial Expiration Time: ' ||
                       js_status.get_string('expiration_ts'));
  -- Extend the expiration minutes by 1 day, the url would now expire
  -- 24 hours later than the previous expiration time
  dbms_data_access.extend_url(
    id                           => url_id,
    extend_expiration_minutes_by => 1440,
    result                       => status);
   -- List urls created
  status := dbms_data_access.list_active_urls;
  js_arr := json_array_t.parse(status);
  for indx in 0.. js_arr.get_size - 1
  loop
    js_status := TREAT (js_arr.get (indx) AS json_object_t);
    if js_status.get_string('id') = url_id then
      dbms_output.put_line('New Expiration Time : ' ||
                            js_status.get_string('expiration_time'));
      exit;
    end if;
  end loop;
end;
/

Ejemplo - Ampliar recuento de caducidad de hiperenlace de tabla

set serveroutput on
declare  status clob;
  js_status json_object_t;
  js_arr    json_array_t;
  url_id varchar2(4000);
begin
  -- Initially sets the expiration count to 100
  dbms_data_access.get_preauthenticated_url(
    schema_name        => 'SCOTT',     -- Schema name
    schema_object_name => 'EMPLOYEE',  -- Schema object name
    expiration_count   => 100,         -- Expiration count
    service_name       => 'HIGH',
    result             => status);
  js_status := json_object_t.parse(status);
  url_id := js_status.get_string('id');
  dbms_output.put_line('The url id of url: ' || url_id);
  dbms_output.put_line('Initial Expiration Count: ' ||
                       js_status.get_string('expiration_count'));
  -- Extends access count by 100 so url would expire after 200 accesses
  dbms_data_access.extend_url(
    id                         => url_id,
    extend_expiration_count_by => 100,
    result                     => status);
  -- List urls created
  status := dbms_data_access.list_active_urls;
  js_arr := json_array_t.parse(status);
  for indx in 0.. js_arr.get_size - 1
  loop
    js_status := TREAT (js_arr.get (indx) AS json_object_t);
     if js_status.get_string('id') = url_id then
      dbms_output.put_line('New Expiration Count : ' ||
                            js_status.get_string('expiration_count'));
      exit;
    end if;
  end loop;
end;
/

Procedimiento INVALIDATE_URL

Este procedimiento invalida un hiperenlace de tabla.

Sintaxis

DBMS_DATA_ACCESS.INVALIDATE_URL(
    id                  IN VARCHAR2,
    kill_sessions       IN BOOLEAN DEFAULT FALSE,
    result              OUT CLOB);

Parámetros

parámetro Descripción

id

Especifica el propietario del objeto.

kill_sessions

Por defecto, las sesiones existentes que pueden estar en medio de acceder a los datos mediante un hiperenlace de tabla no se matan. Cuando es TRUE, este parámetro especifica que dichas sesiones existentes se deben matar, de modo que la invalidación no deje ningún acceso en curso al juego de datos.

Valores válidos: TRUE | FALSE.

result

Proporciona JSON para indicar si la invalidación es correcta o fallida (CLOB).

Función LIST_ACTIVE_URLS

Esta función muestra todos los hipervínculos de tabla y grupos de hipervínculos de tabla activos actualmente.

Sintaxis

DBMS_DATA_ACCESS.LIST_ACTIVE_URLS RETURN CLOB;

Parámetros

parámetro Descripción
RETURN

El valor devuelto es una matriz de JSON.

Ejemplo

DECLARE
   result CLOB;
   BEGIN
       result := DBMS_DATA_ACCESS.LIST_ACTIVE_URLS;
       DBMS_OUTPUT.PUT_LINE(result);
   END;
[{"id":"pT36lYHFGA4s3UXSNBCRO13v3D4_example1",
"created_by":"SCOTT",
"service_name":"HIGH",
"expiration_time":"2025-07-28T16:38:02.723Z",
"expiration_count":10,
"access_count":0,
"created":"2025-04-29T16:38:02.977Z",
"inherit_acl":true,
"is_group_url":false,
"group_ids":[null],
"sql_statement":"select * FROM TREE_DATA WHERE COUNTY = :county"}]

Notas de uso

  • El comportamiento de DBMS_DATA_ACCESS.LIST_ACTIVE_URLS depende del invocador. Si el invocador es ADMIN o cualquier usuario con el rol PDB_DBA, la función muestra todos los hipervínculos de tabla activos, independientemente del usuario que haya generado el hipervínculo de tabla. Si el invocador no es el usuario ADMIN y no un usuario con el rol PDB_DBA, la lista incluye solo los hiperenlaces de tabla activos generados por el invocador.

  • Al generar y mostrar un hiperenlace de tabla en una instancia de Autonomous Database con un punto final privado, el resultado incluye un nombre private_preauth_url con el valor del formulario: "https://private-endpoint/adb/p/parurl-token/data".

    Al generar y mostrar un hiperenlace de tabla en una instancia de Autonomous Database con un punto final privado y el punto final privado está configurado con Permitir acceso público activado, el resultado incluye tanto preauth_url para el punto final público como private_preauth_url.

    Consulte Configuración de puntos finales privados y Uso de un punto final privado con acceso público permitido para obtener más información.

  • Cuando un hiperenlace de tabla es un miembro de grupo, la entrada de respuesta DBMS_DATA_ACCESS.LIST_ACTIVE_URLS muestra "group_ids" con un valor no nulo que incluye uno o más ID. Los ID muestran los ID de grupo de hipervínculos de tabla de los que es miembro el hipervínculo de tabla (miembro de grupo).