DBMS_CLOUD_LINK_ADMIN Package

The DBMS_CLOUD_LINK_ADMIN package allows the ADMIN user to enable a database user to register data sets or to access registered data sets for a given Autonomous AI Database instance, subject to the access restrictions as defined with the granted scope.

Privileges can also be disabled for a user that has the privileges set to register data sets or access registered data sets.

DBMS_CLOUD_LINK_ADMIN Overview

Describes use of the DBMS_CLOUD_LINK_ADMIN package.

Cloud Links provide a cloud-based method to remotely access read only data on an Autonomous AI Database instance. The DBMS_CLOUD_LINK_ADMIN package leverages Oracle Cloud Infrastructure access mechanisms to make data sets accessible within a specific scope and in addition there is a optional authorization step.

Summary of DBMS_CLOUD_LINK_ADMIN Subprograms

This table summarizes the subprograms included in the DBMS_CLOUD_LINK_ADMIN package.

Subprogram	Description
ADD_SERVICE_MAPPING Procedure	The procedure associates a Cloud Links consumer database with a database service.
GRANT_AUTHORIZE Procedure	Grants a user the permission to invoke `DBMS_CLOUD_LINK.GRANT_AUTHORIZATION` and `DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION` procedures.
GRANT_READ Procedure	Allows a user to read registered data sets, subject to access restrictions imposed on data sets at registration.
GRANT_REGISTER Procedure	Allows a user to register a data set for remote access.
REMOVE_SERVICE_MAPPING Procedure	Remove a service mapping for a specified database.
REVOKE_AUTHORIZE Procedure	Revokes a user’s permission to invoke `DBMS_CLOUD_LINK.GRANT_AUTHORIZATION` and `DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION` procedures.
REVOKE_READ Procedure	Disallows a user from accessing registered data sets of the Autonomous AI Database instance.
REVOKE_REGISTER Procedure	Disallows a user from registering data sets for remote access. Data sets that were already registered by the user are unaffected.

ADD_SERVICE_MAPPING Procedure

The procedure DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING associates a consumer database with a database service.

Syntax

DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING(
      database_id        IN   VARCHAR2,
      service_name       IN   VARCHAR2
);

Parameters

Parameter Description

Parameter	Description
`database_id`	Specifies the database ID for an Autonomous AI Database instance that is a Cloud Link consumer. Use `DBMS_CLOUD_LINK.GET_DATABASE_ID` to obtain the database ID. The value "`ANY`" associates the specified `service_name` value with all consumer databases that do not have an entry that matches their database identifier. That is, any `database_id` whose `service_name` has not been set with `DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING`. Valid values: a database ID or "`ANY`".
`service_name`	Specifies the database service name. Valid values are: `TP`, `TPURGENT`, `HIGH`, `MEDIUM`, `LOW`.

database_id

Specifies the database ID for an Autonomous AI Database instance that is a Cloud Link consumer. Use DBMS_CLOUD_LINK.GET_DATABASE_ID to obtain the database ID.

The value "ANY" associates the specified service_name value with all consumer databases that do not have an entry that matches their database identifier. That is, any database_id whose service_name has not been set with DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.

Valid values: a database ID or "ANY".

service_name

Specifies the database service name.

Valid values are: TP, TPURGENT, HIGH, MEDIUM, LOW.

Usage Notes

Only the ADMIN user and schemas with PDB_DBA role can run DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.
You must run DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING on the data set owner's Autonomous AI Database instance.

GRANT_AUTHORIZE Procedure

The procedure grants a user permission to invoke the DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE(
      username        IN   VARCHAR2
);

Parameters

Parameter	Description
`username`	Specifies a username.

Usage Notes

To enable authorization for a data set with DBMS_CLOUD_LINK.GRANT_AUTHORIZATION, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.

GRANT_READ Procedure

The procedure allows a user to read registered data sets, subject to the access restrictions imposed on data sets when a data set is registered using DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_READ(
      username        IN   VARCHAR2
);

Parameters

Parameter	Description
`username`	Specifies a username.

Usage Notes

To read data sets, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_READ. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.
A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') to check if they are enabled for READ access to a data set.

For example, the following query:

SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') FROM DUAL;

Returns 'YES' or 'NO'.

GRANT_REGISTER Procedure

The procedure allows a user to register a data set for remote access.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER(
      username        IN   VARCHAR2,
      scope           IN   CLOB
);

Parameters

Parameter Description

username Specifies a user name.

scope

Specifies the scope in which permissions to publish are to be granted to the specified user.

Valid values are:

'MY$REGION'
'MY$TENANCY'
'MY$COMPARTMENT'
'MY$POOL'

Usage Notes

To register data sets, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.
A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') to check if they are enabled for registering data sets.

For example, the following query:

SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') FROM DUAL;

Returns 'YES' or 'NO'.

REMOVE_SERVICE_MAPPING Procedure

The procedure DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING removes a service mapping for a specified database.

Syntax

DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING(
      database_id        IN   VARCHAR2
);

Parameters

Parameter Description

Parameter	Description
`database_id`	Specifies the database ID for an Autonomous AI Database instance. Use `DBMS_CLOUD_LINK.GET_DATABASE_ID` to obtain the database ID. The value "`ANY`" removes any specified `service_name` value with all consumer databases that do not have an entry that matches their database identifier. That is, any `database_id` whose `service_name` has not been set with `DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING`. Valid values: a database ID or "`ANY`".

database_id

Specifies the database ID for an Autonomous AI Database instance. Use DBMS_CLOUD_LINK.GET_DATABASE_ID to obtain the database ID.

The value "ANY" removes any specified service_name value with all consumer databases that do not have an entry that matches their database identifier. That is, any database_id whose service_name has not been set with DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.

Valid values: a database ID or "ANY".

Usage Note

Only the ADMIN user and schemas with PDB_DBA role can run DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING.

REVOKE_AUTHORIZE Procedure

This procedure disallows a user from invoking DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_AUTHORIZE(
      username        IN   VARCHAR2
);

Parameters

Parameter	Description
`username`	Specifies a username.

REVOKE_READ Procedure

This procedure disallows a user from accessing registered data sets on the Autonomous AI Database instance.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_READ(
      username        IN   VARCHAR2
);

Parameters

Parameter	Description
`username`	Specifies a username.

Usage Note

A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') to check if they are enabled for READ access to a data set.

For example, the following query:

SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') FROM DUAL;

Returns 'YES' or 'NO'.

REVOKE_REGISTER Procedure

The procedure disallows a user from registering data sets for remote access. Data sets that were already registered by the user are unaffected.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_REGISTER(
      username        IN   VARCHAR2
);

Parameters

Parameter	Description
`username`	Specifies a user name.

Usage Note

A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') to check if they are enabled for registering data sets.

For example, the following query:

SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') FROM DUAL;

Returns 'YES' or 'NO'.