Pacchetto DBMS_DATA_ACCESS

Il pacchetto DBMS_DATA_ACCESS fornisce routine per generare e gestire i collegamenti ipertestuali delle tabelle per i data set.

DBMS_DATA_ACCESS Panoramica

Descrive l'uso del pacchetto DBMS_DATA_ACCESS.

DBMS_DATA_ACCESS supporta le operazioni riportate di seguito.

  • Generazione di un collegamento ipertestuale tabella
  • Annullamento manuale del collegamento ipertestuale di una tabella
  • Elenco di collegamenti ipertestuali tabella attivi

DBMS_DATA_ACCESS Modello di sicurezza

La sicurezza in questo pacchetto può essere controllata concedendo EXECUTE a utenti o ruoli selezionati in questo pacchetto.

Quando a un utente è stato concesso EXECUTE su DBMS_DATA_ACCESS, è possibile creare, elencare o invalidare i collegamenti ipertestuali di tabella creati dall'utente. Inoltre, per impostazione predefinita, l'utente ADMIN dispone dei seguenti privilegi:
  • L'utente ADMIN con ruolo PDB_DBA dispone del privilegio EXECUTE su DBMS_DATA_ACCESS.
  • L'utente ADMIN con il ruolo PDB_DBA può elencare o invalidare qualsiasi collegamento ipertestuale di tabella in un'istanza di Autonomous Database.

Riepilogo dei sottoprogrammi DBMS_DATA_ACCESS

In questa sezione vengono descritti i sottoprogrammi DBMS_DATA_ACCESS forniti con Autonomous Database.

Programma secondario descrizione;

GET_PREAUTHENTICATED_URL Procedura

Questa procedura genera un collegamento ipertestuale tabella.

EXTEND_URL Procedura

Questa procedura estende la durata di un collegamento ipertestuale alla tabella.

INVALIDATE_URL Procedura

Questa procedura invalida un collegamento ipertestuale di tabella.

Funzione LIST_ACTIVE_URLS

Questa funzione elenca tutti i collegamenti ipertestuali della tabella attualmente attivi.

GET_PREAUTHENTICATED_URL Procedura

Questa procedura genera un collegamento ipertestuale tabella.

Esistono due moduli, uno per generare il collegamento ipertestuale tabella per un oggetto specifico (tabella o vista). Il form sovraccarico, utilizzando il parametro sql_statement, genera un collegamento ipertestuale tabella per un'istruzione SQL.

Sintassi

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

Parametri

Parametro descrizione;

schema_name

Specifica il proprietario dell'oggetto.

schema_object_name

Specifica l'oggetto dello schema (tabella o vista).

sql_statement

Specifica il testo della query dell'istruzione SELECT. Il supporto delle variabili di binding è disponibile per i tipi di colonna NUMBER e VARCHAR2.

application_user_id

Specifica un valore ID utente applicazione. Quando si accede al collegamento ipertestuale tabella, il valore application_user_id specificato durante la generazione del collegamento ipertestuale tabella è disponibile tramite:

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

È possibile definire criteri VPD che utilizzano questo valore nel contesto dell'applicazione per limitare la visibilità delle righe per l'utente dell'applicazione.

default_bind_values

Specifica i valori predefiniti di una o più bind variable (per un valore sql_statement specificato con bind variable).

Ciò consente a un consumer di collegamenti ipertestuali di tabella di accedere ai dati dei collegamenti ipertestuali di tabella con valori di associazione predefiniti, senza fornire i valori di associazione come parametri di query.

expiration_minutes

Durata in minuti di validità del collegamento ipertestuale tabella.

Il tempo di scadenza massimo consentito è di 90 giorni (129600 minuti). Se il valore è impostato su un valore maggiore di 129600, il valore utilizzato è 129600 minuti (90 giorni).

Se si specifica expiration_minutes come valore non nullo, expiration_count non deve essere impostato su un valore non nullo. Entrambi non possono essere non nulli contemporaneamente.

Valore predefinito: se expiration_minutes non viene fornito o se expiration_minutes viene fornito come NULL, il valore viene impostato su 90 giorni (129600 minuti).

expiration_count

Numero di accessi consentiti nel collegamento ipertestuale tabella.

Non è disponibile alcun valore predefinito.

Se expiration_count non viene specificato e expiration_minutes non viene specificato, expiration_minutes viene impostato su 90 giorni (129600 minuti).

Se si specifica expiration_count come valore non nullo, expiration_minutes non deve essere impostato su un valore non nullo. Entrambi non possono essere non nulli contemporaneamente.

service_name

Servizio di database da utilizzare per il recupero dei dati quando si utilizza il collegamento ipertestuale tabella. Specificare la garanzia a livello di servizio e le risorse utilizzate per servire questo collegamento ipertestuale tabella. Ad esempio, l'accesso a un oggetto o a un'istruzione SQL può essere mappato ai servizi HIGH o MEDIUM, mentre l'accesso a un altro oggetto o istruzione SQL può essere mappato al servizio LOW. I valori supportati sono HIGH, MEDIUM, LOW.

Il valore predefinito è LOW.

column_lists

Valore JSON che specifica le opzioni per colonna. Le opzioni supportate specificate nel parametro column_lists sono una o più delle seguenti:

  • order_by_columns: specifica le colonne che supportano l'ordinamento.

  • filter_columns: specifica le colonne che supportano il filtro

  • default_color_columns: specifica di utilizzare solo la colorazione predefinita per le colonne specificate.

  • group_by_columns: specifica che group by è consentito per le colonne specificate (la visualizzazione dei dati mediante il raggruppamento della colonna specificata è consentita).

Il parametro column_lists è JSON che contiene una lista di array JSON di colonne che definiscono la funzionalità Collegamento ipertestuale tabella. Utilizzare questo parametro per specificare le colonne per una o più opzioni: order_by_columns, filter_columns, default_color_columns o group_by_columns.

Il formato è il seguente:

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

Ad esempio:

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

Valori predefiniti:

Se non si specifica column_lists per le opzioni order_by_columns e filter_columns, l'ordinamento e il filtro vengono abilitati per tutte le colonne.

Se column_lists non è specificato per group_by_columns, l'opzione Raggruppa per non è abilitata per alcuna colonna. Per impostazione predefinita, anche le colonne definite per abilitare group_by_columns sono abilitate come filter_columns.

inherit_acl

Impostare il valore di questo parametro su TRUE per ereditare le ACL. Quando l'ereditarietà è vera, l'indirizzo IP di un consumer di collegamento ipertestuale tabella in entrata viene convalidato con gli elenchi ACL nel database del producer prima di consentire l'accesso ai dati.

Se il parametro non viene fornito o il valore del parametro è impostato su FALSE, i controlli ACL non vengono applicati.

Se nel database del producer non sono configurate ACL, il valore inherit_acl viene ignorato e l'accesso ai dati è consentito senza alcun controllo ACL.

Il valore predefinito è FALSE.

result

JSON che indica il risultato dell'operazione.

Note sull'uso

  • È previsto un limite di 128 collegamenti ipertestuali di tabella attivi in un'istanza di Autonomous Database.

  • Quando si utilizza un collegamento ipertestuale di tabella da un browser, sono supportate le opzioni riportate di seguito.
    • Visualizzare i dati restituiti in formato tabella senza colorazione (impostazione predefinita) aggiungendo il parametro di query ?view=table al collegamento ipertestuale tabella.
    • Visualizzare i dati restituiti in formato tabella e selezionare la colonna o le colonne da colorare con colori predefiniti in base ai valori delle colonne. A tale scopo, aggiungere il parametro di query ?view=table&colored_column_names=column_name_1,column_name_2,...column_name_n al collegamento ipertestuale tabella, dove da column_name_1 a column_name_n sono i nomi delle colonne da colorare.
    • Visualizzare i dati restituiti in formato tabella e selezionare un tipo di dati di colonna specifico da colorare con colori preimpostati, aggiungendo il parametro di query ?view=table&colored_column_types=data_type. I valori dei parametri data_type supportati sono VARCHAR e NONE.
    • Il valore del parametro sql_statement deve essere un'istruzione SELECT. L'istruzione SELECT supporta le bind variable.

      Se le bind variable sono incluse nell'istruzione select e i valori non sono impostati nel parametro default_bind_values, i valori delle bind variable devono essere aggiunti al collegamento ipertestuale tabella generato come parametro di query quando si accede ai dati.

      Quando si include il parametro default_bind_values, quando si accede ai dati è possibile omettere i valori delle bind variable quando vengono specificati valori predefiniti nel parametro default_bind_values. È possibile sostituire un valore di bind variable predefinito specificato con default_bind_values specificando in modo esplicito il valore della bind variable come parametro di query.

  • Quando si genera un collegamento ipertestuale tabella in un'istanza di Autonomous Database con un endpoint privato, il risultato include un nome private_preauth_url con il valore del formato: "https://private-endpoint/adb/p/parurl-token/data".

    Quando si genera un collegamento ipertestuale tabella in un'istanza di Autonomous Database con un endpoint privato e l'endpoint privato viene configurato con l'opzione Consenti accesso pubblico abilitata, il risultato include sia l'opzione preauth_url per l'endpoint pubblico che l'opzione private_preauth_url.

    Per ulteriori informazioni, vedere Configura endpoint privati e Usa un endpoint privato con accesso pubblico consentito.

Esempio - Collegamento ipertestuale tabella generato per un oggetto specifico

L'esempio riportato di seguito genera un collegamento ipertestuale tabella per 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;
/

Esempio - Collegamento ipertestuale tabella generato per un'istruzione SQL

Nell'esempio riportato di seguito viene generato un collegamento ipertestuale tabella per un'istruzione 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;
/

Esempio - Collegamento ipertestuale tabella generato per un'istruzione SQL con una variabile di binding

Nell'esempio seguente viene utilizzata una bind variable nell'istruzione SELECT per generare il collegamento ipertestuale tabella:

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

Per utilizzare il collegamento ipertestuale tabella generato, è necessario passare il valore della bind variable. Nell'esempio riportato di seguito viene utilizzato il collegamento ipertestuale tabella generato per accedere ai dati della struttura ad albero per la prima provincia.

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

Usa collegamento ipertestuale tabella per accedere ai dati con variabili di binding

L'esempio seguente utilizza una bind variable nell'istruzione SELECT e include il parametro default_bind_values per generare il collegamento ipertestuale tabella.

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

In questo caso, viene utilizzato il valore della bind variable predefinito e non è necessario fornire il valore come parametro di query. Ad esempio:

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

È possibile sostituire il valore della bind variable predefinita specificando in modo esplicito il valore come parametro di query. Ad esempio:

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

Per ulteriori informazioni, vedere GET_PREAUTHENTICATED_URL Procedure.

Esempio - Collegamento ipertestuale tabella generato per un oggetto specifico con colonne Raggruppa per

Nell'esempio riportato di seguito viene generato un collegamento ipertestuale tabella per una tabella specifica con le colonne Raggruppa per specificate.

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 Procedura

Questa procedura estende la durata di un collegamento ipertestuale alla tabella.

Sintassi:

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

Parametri

Parametro descrizione;

id

Specifica l'ID del collegamento ipertestuale tabella da estendere.

extend_expiration_minutes_by

Numero di minuti di estensione dell'ora di scadenza del collegamento ipertestuale tabella. L'ora di scadenza viene impostata sull'ora di scadenza corrente più il valore extend_expiration_minutes_by.

Il valore di extend_expiration_minutes_by più l'ora di scadenza corrente non deve superare 129600 (che corrisponde a 90 giorni).

Se extend_expiration_minutes_by è nullo, extend_expiration_count_by non deve essere nullo. Entrambi non possono essere nulli contemporaneamente.

Il valore predefinito è NULL.

extend_expiration_count_by

Il numero di accessi nel collegamento ipertestuale tabella viene esteso da questo conteggio. Il conteggio delle scadenze viene impostato sul conteggio delle scadenze correnti più il valore extend_expiration_count_by.

Se extend_expiration_count_by è nullo, extend_expiration_minutes_by non deve essere nullo. Entrambi non possono essere nulli contemporaneamente.

Il valore predefinito è nullo.

result

JSON che indica il risultato dell'operazione.

Esempio - Estendi minuti scadenza collegamento ipertestuale tabella

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

Esempio - Estendi conteggio scadenze del collegamento ipertestuale tabella

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 Procedura

Questa procedura invalida un collegamento ipertestuale di tabella.

Sintassi

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

Parametri

Parametro descrizione;

id

Specifica il proprietario dell'oggetto.

kill_sessions

Per impostazione predefinita, le sessioni esistenti che potrebbero trovarsi nel mezzo dell'accesso ai dati mediante un collegamento ipertestuale tabella non vengono interrotte. Se impostato su TRUE, questo parametro specifica che tali sessioni esistenti devono essere interrotte, in modo che l'annullamento della convalida non lasci alcun accesso in corso al data set.

Valori validi: TRUE | FALSE.

result

Fornisce il formato JSON per indicare se l'annullamento della convalida è un'operazione riuscita o un errore (CLOB).

Funzione LIST_ACTIVE_URLS

Questa funzione elenca tutti i collegamenti ipertestuali tabella e i gruppi di collegamenti ipertestuali tabella attualmente attivi.

Sintassi

DBMS_DATA_ACCESS.LIST_ACTIVE_URLS RETURN CLOB;

Parametri

Parametro Descrizione
RETURN

Il valore restituito è un array JSON.

Esempio

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

Note sull'uso

  • Il funzionamento di DBMS_DATA_ACCESS.LIST_ACTIVE_URLS dipende dal chiamante. Se il chiamante è ADMIN o qualsiasi utente con ruolo PDB_DBA, la funzione elenca tutti i collegamenti ipertestuali di tabella attivi, indipendentemente dall'utente che ha generato il collegamento ipertestuale di tabella. Se il chiamante non è l'utente ADMIN e non un utente con ruolo PDB_DBA, l'elenco include solo i collegamenti ipertestuali di tabella attivi generati dal chiamante.

  • Quando si genera ed elenca un collegamento ipertestuale tabella in un'istanza di Autonomous Database con un endpoint privato, il risultato include un nome private_preauth_url con il valore del formato: "https://private-endpoint/adb/p/parurl-token/data".

    Quando si genera ed elenca un collegamento ipertestuale tabella in un'istanza di Autonomous Database con un endpoint privato e l'endpoint privato è configurato con l'opzione Consenti accesso pubblico abilitata, il risultato include sia l'opzione preauth_url per l'endpoint pubblico che l'opzione private_preauth_url.

    Per ulteriori informazioni, vedere Configura endpoint privati e Usa un endpoint privato con accesso pubblico consentito.

  • Quando un collegamento ipertestuale tabella è un membro di gruppo, la voce di risposta DBMS_DATA_ACCESS.LIST_ACTIVE_URLS mostra "group_ids" con un valore non nullo che include uno o più ID. Gli ID mostrano gli ID del gruppo di collegamenti ipertestuali tabella di cui è membro il collegamento ipertestuale tabella (membro del gruppo).