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

ADD_MEMBER Procedimento

CREATE_URL Procedimento

Este procedimento gera um Hiperlink de Tabela ou um Grupo de Hiperlink de Tabela.

EXTEND_URL Procedimento

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

Procedimento GET_PREAUTHENTICATED_URL

Este procedimento gera um Hiperlink de Tabela.

Este procedimento está obsoleto. Em vez dele, use o procedimento CREATE_URL.

EXTEND_URL Procedimento

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

INVALIDATE_URL Procedimento

Este procedimento invalida um Hiperlink de Tabela.

Função LIST_ACTIVE_URLS

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

LIST_MEMBERS Procedimento

REMOVE_MEMBER Procedimento

Tópico principal: Pacote DBMS_DATA_ACCESS

ADD_MEMBER Procedimento

Este procedimento adiciona um Hiperlink de Tabela existente ao Grupo de Hiperlinks de Tabela como membro.

Sintaxe

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

Parâmetros

Parâmetro Descrição

id

Especifica o identificador do Grupo de Hiperlinks da Tabela.
member_id

Especifica o identificador do Hiperlink da Tabela a ser adicionado ao grupo.

result

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

Exemplo

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

CREATE_URL Procedimento

Este procedimento gera um Hiperlink de Tabela ou um Grupo de Hiperlink de Tabela. Um Grupo de Hiperlinks de Tabela fornece acesso a vários Hiperlinks de Tabela com um único URL. Este procedimento é sobrecarregado.

Sintaxe

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

Parâmetros

Parâmetro Descrição

sqls

Especifica um array JSON das instruções SELECT ou dos objetos de esquema.

Consulte a descrição a seguir para obter detalhes sobre o formato do array JSON.

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

Esse parâmetro opcional especifica um valor de ID usuário do aplicativo. Quando o Hiperlink da Tabela ou o Grupo de Hiperlink da Tabela é acessado, o valor 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

Este parâmetro opcional especifica a duração em minutos de validade do Hiperlink da Tabela ou do Grupo de Hiperlink da 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

Esse parâmetro opcional especifica o número de acessos permitidos no Hiperlink da Tabela ou no Grupo de 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

Esse parâmetro é opcional. Defina o valor como TRUE para herdar ACLs. Quando esse parâmetro é TRUE, o endereço IP do consumidor de um Hiperlink de Tabela ou Hyperlink 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.

O formato do array JSON que você fornece como parâmetro sqls é:

Nome do Atributo Obrigatório Descrição
name Não Especifica o nome do membro do grupo. Quando nenhum nome é fornecido, o procedimento cria um nome padrão.
description Não Descrição do membro do grupo
sql_statement

O fornecimento de sql_statement ou schema_object_name é obrigatório

instrução SQL para o membro

Consulte Gerar um Hiperlink de Tabela com uma Instrução Select para obter detalhes.

schema_name Não

Nome de esquema para o membro. Forneça um valor schema_name somente quando a tabela/view fornecida no schema_object_name não estiver disponível no esquema atual

Consulte Gerar um Hiperlink de Tabela para uma Tabela ou uma View para obter detalhes.

schema_object_name

O fornecimento de sql_statement ou schema_object_name é obrigatório

Nome da Tabela/View do membro

Consulte Gerar um Hiperlink de Tabela para uma Tabela ou uma View para obter detalhes.

default_bind_variable Não Aplicável somente a sql_statements com variáveis de bind

Consulte Gerar um Hiperlink de Tabela com uma Instrução Select para obter detalhes.

column_lists Não Igual ao definido para a criação de um Hiperlink de Tabela que não seja de grupo

Consulte Gerar um Hiperlink de Tabela com Recursos de IU Especificados em Colunas para obter detalhes.

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.

Exemplos

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

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

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

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

Exemplos

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

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.

Observação

Este procedimento está obsoleto. Em vez dele, use o procedimento CREATE_URL.

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 de 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 usam esse valor no Contexto do Aplicativo para restringir as linhas visíveis ao 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 for fornecido ou quando expiration_minutes for fornecido como NULL, o valor será 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 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 é permitido agrupar por para as colunas especificadas (exibir os dados agrupando a coluna especificada é permitido).

O parâmetro column_lists é JSON que contém uma lista de arrays JSON de colunas que definem a funcionalidade de Hiperlink de 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 padrão:

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

  • Este procedimento está obsoleto. Em vez dele, use o procedimento CREATE_URL.

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

  • 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 vínculo deve ser passado. O exemplo a seguir usa o Hiperlink de Tabela gerado para acessar dados de árvore para o 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 vinculação 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 as 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 ou de um Grupo de 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 ou do Grupo de 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.

Nota de Uso

Com um Grupo de Hiperlinks de Tabela id, o procedimento estende todos os Hiperlinks de Tabela de membros, exceto os membros adicionados com DBMS_DATA_ACCESS.ADD_MEMBER. Os membros que foram adicionados ao Grupo de Hiperlinks de Tabela com DBMS_DATA_ACCESS.ADD_MEMBER mantêm seus valores independentes de invalidação de Hiperlink de Tabela e você pode estendê-los individualmente usando DBMS_DATA_ACCESS.EXTEND_URL.

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 ou um Grupo de 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 identificador do Hiperlink da Tabela ou do Grupo de Hiperlink da Tabela a ser invalidado.

kill_sessions

Esse parâmetro é opcional.

Por padrão, quando você executa DBMS_DATA_ACCESS.INVALIDATE_URL as sessões existentes que podem estar no meio do acesso aos dados usando um Hiperlink de Tabela ou um Grupo de Hiperlink de Tabela não são eliminadas. Quando esse parâmetro é definido como TRUE, esse valor especifica que essas sessões existentes devem ser eliminadas, para que a invalidação não deixe nenhum acesso contínuo a um conjunto de dados.

Valores válidos: TRUE | FALSE.

result

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

Nota de Uso

Quando o parâmetro DBMS_DATA_ACCESS.INVALIDATE_URL id é um Grupo de Hiperlinks de Tabela, o procedimento invalida o grupo e todos os membros do grupo, com exceção de todos os membros do grupo que foram adicionados com DBMS_DATA_ACCESS.ADD_MEMBER. Depois de executar DBMS_DATA_ACCESS.INVALIDATE_URL, os membros adicionados com DBMS_DATA_ACCESS.ADD_MEMBER mantêm seus valores de invalidação de Hiperlink de Tabela independentes e você pode invalidar esses Hiperlinks de Tabela individualmente usando DBMS_DATA_ACCESS.INVALIDATE_URL.

Exemplo

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

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,
"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.

LIST_MEMBERS Procedimento

Este procedimento lista os membros de um Grupo de Hiperlinks de Tabela.

Sintaxe

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

Parâmetros

Parâmetro Descrição

id

Especifica o identificador do Grupo de Hiperlinks da Tabela.

result

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

Exemplo

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

REMOVE_MEMBER Procedimento

Este procedimento remove um membro de um Grupo de Hiperlinks da Tabela.

Sintaxe

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

Parâmetros

Parâmetro Descrição

id

Especifica o identificador do Grupo de Hiperlinks da Tabela.
member_id

Especifica o identificador do membro do grupo a ser removido do Grupo de Hiperlinks da Tabela.

result

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

Observações de Uso

  • O valor member_id não pode ser um ID do Grupo de Hiperlinks da Tabela (is_group_url deve ser false).

  • Se o membro removido for um Hiperlink de Tabela existente que foi adicionado ao grupo usando DBMS_DATA_ACCESS.ADD_MEMBER, o membro será removido do grupo, mas o Hiperlink de Tabela poderá ser acessado diretamente até que seja explicitamente invalidado ou expire.

  • Se um Grupo de Hiperlink de Tabela contiver apenas um membro e esse membro for removido, o grupo será invalidado.

Exemplo

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