Documentation Oracle Cloud Infrastructure

Package DBMS_DATA_ACCESS

Le package DBMS_DATA_ACCESS fournit des routines permettant de générer et de gérer des liens hypertexte de table pour les ensembles de données.

Rubrique parent : Référence de package fourni avec Autonomous Database

Présentation de DBMS_DATA_ACCESS

Décrit l'utilisation du package DBMS_DATA_ACCESS.

DBMS_DATA_ACCESS prend en charge les opérations suivantes :

  • Génération d'un lien hypertexte de table
  • Invalidation manuelle d'un lien hypertexte de table
  • Liste des liens hypertexte de table actifs

Rubrique parent : Package DBMS_DATA_ACCESS

DBMS_DATA_ACCESS Modèle de sécurité

La sécurité sur ce package peut être contrôlée en accordant EXECUTE sur ce package aux utilisateurs ou rôles sélectionnés.

Lorsqu'un utilisateur dispose de EXECUTE sur DBMS_DATA_ACCESS, il peut créer, répertorier ou invalider les liens hypertexte de table créés par l'utilisateur. En outre, l'utilisateur ADMIN dispose par défaut des privilèges suivants :
  • L'utilisateur ADMIN avec le rôle PDB_DBA dispose du privilège EXECUTE sur DBMS_DATA_ACCESS.
  • L'utilisateur ADMIN disposant du rôle PDB_DBA peut répertorier ou invalider tout lien hypertexte de table dans une instance Autonomous Database.

Rubrique parent : Package DBMS_DATA_ACCESS

Récapitulatif des sous-programmes DBMS_DATA_ACCESS

Cette section traite des sous-programmes DBMS_DATA_ACCESS fournis avec Autonomous Database.

Sous-programme Description

Procédure ADD_MEMBER

Procédure CREATE_URL

Cette procédure génère un lien hypertexte de table ou un groupe de liens hypertexte de table.

Procédure EXTEND_URL

Cette procédure prolonge la durée de vie d'un lien hypertexte de table.

GET_PREAUTHENTICATED_URL Procédure

Cette procédure génère un lien hypertexte de table.

Cette procédure est en phase d'abandon. Utilisez plutôt la procédure CREATE_URL.

Procédure EXTEND_URL

Cette procédure prolonge la durée de vie d'un lien hypertexte de table.

Procédure INVALIDATE_URL

Cette procédure invalide un lien hypertexte de table.

Fonction LIST_ACTIVE_URLS

Cette fonction répertorie tous les liens hypertexte de table actuellement actifs.

Procédure LIST_MEMBERS

Procédure REMOVE_MEMBER

  • ADD_MEMBER Procédure
    Cette procédure ajoute un lien hypertexte de table existant au groupe de liens hypertexte de table en tant que membre.
  • CREATE_URL Procédure
    Cette procédure génère un lien hypertexte de table ou un groupe de liens hypertexte de table. Un groupe de liens hypertexte de table permet d'accéder à plusieurs liens hypertexte de table avec une seule URL. Cette procédure est surchargée.
  • Procédure GET_PREAUTHENTICATED_URL
    Cette procédure génère un lien hypertexte de table.
  • Procédure EXTEND_URL
    Cette procédure prolonge la durée de vie d'un lien hypertexte de table ou d'un groupe de liens hypertexte de table.
  • Procédure INVALIDATE_URL
    Cette procédure invalide un lien hypertexte de table ou un groupe de liens hypertexte de table.
  • LIST_ACTIVE_URLS Fonction
    Cette fonction répertorie tous les liens hypertexte de table et les groupes de liens hypertexte de table actuellement actifs.
  • LIST_MEMBERS Procédure
    Cette procédure répertorie les membres d'un groupe de liens hypertexte de table.
  • REMOVE_MEMBER Procédure
    Cette procédure supprime un membre d'un groupe de liens hypertexte de table.

Rubrique parent : Package DBMS_DATA_ACCESS

Procédure ADD_MEMBER

Cette procédure ajoute un lien hypertexte de table existant au groupe de liens hypertexte de table en tant que membre.

Syntaxe

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

Paramètres

Paramètre Description

id

Spécifie l'identificateur du groupe de liens hypertexte de table.
member_id

Spécifie l'identificateur du lien hypertexte de table à ajouter au groupe.

result

Fournit un fichier JSON pour indiquer si l'invalidation est un succès ou un échec (CLOB).

Exemple

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

Procédure CREATE_URL

Cette procédure génère un lien hypertexte de table ou un groupe de liens hypertexte de table. Un groupe de liens hypertexte de table permet d'accéder à plusieurs liens hypertexte de table avec une seule URL. Cette procédure est surchargée.

Syntaxe

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);

Paramètres

Paramètre Description

sqls

Spécifie un tableau JSON des instructions SELECT ou des objets de schéma.

Pour plus d'informations sur le format du tableau JSON, reportez-vous à la description suivante.

schema_name

Spécifie le propriétaire de l'objet.

schema_object_name

Indique l'objet de schéma (table ou vue).

sql_statement

Spécifie le texte de requête de l'instruction SELECT. La prise en charge des variables attachées est disponible pour les types de colonne NUMBER et VARCHAR2.

application_user_id

Ce paramètre facultatif spécifie une valeur d'ID utilisateur d'application. Lorsque vous accédez au lien hypertexte de table ou au groupe de liens hypertexte de table, la valeur de application_user_id indiquée lors de la génération du lien hypertexte de table est disponible via :

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

Vous pouvez définir des stratégies VPD qui utilisent cette valeur dans le contexte de l'application pour restreindre la visibilité des lignes pour l'utilisateur de l'application.

default_bind_values

Spécifie la ou les valeurs par défaut d'une ou de plusieurs variables attachées (pour une valeur sql_statement indiquée avec des variables attachées).

Cela permet à un consommateur de lien hypertexte de table d'accéder aux données de lien hypertexte de table avec des valeurs de liaison par défaut, sans fournir les valeurs de liaison en tant que paramètres de requête.

expiration_minutes

Ce paramètre facultatif spécifie la durée en minutes de validité du lien hypertexte de table ou du groupe de liens hypertexte de table.

Le délai d'expiration maximal autorisé est de 90 jours (129600 minutes). Si la valeur est supérieure à 129600, la valeur utilisée est 129600 minutes (90 jours).

Si expiration_minutes est spécifié en tant que valeur non NULL, expiration_count ne doit pas être défini sur une valeur non NULL. Les deux ne peuvent pas être non NULL en même temps.

Valeur par défaut : lorsque expiration_minutes n'est pas fourni ou que expiration_minutes est fourni en tant que NULL, la valeur est définie sur 90 jours (129600 minutes).

expiration_count

Ce paramètre facultatif spécifie le nombre d'accès autorisés sur le lien hypertexte de table ou sur le groupe de liens hypertexte de table.

Il n'y a pas de valeur par défaut.

Si expiration_count n'est pas spécifié et que expiration_minutes n'est pas spécifié, expiration_minutes est défini sur 90 jours (129600 minutes).

Si expiration_count est spécifié en tant que valeur non NULL, expiration_minutes ne doit pas être défini sur une valeur non NULL. Les deux ne peuvent pas être non NULL en même temps.

service_name

Service de base de données à utiliser pour l'extraction de données lors de l'utilisation du lien hypertexte Table. Indiquez la garantie de niveau de service et les ressources utilisées pour la maintenance de ce lien hypertexte de table. Par exemple, l'accès à un objet ou à une instruction SQL peut être mis en correspondance avec les services HIGH ou MEDIUM, tandis que l'accès à un autre objet ou à une autre instruction SQL peut être mis en correspondance avec le service LOW. Les valeurs prises en charge sont HIGH, MEDIUM, LOW.

La valeur par défaut est LOW.

column_lists

Valeur JSON qui indique les options par colonne. Les options prises en charge indiquées dans le paramètre column_lists sont les suivantes :

  • order_by_columns : indique les colonnes qui prennent en charge le tri.

  • filter_columns : indique les colonnes qui prennent en charge le filtrage.

  • default_color_columns : indique d'utiliser uniquement la coloration par défaut pour les colonnes indiquées.

  • group_by_columns : indique que le regroupement est autorisé pour les colonnes indiquées (la visualisation des données en regroupant la colonne indiquée est autorisée).

Le paramètre column_lists est un fichier JSON qui contient la liste des tableaux JSON de colonnes définissant la fonctionnalité de lien hypertexte de table. Utilisez ce paramètre pour indiquer les colonnes pour une ou plusieurs des options : order_by_columns, filter_columns, default_color_columns ou group_by_columns.

Le format est :

"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]
},

Exemples : 

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

Valeurs par défaut :

Si column_lists n'est pas indiqué pour les options order_by_columns et filter_columns, le tri et le filtrage sont activés pour toutes les colonnes.

Si column_lists n'est pas spécifié pour group_by_columns, l'option de regroupement n'est activée pour aucune colonne. Par défaut, les colonnes définies pour l'activation en tant que group_by_columns sont également activées en tant que filter_columns.

inherit_acl

Ce paramètre est facultatif. Définissez la valeur sur TRUE pour hériter des listes de contrôle d'accès. Lorsque ce paramètre est TRUE, l'adresse IP du destinataire d'un lien hypertexte de table ou d'un groupe de liens hypertexte de table entrant est validée avec les listes d'ACL de la base de données du producteur avant d'autoriser l'accès aux données.

Lorsque le paramètre n'est pas fourni ou que la valeur du paramètre est définie sur FALSE, les vérifications d'ACL ne sont pas appliquées.

Si aucune liste de contrôle d'accès n'est configurée pour la base de données du fournisseur, la valeur inherit_acl est ignorée et l'accès aux données est autorisé sans aucune vérification d'ACL.

La valeur par défaut est FALSE.

result

JSON indiquant le résultat de l'opération.

Le format du tableau JSON que vous fournissez en tant que paramètre sqls est :

Nom d'attribut Requis Description
name Non Spécifie le nom du membre du groupe. Lorsqu'aucun nom n'est fourni, la procédure crée un nom par défaut.
description Non Description du membre du groupe
sql_statement

L'option sql_statement ou schema_object_name est obligatoire

Instruction SQL pour le membre

Pour plus d'informations, reportez-vous à Générer un lien hypertexte de table avec une instruction Select.

schema_name Non

Nom de schéma du membre. Indiquez une valeur schema_name uniquement lorsque la table/vue fournie dans schema_object_name n'est pas disponible dans le schéma en cours

Pour plus de détails, reportez-vous à Génération d'un lien hypertexte de table pour une table ou une vue.

schema_object_name

L'option sql_statement ou schema_object_name est obligatoire

Nom de table/vue du membre

Pour plus de détails, reportez-vous à Génération d'un lien hypertexte de table pour une table ou une vue.

default_bind_variable Non Applicable uniquement pour sql_statements avec des variables attachées

Pour plus d'informations, reportez-vous à Générer un lien hypertexte de table avec une instruction Select.

column_lists Non Identique à ce qui a été défini pour la création d'un lien hypertexte de table non groupe

Pour plus d'informations, reportez-vous à Génération d'un lien hypertexte de table avec les fonctionnalités d'interface utilisateur spécifiées sur les colonnes.

Notes d'utilisation

  • Il existe une limite de 128 liens hypertexte de table actifs sur une instance Autonomous Database.

  • Lorsque vous utilisez un lien hypertexte de table à partir d'un navigateur, les options suivantes sont prises en charge :
    • Affichez les données renvoyées dans un format de table sans coloriage (par défaut), en ajoutant le paramètre de requête ?view=table au lien hypertexte de table.
    • Affichez les données renvoyées sous forme de tableau et sélectionnez les colonnes à colorier avec des couleurs prédéfinies en fonction des valeurs de colonne. Pour ce faire, ajoutez le paramètre de requête ?view=table&colored_column_names=column_name_1,column_name_2,...column_name_n au lien hypertexte de table, où column_name_1 à column_name_n sont les noms des colonnes à colorier.
    • Affichez les données renvoyées sous forme de tableau et sélectionnez le type de données de colonne spécifique à colorier avec des couleurs prédéfinies, en ajoutant le paramètre de requête ?view=table&colored_column_types=data_type. Les valeurs de paramètre data_type prises en charge sont VARCHAR et NONE.

    • La valeur du paramètre sql_statement doit être une instruction SELECT. L'instruction SELECT prend en charge les variables attachées.

      Si des variables attachées sont incluses dans l'instruction SELECT et que les valeurs ne sont pas définies dans le paramètre default_bind_values, les valeurs des variables attachées doivent être ajoutées au lien hypertexte de table généré en tant que paramètre de requête lors de l'accès aux données.

      Lorsque vous incluez le paramètre default_bind_values, lorsque vous accédez aux données, vous pouvez omettre les valeurs de variable attachée lorsque des valeurs par défaut sont indiquées dans le paramètre default_bind_values. Vous pouvez remplacer une valeur de variable attachée par défaut indiquée avec default_bind_values en fournissant explicitement la valeur de variable attachée en tant que paramètre de requête.

  • Lorsque vous générez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée, le résultat inclut un nom private_preauth_url avec la valeur du format : "https://private-endpoint/adb/p/parurl-token/data".

    Lorsque vous générez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée et que l'adresse privée est configurée avec l'option Autoriser l'accès public activée, le résultat inclut à la fois l'adresse preauth_url pour l'adresse publique et private_preauth_url.

    Pour plus d'informations, reportez-vous à Configuration des adresses privées et à Utilisation d'une adresse privée avec accès public autorisé.

Exemples

Exemple - Lien hypertexte de table généré pour un objet spécifique

L'exemple suivant génère un lien hypertexte de table pour 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;
/

Exemple - Lien hypertexte de table généré pour une instruction SQL

L'exemple suivant génère un lien hypertexte de table pour une instruction 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;
/

Exemple - Lien hypertexte de table généré pour une instruction SQL avec une variable attachée

L'exemple suivant utilise une variable attachée dans l'instruction SELECT pour générer le lien hypertexte de table : 

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

Pour utiliser le lien hypertexte de table généré, la valeur de variable attachée doit être transmise. L'exemple suivant utilise le lien hypertexte de table généré pour accéder aux données d'arborescence du premier comté :

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

Utiliser un lien hypertexte de table pour accéder aux données avec des variables attachées

L'exemple suivant utilise une variable attachée dans l'instruction SELECT et inclut le paramètre default_bind_values pour générer le lien hypertexte de table : 

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

Dans ce cas, la valeur de variable attachée par défaut est utilisée et vous n'avez pas besoin de la fournir en tant que paramètre de requête. Par exemple :

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"}
]}

Vous pouvez remplacer la valeur de variable attachée par défaut en spécifiant explicitement la valeur en tant que paramètre de requête. Par exemple :

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

Exemple - Lien hypertexte de table généré pour un objet spécifique avec colonnes Grouper par

L'exemple suivant génère un lien hypertexte de table pour une table spécifique avec des colonnes Grouper par spécifiées :

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

Exemples

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

GET_PREAUTHENTICATED_URL Procédure

Cette procédure génère un lien hypertexte de table.

Il existe deux formulaires, l'un pour générer le lien hypertexte Table pour un objet spécifique (table ou vue). Le formulaire surchargé, à l'aide du paramètre sql_statement, génère un lien hypertexte de table pour une instruction SQL.

Remarque

Cette procédure est en phase d'abandon. Utilisez plutôt la procédure CREATE_URL.

Syntaxe

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);

Paramètres

Paramètre Description

schema_name

Spécifie le propriétaire de l'objet.

schema_object_name

Indique l'objet de schéma (table ou vue).

sql_statement

Indique le texte de la requête d'instruction SELECT. La prise en charge des variables attachées est disponible pour les types de colonne NUMBER et VARCHAR2.

application_user_id

Spécifie une valeur d'ID utilisateur d'application. Lorsque vous accédez au lien hypertexte de table, la valeur application_user_id indiquée lors de la génération du lien hypertexte de table est disponible via :

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

Vous pouvez définir des stratégies VPD qui utilisent cette valeur dans le contexte de l'application pour restreindre les lignes visibles par l'utilisateur de l'application.

default_bind_values

Spécifie la ou les valeurs par défaut d'une ou de plusieurs variables attachées (pour une valeur sql_statement indiquée avec des variables attachées).

Cela permet à un consommateur de lien hypertexte de table d'accéder aux données de lien hypertexte de table avec des valeurs de liaison par défaut, sans fournir les valeurs de liaison en tant que paramètres de requête.

expiration_minutes

Durée en minutes de validité du lien hypertexte de table.

Le délai d'expiration maximal autorisé est de 90 jours (129600 minutes). Si la valeur est supérieure à 129600, la valeur utilisée est de 129600 minutes (90 jours).

Si expiration_minutes est spécifié en tant que valeur non NULL, expiration_count ne doit pas être défini sur une valeur non NULL. Les deux ne peuvent pas être non NULL en même temps.

Valeur par défaut : lorsque expiration_minutes n'est pas fourni ou que expiration_minutes est fourni en tant que NULL, la valeur est définie sur 90 jours (129600 minutes).

expiration_count

Nombre d'accès autorisés sur le lien hypertexte de table.

Il n'y a pas de valeur par défaut.

Si expiration_count n'est pas spécifié et que expiration_minutes n'est pas spécifié, expiration_minutes est défini sur 90 jours (129600 minutes).

Si expiration_count est spécifié en tant que valeur non NULL, expiration_minutes ne doit pas être défini sur une valeur non NULL. Les deux ne peuvent pas être non NULL en même temps.

service_name

Service de base de données à utiliser pour l'extraction des données lors de l'utilisation du lien hypertexte de table. Indiquez la garantie de niveau de service et les ressources utilisées pour traiter ce lien hypertexte de table. Par exemple, l'accès à un objet ou à une instruction SQL peut être mis en correspondance avec les services HIGH ou MEDIUM, tandis que l'accès à un autre objet ou à une autre instruction SQL peut être mis en correspondance avec le service LOW. Les valeurs prises en charge sont HIGH, MEDIUM et LOW.

La valeur par défaut est LOW.

column_lists

Valeur JSON qui spécifie les options par colonne. Les options prises en charge indiquées dans le paramètre column_lists sont les suivantes :

  • order_by_columns : indique les colonnes qui prennent en charge le tri.

  • filter_columns : indique les colonnes qui prennent en charge le filtrage.

  • default_color_columns : indique d'utiliser uniquement la coloration par défaut pour les colonnes indiquées.

  • group_by_columns : indique que le regroupement est autorisé pour les colonnes indiquées (la visualisation des données en regroupant la colonne indiquée est autorisée).

Le paramètre column_lists est un format JSON qui contient la liste des tableaux JSON de colonnes définissant la fonctionnalité de lien hypertexte de table. Utilisez ce paramètre pour indiquer les colonnes d'au moins une des options suivantes : order_by_columns, filter_columns, default_color_columns ou group_by_columns.

Le format est :

"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]
},

Par exemple : 

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

Valeurs par défaut :

Si column_lists n'est pas indiqué pour les options order_by_columns et filter_columns, le tri et le filtrage sont activés pour toutes les colonnes.

Si column_lists n'est pas spécifié pour group_by_columns, l'option Grouper par n'est activée pour aucune colonne. Par défaut, les colonnes définies pour activer en tant que group_by_columns sont également activées en tant que filter_columns.

inherit_acl

Définissez la valeur de ce paramètre sur TRUE pour hériter des listes de contrôle d'accès. Lorsque l'option Hériter a la valeur Vrai, l'adresse IP d'un consommateur de lien hypertexte de table entrant est validée avec les listes d'ACL de la base de données du producteur avant d'autoriser l'accès aux données.

Lorsque le paramètre n'est pas fourni ou que la valeur du paramètre est définie sur FALSE, les vérifications d'ACL ne sont pas appliquées.

Si aucune liste de contrôle d'accès n'est configurée pour la base de données du fournisseur, la valeur inherit_acl est ignorée et l'accès aux données est autorisé sans aucune vérification d'ACL.

La valeur par défaut est FALSE.

result

JSON indiquant le résultat de l'opération.

Notes d'utilisation

  • Cette procédure est en phase d'abandon. Utilisez plutôt la procédure CREATE_URL.

  • Il existe une limite de 128 liens hypertexte de table actifs sur une instance Autonomous Database.

  • Lorsque vous générez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée, le résultat inclut un nom private_preauth_url avec la valeur du format : "https://private-endpoint/adb/p/parurl-token/data".

    Lorsque vous générez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée et que l'adresse privée est configurée avec l'option Autoriser l'accès public activée, le résultat inclut à la fois l'adresse preauth_url pour l'adresse publique et private_preauth_url.

    Pour plus d'informations, reportez-vous à Configuration des adresses privées et à Utilisation d'une adresse privée avec accès public autorisé.

Exemple - Lien hypertexte de table généré pour un objet spécifique

L'exemple suivant génère un lien hypertexte de table pour 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;
/

Exemple - Lien hypertexte de table généré pour une instruction SQL

L'exemple suivant génère un lien hypertexte de table pour une instruction 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;
/

Exemple - Lien hypertexte de table généré pour une instruction SQL avec une variable attachée

L'exemple suivant utilise une variable attachée dans l'instruction SELECT pour générer le lien hypertexte de table : 

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

Pour utiliser le lien hypertexte de table généré, la valeur de variable attachée doit être transmise. L'exemple suivant utilise le lien hypertexte de table généré pour accéder aux données de l'arborescence du premier comté :

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

Utiliser un lien hypertexte de table pour accéder aux données avec des variables attachées

L'exemple suivant utilise une variable attachée dans l'instruction SELECT et inclut le paramètre default_bind_values pour générer le lien hypertexte de table : 

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

Dans ce cas, la valeur de variable attachée par défaut est utilisée et vous n'avez pas besoin de la fournir en tant que paramètre de requête. Par exemple :

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"}
]}

Vous pouvez remplacer la valeur de variable attachée par défaut en spécifiant explicitement la valeur en tant que paramètre de requête. Par exemple :

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

Pour plus d'informations, reportez-vous à Procédure GET_PREAUTHENTICATED_URL.

Exemple - Lien hypertexte de table généré pour un objet spécifique avec regroupement par colonnes

L'exemple suivant génère un lien hypertexte de table pour une table spécifique avec des colonnes Grouper par spécifiées :

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

EXTEND_URL Procédure

Cette procédure prolonge la durée de vie d'un lien hypertexte de table ou d'un groupe de liens hypertexte de table.

Syntaxe :

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

Paramètres

Paramètre Description

id

Indique l'ID du lien hypertexte de table ou du groupe de liens hypertexte de table à étendre.

extend_expiration_minutes_by

Nombre de minutes pendant lesquelles prolonger le délai d'expiration du lien hypertexte de table. L'heure d'expiration est définie sur l'heure d'expiration en cours plus la valeur de extend_expiration_minutes_by.

La valeur de extend_expiration_minutes_by plus le délai d'expiration actuel ne doit pas dépasser 129600 (ce qui correspond à 90 jours).

Si extend_expiration_minutes_by est NULL, extend_expiration_count_by ne doit pas être NULL. Les deux ne peuvent pas avoir la valeur NULL à la fois.

La valeur par défaut est NULL.

extend_expiration_count_by

Le nombre d'accès sur le lien hypertexte de table est étendu par ce nombre. Le nombre d'expiration est défini sur le nombre d'expiration actuel plus la valeur de extend_expiration_count_by.

Si extend_expiration_count_by est NULL, extend_expiration_minutes_by ne doit pas être NULL. Les deux ne peuvent pas avoir la valeur NULL à la fois.

La valeur par défaut est NULL.

result

JSON indiquant le résultat de l'opération.

Remarque sur l'utilisation

Avec un groupe de liens hypertexte de table id, la procédure étend tous les liens hypertexte de table membres à l'exception des membres ajoutés avec DBMS_DATA_ACCESS.ADD_MEMBER. Les membres ajoutés au groupe de liens hypertexte de table avec DBMS_DATA_ACCESS.ADD_MEMBER conservent leurs valeurs d'invalidation de lien hypertexte de table indépendantes et vous pouvez les étendre individuellement à l'aide de DBMS_DATA_ACCESS.EXTEND_URL.

Exemple - Prolonger les minutes d'expiration du lien hypertexte de table

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

Exemple - Prolonger le nombre d'expirations du lien hypertexte de table

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

INVALIDATE_URL Procédure

Cette procédure invalide un lien hypertexte de table ou un groupe de liens hypertexte de table.

Syntaxe

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

Paramètres

Paramètre Description

id

Indique l'identificateur du lien hypertexte de table ou du groupe de liens hypertexte de table à invalider.

kill_sessions

Ce paramètre est facultatif.

Par défaut, lorsque vous exécutez DBMS_DATA_ACCESS.INVALIDATE_URL, les sessions existantes qui peuvent se trouver au milieu de l'accès aux données à l'aide d'un lien hypertexte de table ou d'un groupe de liens hypertexte de table ne sont pas arrêtées. Lorsque ce paramètre est défini sur TRUE, cette valeur indique que ces sessions existantes doivent être arrêtées, de sorte que l'invalidation ne laisse aucun accès en cours à un ensemble de données.

Valeurs valides : TRUE | FALSE.

result

Fournit le format JSON pour indiquer si l'invalidation est un succès ou un échec (CLOB).

Remarque sur l'utilisation

Lorsque le paramètre DBMS_DATA_ACCESS.INVALIDATE_URL id est un groupe de liens hypertexte de table, la procédure invalide le groupe et tous les membres du groupe, à l'exception de tous les membres de groupe ajoutés avec DBMS_DATA_ACCESS.ADD_MEMBER. Après avoir exécuté DBMS_DATA_ACCESS.INVALIDATE_URL, les membres ajoutés avec DBMS_DATA_ACCESS.ADD_MEMBER conservent leurs valeurs d'invalidation de lien hypertexte de table indépendantes et vous pouvez invalider ces liens hypertexte de table individuellement à l'aide de DBMS_DATA_ACCESS.INVALIDATE_URL.

Exemple

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

Fonction LIST_ACTIVE_URLS

Cette fonction répertorie tous les liens hypertexte de table et les groupes de liens hypertexte de table actuellement actifs.

Syntaxe

DBMS_DATA_ACCESS.LIST_ACTIVE_URLS RETURN CLOB;

Paramètres

Paramètre Description
RETURN

La valeur renvoyée est un tableau JSON.

Exemple

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"}]

Notes d'utilisation

  • Le comportement de DBMS_DATA_ACCESS.LIST_ACTIVE_URLS dépend de l'appelant. Si l'appelant est ADMIN ou tout utilisateur doté du rôle PDB_DBA, la fonction répertorie tous les liens hypertexte de table actifs, quel que soit l'utilisateur qui a généré le lien hypertexte de table. Si l'appelant n'est pas l'utilisateur ADMIN et n'est pas un utilisateur doté du rôle PDB_DBA, la liste inclut uniquement les liens hypertexte de table actifs générés par l'appelant.

  • Lorsque vous générez et répertoriez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée, le résultat inclut un nom private_preauth_url avec la valeur du format : "https://private-endpoint/adb/p/parurl-token/data".

    Lorsque vous générez et répertoriez un lien hypertexte de table sur une instance Autonomous Database avec une adresse privée et que l'adresse privée est configurée avec l'option Autoriser l'accès public activée, le résultat inclut à la fois l'adresse preauth_url pour l'adresse publique et private_preauth_url.

    Pour plus d'informations, reportez-vous à Configuration des adresses privées et à Utilisation d'une adresse privée avec accès public autorisé.

  • Lorsqu'un lien hypertexte de table est un membre de groupe, l'entrée de réponse DBMS_DATA_ACCESS.LIST_ACTIVE_URLS affiche "group_ids" avec une valeur non NULL qui inclut un ou plusieurs ID. Les ID affichent les ID de groupe de liens hypertexte de table dont le lien hypertexte de table (membre du groupe) est membre.

Procédure LIST_MEMBERS

Cette procédure répertorie les membres d'un groupe de liens hypertexte de table.

Syntaxe

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

Paramètres

Paramètre Description

id

Spécifie l'identificateur du groupe de liens hypertexte de table.

result

Fournit le format JSON pour indiquer si l'invalidation est un succès ou un échec (CLOB).

Exemple

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

Procédure REMOVE_MEMBER

Cette procédure supprime un membre d'un groupe de liens hypertexte de table.

Syntaxe

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

Paramètres

Paramètre Description

id

Spécifie l'identificateur du groupe de liens hypertexte de table.
member_id

Spécifie l'identificateur du membre de groupe à supprimer du groupe de liens hypertexte de table.

result

Fournit le format JSON pour indiquer si l'invalidation est un succès ou un échec (CLOB).

Notes d'utilisation

  • La valeur member_id ne peut pas être un ID de groupe de liens hypertexte de table (is_group_url doit être false).

  • Si le membre enlevé est un lien hypertexte de table existant qui a été ajouté au groupe à l'aide de DBMS_DATA_ACCESS.ADD_MEMBER, le membre est enlevé du groupe, mais le lien hypertexte de table est accessible directement jusqu'à ce qu'il soit explicitement invalidé ou expire.

  • Si un groupe de liens hypertexte de table ne contient qu'un seul membre et que ce membre est supprimé, le groupe est invalidé.

Exemple

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