Documentação do Oracle Cloud Infrastructure

Pacote DBMS_DATA_ACCESS

O pacote DBMS_DATA_ACCESS fornece rotinas para gerar e gerenciar Hiperlinks de Tabela para conjuntos de dados.

Tópico principal: Referência de Pacote Fornecida pelo Autonomous Database

DBMS_DATA_ACCESS Visão Geral

Descreve o uso do pacote DBMS_DATA_ACCESS.

O DBMS_DATA_ACCESS suporta estas operações:

  • Geração de um Hyperlink de Tabela
  • Invalidação manual de um Hiperlink de Tabela
  • Listagem de Hiperlinks de Tabela ativos

Tópico principal: Pacote DBMS_DATA_ACCESS

DBMS_DATA_ACCESS Modelo de Segurança

A segurança neste pacote pode ser controlada concedendo EXECUTE neste pacote a usuários ou atribuições selecionados.

Quando um usuário recebe EXECUTE em DBMS_DATA_ACCESS, ele pode criar, listar ou invalidar os Hiperlinks de Tabela criados pelo usuário. Além disso, por padrão, o usuário ADMIN tem os seguintes privilégios:
  • O usuário ADMIN com a atribuição PDB_DBA tem o privilégio EXECUTE em DBMS_DATA_ACCESS.
  • O usuário ADMIN com a atribuição PDB_DBA pode listar ou invalidar qualquer Hiperlink de Tabela em uma instância do Autonomous Database.

Tópico principal: Pacote DBMS_DATA_ACCESS

Resumo de Subprogramas DBMS_DATA_ACCESS

Esta seção abrange os subprogramas DBMS_DATA_ACCESS fornecidos com o Autonomous Database.

Subprograma Descrição

Procedimento GET_PREAUTHENTICATED_URL

Este procedimento gera um Hiperlink de Tabela.

Procedimento EXTEND_URL

Este procedimento prolonga a vida útil de um Hiperlink de Tabela.

Procedimento INVALIDATE_URL

Este procedimento invalida um Hiperlink de Tabela.

Função LIST_ACTIVE_URLS

Esta função lista todos os Hiperlinks de Tabela ativos no momento.

Tópico principal: Pacote DBMS_DATA_ACCESS

Procedimento GET_PREAUTHENTICATED_URL

Este procedimento gera um Hiperlink de Tabela.

Há dois formulários, um para gerar o Hiperlink de Tabela para um objeto específico (tabela ou view). O formulário sobrecarregado, usando o parâmetro sql_statement, gera um Hiperlink de Tabela para uma instrução SQL.

Sintaxe

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    schema_name           IN VARCHAR2,
    schema_object_name    IN VARCHAR2,
    application_user_id   IN VARCHAR2,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL( 
    sql_statement         IN CLOB,
    application_user_id   IN VARCHAR2,
    default_bind_values   IN CLOB,
    expiration_minutes    IN NUMBER,
    expiration_count      IN NUMBER,
    service_name          IN VARCHAR2,
    column_lists          IN CLOB,
    inherit_acl           IN BOOLEAN  DEFAULT FALSE,
    result                OUT CLOB);

Parâmetros

Parâmetro Descrição

schema_name

Especifica o proprietário do objeto.

schema_object_name

Especifica o objeto de esquema (tabela ou view).

sql_statement

Especifica o texto da consulta da instrução SELECT. O suporte a variáveis de bind está disponível para os tipos de coluna NUMBER e VARCHAR2.

application_user_id

Especifica um valor de ID de usuário do aplicativo. Quando o Hiperlink da Tabela é acessado, o valor de application_user_id especificado durante a geração do Hiperlink da Tabela está disponível por meio de:

sys_context('DATA_ACCESS_CONTEXT$', 'USER_IDENTITY')

Você pode definir Políticas de VPD que fazem uso desse valor no Contexto do Aplicativo para restringir as linhas visíveis para o usuário do aplicativo.

default_bind_values

Especifica o(s) valor(es) padrão(is) de uma ou mais variáveis de bind (para um sql_statement especificado com variáveis de bind).

Isso permite que um consumidor de hiperlink de tabela acesse os dados de hiperlink de tabela com valores de vínculo padrão, sem fornecer os valores de vínculo como parâmetros de consulta.

expiration_minutes

Duração em minutos de validade do Hiperlink de Tabela.

O tempo máximo de expiração permitido é de 90 dias (129600 minutos). Se o valor for definido como maior que 129600, o valor usado será 129600 minutos (90 dias).

Se expiration_minutes for especificado como um valor não nulo, expiration_count não deverá ser definido como um valor não nulo. Ambos não podem ser não nulos ao mesmo tempo.

Valor padrão: quando expiration_minutes não é fornecido ou quando expiration_minutes é fornecido como NULL, o valor é definido como 90 dias (129600 minutos).

expiration_count

Número de acessos permitidos no Hiperlink da Tabela.

Não há valor padrão.

Se expiration_count não for especificado e expiration_minutes não for especificado, expiration_minutes será definido como 90 dias (129600 minutos).

Se expiration_count for especificado como um valor não nulo, expiration_minutes não deverá ser definido como um valor não nulo. Ambos não podem ser não nulos ao mesmo tempo.

service_name

O serviço de banco de dados a ser usado para recuperação de dados ao usar o Hiperlink de Tabela. Especifique a garantia de nível de serviço e os recursos usados para atender a este Hiperlink de Tabela. Por exemplo, o acesso a um objeto ou instrução SQL pode ser mapeado para os serviços HIGH ou MEDIUM, enquanto o acesso a outro objeto ou instrução SQL pode ser mapeado para o serviço LOW. Os valores suportados são HIGH, MEDIUM, LOW.

O valor padrão é LOW.

column_lists

Um valor JSON que especifica opções por coluna. As opções suportadas especificadas no parâmetro column_lists são uma ou mais de:

  • order_by_columns: especifica as colunas que suportam classificação.

  • filter_columns: especifica as colunas que suportam filtragem

  • default_color_columns: especifica para usar apenas a coloração padrão para as colunas especificadas.

  • group_by_columns: especifica que agrupar por é permitido para as colunas especificadas (a exibição dos dados agrupando a coluna especificada é permitida).

O parâmetro column_lists é JSON que contém uma lista de arrays JSON de colunas que definem a funcionalidade Hiperlink da Tabela. Use esse parâmetro para especificar as colunas para uma ou mais das opções: order_by_columns, filter_columns, default_color_columns ou group_by_columns.

O formato é o seguinte:

"column_lists" : {
        "order_by_columns": [order_by_columns_list],
        "filter_columns": [filter_columns_list],
        "default_color_columns": [default_color_columns_list],
        "group_by_columns": [group_by_columns_list]
},

Por exemplo: 

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

Valores default:

Se column_lists não for especificado para as opções order_by_columns e filter_columns, a classificação e a filtragem serão ativadas para todas as colunas.

Se column_lists não for especificado para group_by_columns, a opção agrupar por não será ativada para nenhuma coluna. Por padrão, as colunas definidas para ativar como group_by_columns também são ativadas como filter_columns.

inherit_acl

Defina o valor desse parâmetro como TRUE para herdar as ACLs. Quando a herança é verdadeira, o endereço IP de um consumidor de Hiperlink de Tabela de entrada é validado com as listas ACL no banco de dados do produtor antes de permitir o acesso aos dados.

Quando o parâmetro não é fornecido ou o valor do parâmetro é definido como FALSE, as verificações de ACL não são aplicadas.

Se o banco de dados do produtor não tiver ACLs configuradas, o valor inherit_acl será ignorado e o acesso aos dados será permitido sem nenhuma verificação de ACL.

O valor padrão é FALSE.

result

JSON que indica o resultado da operação.

Observações de Uso

  • Há um limite de 128 Hiperlinks de Tabela ativos em uma instância do Autonomous Database.

  • Ao usar um Hiperlink de Tabela de um navegador, as seguintes opções são suportadas:
    • Exiba os dados retornados no formato de tabela sem coloração (padrão), anexando o parâmetro de consulta ?view=table ao Hiperlink da Tabela.
    • Exiba os dados retornados no formato de tabela e selecione a(s) coluna(s) que deseja colorir com cores predefinidas com base nos valores da coluna. Para fazer isso, anexe o parâmetro de consulta ?view=table&colored_column_names=column_name_1,column_name_2,...column_name_n ao Hiperlink de Tabela, em que column_name_1 a column_name_n são os nomes das colunas que você deseja colorir.
    • Exiba os dados retornados no formato de tabela e selecione um tipo de dados de coluna específico que você deseja colorir com cores predefinidas, anexando o parâmetro de consulta ?view=table&colored_column_types=data_type. Os valores de parâmetro data_type suportados são VARCHAR e NONE.

    • O valor do parâmetro sql_statement deve ser uma instrução SELECT. A instrução SELECT suporta variáveis de bind.

      Se as variáveis de bind forem incluídas na instrução select e os valores não estiverem definidos no parâmetro default_bind_values, os valores das variáveis de bind deverão ser anexados ao Hiperlink de Tabela gerado como um parâmetro de consulta ao acessar os dados.

      Ao incluir o parâmetro default_bind_values, ao acessar os dados, você pode omitir os valores de variável de bind quando os valores padrão forem especificados no parâmetro default_bind_values. Você pode substituir um valor de variável de vinculação padrão especificado por default_bind_values fornecendo explicitamente o valor de variável de vinculação como um parâmetro de consulta.

  • Quando você gera um Hiperlink de Tabela em uma instância do Autonomous Database com um ponto final privado, o resultado inclui um nome private_preauth_url com o valor do formato: "https://private-endpoint/adb/p/parurl-token/data".

    Quando você gera um Hiperlink de Tabela em uma instância do Autonomous Database com um ponto final privado e o ponto final privado é configurado com a opção Permitir acesso público ativada, o resultado inclui o preauth_url do ponto final público e o private_preauth_url.

    Consulte Configurar Pontos Finais Privados e Usar um Ponto Final Privado com Acesso Público Permitido para obter mais informações.

Exemplo - Hiperlink de Tabela Gerado para um Objeto Específico

O exemplo a seguir gera um Hiperlink de Tabela para STUDENTS_VIEW: 

DECLARE
   status CLOB;
   BEGIN
   DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
      schema_name => 'USER1',
      schema_object_name => 'STUDENTS_VIEW',
      expiration_minutes => 120,
      service_name => 'HIGH',
      result => status);
   dbms_output.put_line(status);
END;
/

Exemplo - Hiperlink de Tabela Gerado para uma Instrução SQL

O exemplo a seguir gera um Hiperlink de Tabela para uma instrução 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;
/

Exemplo - Hiperlink de Tabela Gerado para uma Instrução SQL com uma Variável de Bind

O exemplo a seguir usa uma variável de bind na instrução SELECT para gerar o Hiperlink da Tabela: 

set serveroutput on 
DECLARE
  status clob; 
BEGIN
  DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
    sql_statement => 'select * from TREE_DATA WHERE COUNTY = :countyNAME',
    expiration_minutes => 3000,
    result => status);
    dbms_output.put_line('status : '||status);
END;
/

Para usar o Hiperlink de Tabela gerado, o valor da variável de bind deve ser informado. O exemplo a seguir usa o Hiperlink de Tabela gerado para acessar os dados da árvore do primeiro condado:

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

Usar Hiperlink de Tabela para Acessar Dados com Variáveis de Bind

O exemplo a seguir usa uma variável de bind na instrução SELECT e inclui o parâmetro default_bind_values para gerar o Hiperlink da Tabela: 

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

Nesse caso, o valor da variável de bind padrão é usado e você não precisa fornecer o valor como um parâmetro de consulta. Por exemplo:

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

Você pode substituir o valor de variável de vinculação padrão especificando explicitamente o valor como um parâmetro de consulta. Por exemplo:

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

Consulte GET_PREAUTHENTICATED_URL Procedure para obter mais informações.

Exemplo - Hiperlink de Tabela Gerado para um Objeto Específico com Colunas Agrupar por

O exemplo a seguir gera um Hiperlink de Tabela para uma tabela específica com colunas Agrupar por especificadas:

DECLARE
   status CLOB;
   BEGIN
      DBMS_DATA_ACCESS.GET_PREAUTHENTICATED_URL(
          schema_name => 'ADMIN',
          schema_object_name    => 'TREE_DATA',
          expiration_minutes    => 360,
          service_name          => 'HIGH',
          column_lists          => {"group_by_columns": ["COUNTY", "SPECIES"]}',
          result                => status);

       dbms_output.put_line(status);
    END;
/

Procedimento EXTEND_URL

Este procedimento prolonga a vida útil de um Hiperlink de Tabela.

sintaxe:

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

Parâmetros

Parâmetro Descrição

id

Especifica o ID do Hiperlink da Tabela a ser estendido.

extend_expiration_minutes_by

Número de minutos pelos quais estender o tempo de expiração do Hiperlink da Tabela. O tempo de expiração é definido como o tempo de expiração atual mais o valor de extend_expiration_minutes_by.

O valor de extend_expiration_minutes_by mais o tempo de expiração atual não deve exceder 129600 (que corresponde a 90 dias).

Se extend_expiration_minutes_by for nulo, extend_expiration_count_by não deverá ser nulo. Ambos não podem ser nulos ao mesmo tempo.

O valor default é NULL.

extend_expiration_count_by

O número de acessos no Hiperlink da Tabela é estendido por essa contagem. A contagem de expiração é definida como a contagem de expiração atual mais o valor de extend_expiration_count_by.

Se extend_expiration_count_by for nulo, extend_expiration_minutes_by não deverá ser nulo. Ambos não podem ser nulos ao mesmo tempo.

O valor padrão é nulo.

result

JSON que indica o resultado da operação.

Exemplo - Estender Minutos de Expiração do Hiperlink da Tabela

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

Exemplo - Estender Contagem de Expirações do Hiperlink da Tabela

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

Procedimento INVALIDATE_URL

Este procedimento invalida um Hiperlink de Tabela.

Sintaxe

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

Parâmetros

Parâmetro Descrição

id

Especifica o proprietário do objeto.

kill_sessions

Por padrão, as sessões existentes que podem estar no meio do acesso aos dados usando um Hiperlink de Tabela não são eliminadas. Quando VERDADEIRO, esse parâmetro especifica que essas sessões existentes devem ser eliminadas, para que a invalidação não deixe nenhum acesso contínuo ao conjunto de dados.

Valores válidos: TRUE | FALSE.

result

Fornece JSON para indicar se a invalidação é um sucesso ou uma falha (CLOB).

Função LIST_ACTIVE_URLS

Esta função lista todos os Hiperlinks de Tabela e Grupos de Hiperlinks de Tabela atualmente ativos.

Sintaxe

DBMS_DATA_ACCESS.LIST_ACTIVE_URLS RETURN CLOB;

Parâmetros

Parâmetro Descrição
RETURN

O valor de retorno é um array JSON.

Exemplo

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

Observações de Uso

  • O comportamento de DBMS_DATA_ACCESS.LIST_ACTIVE_URLS depende do chamador. Se o chamador for ADMIN ou qualquer usuário com a atribuição PDB_DBA, a função listará todos os Hiperlinks de Tabela ativos, independentemente do usuário que gerou o Hiperlink de Tabela. Se o chamador não for o usuário ADMIN e não for um usuário com a atribuição PDB_DBA, a lista incluirá apenas os Hiperlinks de Tabela ativos gerados pelo chamador.

  • Quando você gera e lista um Hiperlink de Tabela em uma instância do Autonomous Database com um ponto final privado, o resultado inclui um nome private_preauth_url com o valor do formato: "https://private-endpoint/adb/p/parurl-token/data".

    Quando você gera e lista um Hiperlink de Tabela em uma instância do Autonomous Database com um ponto final privado e o ponto final privado é configurado com a opção Permitir acesso público ativada, o resultado inclui o preauth_url para o ponto final público e o private_preauth_url.

    Consulte Configurar Pontos Finais Privados e Usar um Ponto Final Privado com Acesso Público Permitido para obter mais informações.

  • Quando um Hiperlink de Tabela é um membro do grupo, a entrada de resposta DBMS_DATA_ACCESS.LIST_ACTIVE_URLS mostra "group_ids" com um valor não nulo que inclui um ou mais IDs. Os IDs mostram os IDs do Grupo de Hiperlinks da Tabela dos quais o Hiperlink da Tabela (membro do grupo) é membro.