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

ADD_MEMBER Procedimiento

CREATE_URL Procedimiento

Este procedimiento genera un hipervínculo de tabla o un grupo de hipervínculos de tabla.

EXTEND_URL Procedimiento

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

Procedimiento GET_PREAUTHENTICATED_URL

Este procedimiento genera un hipervínculo de tabla.

Este procedimiento está en desuso. En su lugar, utilice el procedimiento CREATE_URL.

EXTEND_URL Procedimiento

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

INVALIDATE_URL Procedimiento

Este procedimiento invalida un hiperenlace de tabla.

Función LIST_ACTIVE_URLS

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

LIST_MEMBERS Procedimiento

REMOVE_MEMBER Procedimiento

  • Procedimiento ADD_MEMBER
    Este procedimiento agrega un hiperenlace de tabla existente al grupo de hiperenlaces de tabla como miembro.
  • CREATE_URL Procedimiento
    Este procedimiento genera un hipervínculo de tabla o un grupo de hipervínculos de tabla. Un grupo de hipervínculos de tabla proporciona acceso a varios hipervínculos de tabla con una única URL. Este procedimiento está sobrecargado.
  • Procedimiento GET_PREAUTHENTICATED_URL
    Este procedimiento genera un hiperenlace de tabla.
  • Procedimiento EXTEND_URL
    Este procedimiento prolonga la vida de un hipervínculo de tabla o de un grupo de hipervínculos de tabla.
  • Procedimiento INVALIDATE_URL
    Este procedimiento invalida un hiperenlace de tabla o un grupo de hiperenlaces de tabla.
  • Función LIST_ACTIVE_URLS
    Esta función muestra todos los hipervínculos de tabla y grupos de hipervínculos de tabla activos actualmente.
  • LIST_MEMBERS Procedimiento
    Este procedimiento muestra los miembros de un grupo de hipervínculos de tabla.
  • REMOVE_MEMBER Procedimiento
    Este procedimiento elimina un miembro de un grupo de hipervínculos de tabla.

Tema principal: Paquete DBMS_DATA_ACCESS

ADD_MEMBER Procedimiento

Este procedimiento agrega un hipervínculo de tabla existente al grupo de hipervínculos de tabla como miembro.

Sintaxis

DBMS_DATA_ACCESS.ADD_MEMBER(
    id        IN VARCHAR2,
    member_id       IN BOOLEAN DEFAULT FALSE,
    result          OUT CLOB);

Parámetros

parámetro Descripción

id

Especifica el identificador del grupo de hipervínculos de tabla.
member_id

Especifica el identificador del hiperenlace de tabla que se va a agregar al grupo.

result

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

Ejemplo

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.ADD_MEMBER(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        member_id => 'Zdd1Px7QWASdqDbnndiuwTAyyEstv82PCHlS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/

CREATE_URL Procedimiento

Este procedimiento genera un hipervínculo de tabla o un grupo de hipervínculos de tabla. Un grupo de hipervínculos de tabla proporciona acceso a varios hipervínculos de tabla con una única URL. Este procedimiento está sobrecargado.

Sintaxis

DBMS_DATA_ACCESS.CREATE_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.CREATE_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);

DBMS_DATA_ACCESS.CREATE_URL( 
    sqls                  IN CLOB,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    inherit_acl           IN BOOLEAN   DEFAULT FALSE,
    result                OUT CLOB);

Parámetros

parámetro Descripción

sqls

Especifica una matriz de JSON de las sentencias SELECT u objetos de esquema.

Consulte la siguiente descripción para obtener más información sobre el formato de la matriz de JSON.

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

Este parámetro opcional especifica un valor de ID de usuario de aplicación. Cuando se accede al hiperenlace de tabla o al grupo de hiperenlaces 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

Este parámetro opcional especifica la duración en minutos de validez del hiperenlace de tabla o del grupo de hiperenlaces 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

Este parámetro opcional especifica el número de accesos permitidos en el hiperenlace de tabla o en el grupo de hiperenlaces 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

Este parámetro es opcional. Defina el valor en TRUE para heredar las ACL. Cuando este parámetro es TRUE, la dirección IP del consumidor de un hiperenlace de tabla o de un grupo de hiperenlaces de tabla entrante se valida con las listas de ACL de 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.

El formato de la matriz de JSON que proporciona como parámetro sqls es:

Nombre de atributo Necesario Descripción
name No Especifica el nombre del miembro del grupo. Cuando no se proporciona ningún nombre, el procedimiento crea un nombre por defecto.
description No Descripción de miembro de grupo
sql_statement

Proporcionar sql_statement o schema_object_name es obligatorio

Sentencia SQL para el miembro

Consulte Generación de un hiperenlace de tabla con una sentencia Select para obtener más información.

schema_name No

Nombre de esquema para el miembro. Proporcione un valor schema_name solo cuando la tabla/vista proporcionada en schema_object_name no esté disponible en el esquema actual

Consulte Generación de un hiperenlace de tabla para una tabla o una vista para obtener más información.

schema_object_name

Proporcionar sql_statement o schema_object_name es obligatorio

Nombre de tabla/vista del miembro

Consulte Generación de un hiperenlace de tabla para una tabla o una vista para obtener más información.

default_bind_variable No Aplicable solo para sql_statements con variables de enlace

Consulte Generación de un hiperenlace de tabla con una sentencia Select para obtener más información.

column_lists No Igual que se ha definido para la creación de un hiperenlace de tabla que no sea de grupo

Consulte Generación de un hiperenlace de tabla con funciones de interfaz de usuario especificadas en columnas para obtener más informació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.

Ejemplos

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.CREATE_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.CREATE_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.CREATE_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.CREATE_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

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.CREATE_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;
/

Ejemplos

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.CREATE_URL(
          sqls => '[{"name": "employee", "description": "employee description", "schema_name":"admin", "schema_object_name":"employee"},
              {"name":"tree", "description": "tree description", "sql_statement": "select * from admin.tree_data"}]',
          expiration_count     => 10,
          service_name         => 'HIGH',
          result               => status);
       dbms_output.put_line(status);
    END;
/

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.

Nota

Este procedimiento está en desuso. En su lugar, utilice el procedimiento CREATE_URL.

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 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 máximo de caducidad 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 expiration_minutes se proporciona 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 va a 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 realizar el servicio de 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 la coloración 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 para 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 predeterminados:

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 Agrupar por 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

  • Este procedimiento está en desuso. En su lugar, utilice el procedimiento CREATE_URL.

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

  • 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 la variable de enlace. En el siguiente ejemplo se utiliza el hiperenlace de tabla generado para acceder a los datos del á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

En el siguiente ejemplo se 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 prolonga la vida útil de un hiperenlace de tabla o de un grupo de hiperenlaces 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 o del grupo de hiperenlaces 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.

Nota de Uso

Con un grupo de hipervínculos de tabla id, el procedimiento amplía todos los hipervínculos de tabla de miembros excepto los miembros agregados con DBMS_DATA_ACCESS.ADD_MEMBER. Los miembros que se agregaron al grupo de hiperenlaces de tablas con DBMS_DATA_ACCESS.ADD_MEMBER mantienen sus valores de invalidación de hiperenlaces de tablas independientes y puede ampliarlos individualmente mediante DBMS_DATA_ACCESS.EXTEND_URL.

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 hipervínculo de tabla o un grupo de hipervínculos 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 identificador del hiperenlace de tabla o del grupo de hiperenlaces de tabla que se va a invalidar.

kill_sessions

Este parámetro es opcional.

Por defecto, al ejecutar DBMS_DATA_ACCESS.INVALIDATE_URL sesiones existentes que pueden estar en medio del acceso a datos mediante un hiperenlace de tabla o un grupo de hiperenlaces de tabla no se eliminan. Cuando este parámetro se define en TRUE, este valor especifica que se deben matar las sesiones existentes, de modo que la invalidación no deje ningún acceso continuo a un juego de datos.

Valores válidos: TRUE | FALSE.

result

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

Nota de Uso

Cuando el parámetro DBMS_DATA_ACCESS.INVALIDATE_URL id es un grupo de hiperenlaces de tablas, el procedimiento invalida el grupo y todos los miembros del grupo, con la excepción de los miembros del grupo que se hayan agregado con DBMS_DATA_ACCESS.ADD_MEMBER. Después de ejecutar DBMS_DATA_ACCESS.INVALIDATE_URL, los miembros que se agregaron con DBMS_DATA_ACCESS.ADD_MEMBER mantienen sus valores de invalidación de hiperenlace de tabla independientes y puede invalidar estos hiperenlaces de tabla individualmente mediante DBMS_DATA_ACCESS.INVALIDATE_URL.

Ejemplo

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.INVALIDATE_URL(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/

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,
"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).

LIST_MEMBERS Procedimiento

Este procedimiento muestra los miembros de un grupo de hipervínculos de tabla.

Sintaxis

DBMS_DATA_ACCESS.LIST_MEMBERS(
    id              IN VARCHAR2,
    result          OUT CLOB);

Parámetros

Parámetro Descripción

id

Especifica el identificador del grupo de hipervínculos de tabla.

result

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

Ejemplo

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.LIST_MEMBERS(
         id => 'aGnHVyZ4vBo4_Fq2R0A2G2-y6TdUKRHeveqyGJ3_example',
         result => status);           
      dbms_output.put_line(status);
    END;
/

REMOVE_MEMBER Procedimiento

Este procedimiento elimina un miembro de un grupo de hipervínculos de tabla.

Sintaxis

DBMS_DATA_ACCESS.REMOVE_MEMBER(
    id              IN VARCHAR2,
    member_id       IN BOOLEAN DEFAULT FALSE,
    result          OUT CLOB);

Parámetros

Parámetro Descripción

id

Especifica el identificador del grupo de hipervínculos de tabla.
member_id

Especifica el identificador que debe eliminar el miembro del grupo del grupo de hipervínculos de tabla.

result

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

Notas de uso

  • El valor member_id no puede ser un ID de grupo de hipervínculos de tabla (is_group_url debe ser false).

  • Si el miembro eliminado es un hiperenlace de tabla existente que se ha agregado al grupo mediante DBMS_DATA_ACCESS.ADD_MEMBER, el miembro se elimina del grupo, pero se puede acceder directamente al hiperenlace de tabla hasta que se invalide o caduque explícitamente.

  • Si un grupo de hipervínculos de tabla contiene solo un miembro y ese miembro se elimina, el grupo se invalidará.

Ejemplo

DECLARE
    status CLOB;
    BEGIN
       DBMS_DATA_ACCESS.REMOVE_MEMBER(
        id => 'Vd1Px7QWASdqDbnndiuwTAyyEstv82PCHqS_example',
        member_id => 'Zdd1Px7QWASdqDbnndiuwTAyyEstv82PCHlS_example',
        result => status);           
       dbms_output.put_line(status);
    END;
/