Documentación de Oracle Cloud Infrastructure

Paquete DBMS_CLOUD_LINK

El paquete DBMS_CLOUD_LINK permite a un usuario registrar una tabla o una vista como juego de datos para el acceso de solo lectura con enlaces en la nube.

Tema principal: Referencia de paquete proporcionado por Autonomous Database

Visión general de DBMS_CLOUD_LINK

Describe el uso del paquete DBMS_CLOUD_LINK.

El paquete DBMS_CLOUD_LINK proporciona el procedimiento REGISTER que permite registrar una tabla o una vista como un juego de datos para su uso con enlaces de nube. Para poder registrar un juego de datos, el usuario ADMIN debe otorgar permiso a un usuario para registrar un juego de datos mediante el procedimiento DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. Después de que el administrador ejecute GRANT_REGISTER, un usuario puede registrar una tabla o una vista que posea como juego de datos registrado (o registrar un objeto en otro esquema si el usuario tiene el privilegio READ WITH GRANT OPTION en el objeto). Los juegos de datos registrados proporcionan acceso remoto al objeto registrado con enlaces a la nube, según el ámbito especificado con el procedimiento REGISTER.

Para ejecutar DBMS_CLOUD_LINK.REGISTER, debe tener el privilegio de ejecución en DBMS_CLOUD_LINK.REGISTER, además de haber ejecutado previamente DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. Solo el usuario ADMIN y los esquemas con el rol PDB_DBA tienen privilegios de ejecución en DBMS_CLOUD_LINK.REGISTER por defecto.

Tema principal: Paquete DBMS_CLOUD_LINK

Resumen de los subprogramas DBMS_CLOUD_LINK

Muestra una tabla con un resumen de los subprogramas incluidos en el paquete DBMS_CLOUD_LINK.

Subprograma Descripción

Función DESCRIBE

Esta función recupera la descripción de un juego de datos. La descripción se proporciona cuando se registra un juego de datos con DBMS_CLOUD_LINK.REGISTER.

Procedimiento FIND

Recupera el espacio de nombres, el nombre y la descripción de los juegos de datos que coinciden con la cadena de búsqueda. Los juegos de datos coincidentes solo se muestran si son accesibles para el usuario, según las restricciones de acceso.

Función GET_DATABASE_ID

Devuelve un identificador único para la instancia de Autonomous Database. Las llamadas repetidas a DBMS_CLOUD_LINK.GET_DATABASE_ID en la misma instancia siempre devuelven el mismo valor.

Procedimiento GRANT_AUTHORIZATION

Otorga autorización a una base de datos especificada para acceder al juego de datos especificado.

Procedimiento REGISTRAR

Registra una tabla o vista como juego de datos.

Procedimiento REVOKE_AUTHORIZATION

Revoca la autorización para que una base de datos especificada acceda al juego de datos especificado.

Procedimiento UNREGISTER

Elimina un juego de datos registrado.
  • Función ESCRIBE
    Esta función recupera la descripción de un juego de datos. La descripción se proporciona cuando se registra un juego de datos con DBMS_CLOUD_LINK.REGISTER.
  • Procedimiento FIND
    Este procedimiento recupera el espacio de nombres, el nombre y la descripción de los juegos de datos que coinciden con la cadena de búsqueda. Los juegos de datos coincidentes solo se muestran si son accesibles para el usuario, según las restricciones de acceso.
  • Función GET_DATABASE_ID
    La función devuelve un identificador único para la instancia de Autonomous Database. Las llamadas repetidas a DBMS_CLOUD_LINK.GET_DATABASE_ID en la misma instancia siempre devuelven el mismo valor.
  • Procedimiento GRANT_AUTHORIZATION
    Este procedimiento otorga autorización a una base de datos especificada para acceder al juego de datos especificado.
  • Procedimiento REGISTER
    El procedimiento registra una tabla o una vista como un juego de datos para permitir el acceso de solo lectura remoto, sujeto a las restricciones impuestas por el parámetro scope.
  • Procedimiento REVOKE_AUTHORIZATION
    Este procedimiento revoca la autorización para que una base de datos especificada acceda al juego de datos especificado.
  • Procedimiento UNREGISTER
    El procedimiento permite a un usuario que haya registrado previamente una tabla o una vista con el procedimiento REGISTER anular el registro de la tabla o vista para que ya no esté disponible para el acceso remoto.

Tema principal: Paquete DBMS_CLOUD_LINK

Función DESCRIBE

Esta función recupera la descripción de un juego de datos. La descripción se proporciona cuando se registra un juego de datos con DBMS_CLOUD_LINK.REGISTER.

Sintaxis

DBMS_CLOUD_LINK.DESCRIBE(
      namespace        IN   VARCHAR2,
      name             IN   VARCHAR2
) return CLOB;

Parámetros

parámetro Descripción

namespace

Especifica el espacio de nombres del juego de datos registrado.

name

Especifica el nombre de un juego de datos registrado.

Nota de Uso

Puede utilizar esta función sujeta a las restricciones de acceso impuestas en el momento del registro con DBMS_CLOUD_LINK.REGISTER. Si una base de datos no puede acceder a un juego de datos, su descripción no se recuperará.

Procedimiento FIND

Este procedimiento recupera el espacio de nombres, el nombre y la descripción de los juegos de datos que coinciden con la cadena de búsqueda. Los juegos de datos coincidentes solo se muestran si son accesibles para el usuario, en función de las restricciones de acceso.

Sintaxis

DBMS_CLOUD_LINK.FIND(
      search_string        IN   VARCHAR2,
      search_result        OUT   CLOB
);

Parámetros

parámetro Descripción

search_string

Especifica la cadena de búsqueda. La cadena de búsqueda no es confidencial.

search_result

Documento JSON que incluye los valores de espacio de nombres, nombre y descripción del juego de datos.

Nota de Uso

La cadena de búsqueda no distingue entre mayúsculas y minúsculas y el paquete utiliza la búsqueda de texto libre con Oracle Text.

Función GET_DATABASE_ID

La función devuelve un identificador único para la instancia de Autonomous Database. Las llamadas repetidas a DBMS_CLOUD_LINK.GET_DATABASE_ID en la misma instancia siempre devuelven el mismo valor.

Puede llamar a esta función en una base de datos que accede a un juego de datos registrado de forma remota para obtener el ID de base de datos. Esto le permite proporcionar el iD de la base de datos para que el propietario de un juego de datos pueda aprovechar un control de acceso a datos más detallado, por ejemplo, con VPD, basado en un ID de base de datos especificado de sitios remotos.

Un ID de base de datos identifica cada base de datos remota que accede a un juego de datos registrado para realizar un seguimiento y auditar el acceso en las vistas V$CLOUD_LINK_ACCESS_STATS y GV$CLOUD_LINK_ACCESS_STATS de la base de datos que posee un juego de datos registrado.

Sintaxis

DBMS_CLOUD_LINK.GET_DATABASE_ID()
  RETURN VARCHAR2;

Notas de Uso

Los enlaces de nube utilizan el identificador único que devuelve DBMS_CLOUD_LINK.GET_DATABASE_ID para identificar bases de datos individuales que acceden a un juego de datos de forma remota. La base de datos propietaria del juego de datos registrado realiza un seguimiento y audita el ID de base de datos como un registro del origen para el acceso al juego de datos en las vistas V$CLOUD_LINK_ACCESS_STATS y GV$CLOUD_LINK_ACCESS_STATS.

El identificador DBMS_CLOUD_LINK.GET_DATABASE_ID está disponible como valor SYS_CONTEXT para que pueda obtener esta información mediante programación sobre una sesión remota de conexión mediante SYS_CONTEXT, con el fin de restringir y controlar aún más a qué datos específicos se puede acceder de forma remota mediante instancias de Autonomous Database individuales con bases de datos privadas virtuales (VPD)s.

Valores de Retorno

Identificador único para la instancia de Autonomous Database de VARCHAR2.

Procedimiento GRANT_AUTHORIZATION

Este procedimiento otorga autorización a una base de datos especificada para acceder al juego de datos especificado.

Sintaxis

DBMS_CLOUD_LINK.GRANT_AUTHORIZATION(
      database_id        IN   VARCHAR2,
      namespace          IN   VARCHAR2 DEFAULT,
      name               IN   VARCHAR2
);

Parámetros

parámetro Descripción

database_id

Especifica el ID de base de datos para una instancia de Autonomous Database. Utilice DBMS_CLOUD_LINK.GET_DATABASE_ID para obtener el ID de base de datos.

namespace

Especifica el espacio de nombres del juego de datos para otorgar autorización de acceso para el database_id especificado.

name

Especifica el nombre del juego de datos para otorgar autorización de acceso para el database_id especificado.

Procedimiento REGISTRAR

El procedimiento registra una tabla o una vista como un juego de datos para permitir el acceso de solo lectura remoto, sujeto a las restricciones impuestas por el parámetro scope.

Sintaxis

DBMS_CLOUD_LINK.REGISTER(
     schema_name      IN VARCHAR2,
     schema_object    IN VARCHAR2,
     namespace        IN VARCHAR2,
     name             IN VARCHAR2,
     description      IN CLOB,
     scope            IN CLOB,
     auth_required    IN BOOLEAN DEFAULT,
     data_set_owner   IN VARCHAR2 DEFAULT,
     offload_targets  IN CLOB DEFAULT

);

Parámetros

parámetro Descripción

schema_name

Especifica el propietario de la tabla o vista especificada con el parámetro schema_object.

schema_object

Especifica el nombre de una tabla o vista. Los objetos válidos son:

  • Tablas (incluidas las pilas, externas o híbridas)
  • vistas
  • Vistas Materializadas
  • Tablas en la nube

No se admiten otros objetos, como vistas analíticas o sinónimos.
namespace

Especifica el espacio de nombres para el juego de datos.

Un valor NULL especifica un valor namespace generado por el sistema, único para la instancia de Autonomous Database.

name

Especifica el nombre del juego de datos.
description

Especifica el texto para describir los datos.
scope

Describe quién tiene permiso para acceder al juego de datos. El valor es una lista separada por comas que consta de uno o más de los siguientes elementos:

  • OCID de la base de datos: se permite acceso al juego de datos para las instancias específicas de Autonomous Database identificadas por OCID.

  • OCID del compartimento: se permite el acceso al juego de datos para las bases de datos en los compartimentos identificados por el OCID del compartimento.

  • OCID del arrendamiento: se permite el acceso al juego de datos para las bases de datos en los arrendamientos identificados por el OCID del arrendamiento.

  • Nombre de la región: se permite el acceso al juego de datos para las bases de datos en la región identificada por la región con nombre. Por ámbito, el acceso a enlaces en la nube está limitado a una sola región y no es entre regiones. Un consumidor de una región diferente solo puede acceder a un juego de datos cuando existe una clonación de refrescamiento entre regiones de la base de datos que es el propietario del juego de datos en la región de la base de datos del consumidor.

    Consulte Registro o anulación del registro de un juego de datos en una región diferente para obtener más información.

  • MY$COMPARTMENT: se permite el acceso al juego de datos para las bases de datos del mismo compartimento que el del propietario del juego de datos.

  • MY$TENANCY: se permite acceso al juego de datos para las bases de datos del mismo arrendamiento que el del propietario del juego de datos.

  • MY$REGION: se permite el acceso al juego de datos para las bases de datos de la misma región que el propietario del juego de datos.

  • Lista de regiones: se permite el acceso al juego de datos para las bases de datos de las regiones especificadas

    Por ejemplo: 

    scope   =>  'us-phoenix-1,us-ashburn-1',

    Un consumidor de una región diferente solo puede acceder a un juego de datos cuando existe una clonación de refrescamiento entre regiones de la base de datos que es el propietario del juego de datos en la región de la base de datos del consumidor.

Los valores de ámbito, MY$REGION, MY$TENANCY y MY$COMPARTMENT, son variables que actúan como macros de conveniencia y se resuelven en OCID.

auth_required

Especifica que se necesita una autorización adicional para que las bases de datos puedan leer del juego de datos. Los casos posibles son los siguientes:

  • Las bases de datos que están dentro del SCOPE especificado y que se han autorizado con DBMS_CLOUD_LINK.GRANT_AUTHORIZATION pueden ver filas del juego de datos.

  • Cualquier base de datos que esté dentro del valor SCOPE especificado pero no se haya autorizado con DBMS_CLOUD_LINK.GRANT_AUTHORIZATION no puede ver las filas del juego de datos. En este caso, los consumidores sin autorización ven el juego de datos como vacío.

  • Las bases de datos que no están dentro del SCOPE especificado ven un error al intentar acceder al juego de datos.

data_set_owner

Especifica el propietario del juego de datos. Indica a quién pertenece el juego de datos o quién es responsable de actualizar y mantener el juego de datos. Por ejemplo, puede definir data_set_owner en la dirección de correo electrónico de la persona que registró el juego de datos.

offload_targets

Especifica uno o más OCID de Autonomous Database de clonaciones de refrescamiento en las que se descarga el acceso a juegos de datos de la instancia de Autonomous Database en la que se registra el juego de datos.

El valor offload_targets es un documento JSON que define uno o más pares de valores de clave CLOUD_LINK_DATABASE_ID y OFFLOAD_TARGET:

  • CLOUD_LINK_DATABASE_ID es uno de los siguientes:

    • Un ID de base de datos: especifica un ID de base de datos para el consumidor del juego de datos cuya solicitud se descarga en la clonación de refrescamiento correspondiente especificada con el valor OFFLOAD_TARGET.

      Obtenga el ID de base de datos ejecutando DBMS_CLOUD_LINK.GET_DATABASE_ID. Consulte Función GET_DATABASE_ID para obtener más información.

    • ANY: especifica que cualquier solicitud del consumidor del juego de datos se descarga en el destino de descarga correspondiente. La solicitud de juego de datos de un consumidor se enrutará al destino de descarga correspondiente.

      Si especifica ANY sin especificar identificadores de base de datos, todas las solicitudes de juego de datos de los consumidores se descargan en la clonación de refrescamiento especificada con el valor OFFLOAD_TARGET.

      Si especifica tanto los ID de base de datos como ANY, las solicitudes de juegos de datos de los consumidores que no coinciden con un ID de base de datos se descargan en la clonación de refrescamiento especificada con el valor OFFLOAD_TARGET.

  • OFFLOAD_TARGET es el OCID de una instancia de Autonomous Database que es una clonación de refrescamiento.

Por ejemplo, a continuación se muestra un ejemplo de JSON con tres pares de valores OFFLOAD_TARGET/CLOUD_LINK_DATABASE_ID: 

{
  "OFFLOAD_TARGETS": [
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx69708978",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfabc"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx89898978",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdef"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx4755680",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfghi"
    }
  ]
}

Cuando un consumidor de juegos de datos solicita acceso a un juego de datos que se registra con offload_targets con la palabra clave ANY, cualquier solicitud de acceso se descarga en la clonación de refrescamiento identificada con OFFLOAD_TARGET en el JSON proporcionado (excepto las solicitudes que tienen una entrada explícita en el JSON proporcionado).

Por ejemplo, a continuación se muestra un ejemplo de JSON con un par de valores OFFLOAD_TARGET/CLOUD_LINK_DATABASE_ID explícito y una entrada ANY: 

{
  "OFFLOAD_TARGETS": [
    {
      "CLOUD_LINK_DATABASE_ID": "ANY",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdef"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx4755680",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfghi"
    }
  ]
}

DBMS_CLOUD_LINK.REGISTER informa de un error si el OCID proporcionado como valor OFFLOAD_TARGET no es un OCID de una clonación de refrescamiento en la misma región.

Consulte Uso de clonaciones de refrescamiento con Autonomous Database para obtener información sobre el uso de clonaciones de refrescamiento.

Notas de Uso

  • Puede registrar un objeto en otro esquema si tiene el privilegio READ WITH GRANT OPTION en el objeto.

  • Después de registrar un objeto, puede que los usuarios tengan que esperar hasta diez (10) minutos para acceder al objeto con enlaces en la nube.

  • Para cambiar el ámbito de un juego de datos existente, primero debe anular el registro del juego de datos con DBMS_CLOUD_LINK.UNREGISTER. A continuación, debe registrar el juego de datos con el nuevo ámbito con DBMS_CLOUD_LINK.REGISTER. El tiempo total de espera para estas dos operaciones puede ser de hasta 20 minutos, incluidos 10 minutos para anular el registro y otros 10 minutos para que el registro se propague y se pueda acceder a él a través de enlaces en la nube.

    Este retraso también puede afectar a la visibilidad del juego de datos en las vistas DBA_CLOUD_LINK_REGISTRATIONS y DBA_CLOUD_LINK_ACCESS.

  • Puede registrar una tabla o vista que reside en el esquema de otro usuario cuando tiene privilegios READ WITH GRANT OPTION para la tabla o vista.

  • El ámbito que define al registrar un juego de datos solo se respeta cuando coincide o es más restrictivo que el valor definido con DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. Por ejemplo, supongamos que el ADMIN ha otorgado el ámbito 'MY$TENANCY' con GRANT_REGISTER y que el usuario especifica 'MY$REGION' al registrar un juego de datos con DBMS_CLOUD_LINK.REGISTER. En este caso, verían un error como el siguiente: 

    ORA-20001: Share privileges are not enabled for current user or it is enabled but not for scope MY$REGION

  • Algunas comprobaciones de validez jerárquica para el registro no se pueden realizar en el momento del registro. Los registros no válidos no serán visibles, detectables ni accesibles para nadie.

  • Para utilizar DBMS_CLOUD_LINK.REGISTER, debe tener el privilegio de ejecución en el paquete DBMS_CLOUD_LINK, además del privilegio de registro asignado con DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. Solo el usuario ADMIN y los esquemas con PDB_DBA tienen este privilegio por defecto.

  • Al registrar un juego de datos en una clonación de refrescamiento en una región remota, la llamada de DBMS_CLOUD_LINK.REGISTER en la clonación de región remota debe utilizar los mismos parámetros con los mismos valores que en la base de datos origen, con la excepción del parámetro offload_targets.

    Por ejemplo, al ejecutar DBMS_CLOUD_LINK.REGISTER con el ámbito definido en MY$COMPARTMENT en la instancia de Autonomous Database de origen, vuelva a ejecutar el procedimiento en la clonación de refrescamiento entre regiones con el mismo valor de parámetro de ámbito (MY$COMPARTMENT).

  • Si especifica el parámetro offload_targets con DBMS_CLOUD_LINK.REGISTER en el origen, debe omitir este parámetro al registrar el juego de datos en una clonación de refrescamiento entre regiones.

Procedimiento REVOKE_AUTHORIZATION

Este procedimiento revoca la autorización para que una base de datos especificada acceda al juego de datos especificado.

Sintaxis

DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION(
      database_id        IN   VARCHAR2,
      namespace          IN   VARCHAR2 DEFAULT,
      name               IN   VARCHAR2
);

Parámetros

parámetro Descripción

database_id

Especifica el ID de base de datos para una instancia de Autonomous Database. Utilice DBMS_CLOUD_LINK.GET_DATABASE_ID para obtener el ID de base de datos.

namespace

Especifica el espacio de nombres del juego de datos para revocar la autorización de acceso para el database_id especificado.

name

Especifica el nombre del juego de datos para revocar la autorización de acceso para el database_id especificado.

Procedimiento UNREGISTER

El procedimiento permite a un usuario que haya registrado previamente una tabla o una vista con el procedimiento REGISTER anular el registro de la tabla o vista para que ya no esté disponible para el acceso remoto.

Sintaxis

DBMS_CLOUD_LINK.UNREGISTER(
      namespace        IN   VARCHAR2,
      name             IN   VARCHAR2
);

Parámetros

parámetro Descripción

namespace

Especifica un nombre de usuario.
name

Especifica el nombre del juego de datos.

Nota de Uso

DBMS_CLOUD_LINK.UNREGISTER también puede tardar hasta diez (10) minutos en propagarse por completo, después de lo cual se puede acceder a los datos de forma remota.