Consumir Compartilhamento

Sobre Perfis JSON

Os Perfis de Compartilhamento Delta ajudam você a se conectar a um provedor de compartilhamento e acessar um Servidor de Compartilhamento Delta. As informações do perfil são armazenadas em um arquivo zip que contém as credenciais do cliente no formato JSON. Para acessar os dados de compartilhamento, você deve registrar os objetos compartilhados usando um perfil JSON autorizado. Em seguida, você pode usar o perfil JSON para autenticação com um Delta Sharing Server e acessar os compartilhamentos de dados disponíveis.

Fazer Download de Perfis JSON

Quando a Ferramenta de Compartilhamento cria um objeto de compartilhamento, o destinatário recebe uma notificação por e-mail com um link para fazer download dos Perfis de Compartilhamento Delta. Você também pode fazer download dos perfis JSON na console do Database Actions:

1. Na página Fornecer Compartilhamento, clique nos três pontos ao lado de um destinatário e selecione Copiar Link de Ativação de Perfil para a Área de Transferência.

2. Abra o link em um navegador da Web para acessar a página Delta Profile Download.

3. Clique em Obter Informações do Perfil para fazer download de um arquivo zip contendo perfis JSON de Compartilhamento Delta.

Tipos de perfil JSON

A imagem ilustra os perfis JSON e mostra como consumir o Delta Share usando bearerToken e OIDC para Databricks.

Descrição da ilustração adp-databricks-delta-share-oidc.eps

O Delta Sharing suporta os seguintes perfis:

• Versão 1 do Perfil usando bearerToken

  Esse arquivo JSON pode incluir tokenEndpoint, clientID e clientSecret para que o token possa ser atualizado.

• Versão 2 do Perfil usando OIDC (somente PL/SQL) para Compartilhamento de Databricks

  Esse arquivo JSON contém credenciais do cliente OpenID Connect (OIDC) e OAuth, por exemplo, clientId, clientSecret e tokenEndpoint. Os perfis OIDC do Databricks usam shareCredentialsVersion 2 e type oauth_client_credentials, mas não suportam bearerToken. O Autonomous Database usa o tokenEndpoint para obter tokens de acesso com validade mais curta e os atualiza automaticamente.

  A versão 2 do perfil oferece melhor segurança porque não há tokens de portador de longa duração para distribuir, tem rotação mais fácil de segredos e fornece mais automação.

Ao se inscrever em um Provedor de Compartilhamento Delta no Compartilhamento de Consumo, você pode usar o arquivo JSON versão 1 ou versão 2 ou fazer upload do arquivo zip diretamente no campo Compartilhar JSON do Provedor.

{
        "shareCredentialsVersion": 1, 
        "endpoint": "https://myhost.us.example.com/ords/prov/_delta_sharing/", 
        "tokenEndpoint": "http://myhost.us.example.com:1234/ords/pdbdba/oauth/token", 
        "bearerToken": "-xxxxxxxxxxxxxxxxxxxxx", 
        "expirationTime": "20XX-01-13T07:53:11.073Z", 
        "clientID": "xxxxxxxxxxxxxxxxxxxxxx..", 
        "clientSecret": "xxxxxxxxxxxxxxxxxxxx.."
}

{
        "shareCredentialsVersion": 2, 
        "endpoint": "https://myhost.us.example.com/ords/prov/_delta_sharing/", 
        "tokenEndpoint": "http://myhost.us.example.com:1234/ords/pdbdba/oauth/token", 
        "type": "oauth_client_credentials",
        "clientId": "xxxxxxxxxxxxxxxxxxxxxx..", 
        "clientSecret": "xxxxxxxxxxxxxxxxxxxx..",
        "tokenScope": "xxxxxxxxxx"
}

Observe a diferença no caso de IDs de cliente em ambos os perfis. O Perfil 1 tem clientID e o Perfil 2 tem clientId.

Aprimoramentos de Segurança

Como destinatário de compartilhamento, você deve configurar uma lista de controle de acesso (ACL) para a máquina do provedor de compartilhamento usando o procedimento APPEND_HOST_ACE como usuário ADMIN ou outro usuário privilegiado. Isso permite que você acesse o compartilhamento via Internet.

Por exemplo, se você quiser permitir que um usuário do banco de dados, A_SHARE_USER, acesse os pontos finais em um host (Provedor de compartilhamento) chamado, aqui está uma amostra do procedimento PL/SQL que você precisará executar no editor de planilha SQL como administrador. Como pré-requisito, extraia o nome do host da propriedade do ponto final no perfil JSON de compartilhamento delta, conforme fornecido no exemplo acima. O nome do host do exemplo é myhost.us.example.com.

BEGIN 
        dbms_network_acl_admin.append_host_ace(    
        host =>'myhost.us.example.com', 
        lower_port=>443,    
        upper_port=>443,
        ace => xs$ace_type(      
        privilege_list => xs$name_list('http', 'http_proxy'),      
        principal_name =>'A_SHARE_USER',
        principal_type => xs_acl.ptype_db)); 
        COMMIT;
        END;        
/

A seguir estão os parâmetros com a respectiva descrição:

• host- Especifica o nome ou o endereço IP do host. O nome do host ou do domínio não faz distinção entre maiúsculas e minúsculas.
• porta inferior- Especifica a porta inferior de um intervalo de portas TCP opcional.
• porta superior- Especifica a porta superior de um intervalo de portas TCP opcional.
• ace – A Entrada de Controle de Acesso.
• lista de privilégios- Especifica a lista de privilégios de rede a serem concedidos ou negados.
• principal_name- É o principal (usuário ou atribuição do banco de dados) para o qual o privilégio é concedido ou negado. Faz distinção entre maiúsculas e minúsculas.
• principal_type- Especifica o tipo de principal que você usa.

Para obter mais detalhes sobre os subprogramas do pacote DBMS_NETWORK_ACL_ADMIN, consulte o documento PL/SQL Packages and Types Reference.

PRIV_ORDS_ACL             CONSTANT PLS_INTEGER := 8;

Fazer Upload de um Perfil JSON para Criar uma Assinatura do Provedor de Compartilhamento

Neste processo, você carregará o perfil JSON do provedor para configuração e credenciais para permitir o acesso aos destinatários.

1. Abra a página Compartilhamento de Consumo e clique em + Inscrever-se no Provedor de Compartilhamento para selecionar Inscrever-se no Provedor de Compartilhamento Delta no menu suspenso. Isso abre a janela Inscrever-se para Compartilhar Provedor.
   Descrição da ilustração subscriptione-share-provider-version-providersettings.png
2. Especifique o seguinte nas configurações do profissional de saúde:

   • Compartilhar Origem: Selecione JSON do Provedor de Compartilhamento Delta.

   • Compartilhar JSON do Provedor: Você pode compartilhar o perfil JSON usando as seguintes opções-

     Do Arquivo: Selecione essa opção e clique em Delta Share Profile JSON para procurar e fazer upload do perfil JSON no seu sistema. Como alternativa, você também pode fazer upload do arquivo zip que contém os Perfis JSON diretamente no campo Compartilhar JSON do Provedor.

     JSON: Selecione esta opção para colar o conteúdo de um arquivo JSON no espaço fornecido. Certifique-se de copiar todo o conteúdo, incluindo as chaves inicial e final.

   • Em Compartilhar Detalhes do Provedor, informe um Nome do Provedor e, opcionalmente, adicione uma Descrição.

   Clique em Próximo para avançar para a guia Adicionar Compartilhamentos.
3. Na guia Adicionar Compartilhamentos da caixa de diálogo, você verá a lista de compartilhamentos disponíveis. Clique no compartilhamento que você deseja consumir dos Compartilhamentos Disponíveis e selecione qualquer uma das opções disponíveis:
   Descrição da ilustração subscribe-share-provider-version-addshares.png
   • >: Esta opção permite mover o Compartilhamento Disponível para Compartilhamentos Selecionados.
   • <: Selecione esta opção para remover o compartilhamento selecionado dos Compartilhamentos Selecionados.
   • >>: Esta opção permite que você mova todos os compartilhamentos para os Compartilhamentos Selecionados.
   • <<: Selecione esta opção para remover todos os compartilhamentos selecionados dos Compartilhamentos Selecionados.

4. Clique em Inscrever-se para adicionar o compartilhamento. Um prompt de confirmação é exibido quando o provedor é criado com êxito. Após a criação bem-sucedida do provedor, você verá a tela Vincular Objeto do Cloud da página Carregamento de Dados.

5. Você pode exibir o nome do provedor no campo de local de armazenamento na nuvem. O compartilhamento aparece no local do arquivo de origem com os arquivos adicionados ao compartilhamento.
   Descrição da ilustração link-cloud-object.png

   Expanda o carrinho de pasta Compartilhar, arraste e solte o arquivo que você compartilha da origem para o carrinho de Link de Dados.

   Selecione Iniciar no carrinho de links de Dados para executar o job de link de dados.

6. Exiba as tabelas criadas no Database Actions.
   • Clique no Database Actions, na trilha de navegação estrutural, para voltar ao inicializador do Database Actions.
   • Clique no bloco SQL.
   • Selecione a tabela externa, arraste-a e solte-a na planilha.

     A instrução SQL Select da tabela é exibida. Esta instrução SQL pode ser executada para consumir os dados compartilhados.

     
     Descrição da ilustração xt_sql.png

ORA-29913: error while processing ODCIEXTTABLEFETCH routine

Os provedores do Databricks podem compartilhar tabelas Delta quando o Autonomous AI Database for um consumidor do Delta Sharing nos seguintes cenários:

• Cenário 1 - Elimine vetores de exclusão da tabela

• Cenário 2 - crie uma view e compartilhe-a

• Cenário 3 - Desativar vetores de exclusão nas configurações do espaço de trabalho para tabelas futuras

Cenário 1 - Elimine vetores de exclusão da tabela

Use essa opção se estiver pronto para interromper o uso de deletionVectors em uma tabela específica.

1. Execute isso no Databricks.

   ALTER TABLE table_name 
   DROP FEATURE deletionVectors

2. Adicione a tabela table_name ao compartilhamento Delta e configure o Autonomous AI Database como consumidor.

Essa opção aplica todas as exclusões pendentes e remove o recurso deletionVectors da tabela. A tabela se comporta como uma tabela Delta regular sem deletionVectors.

Cenário 2 - Criar uma View e Compartilhá-la

Use essa opção quando quiser manter deletionVectors na tabela base.

1. Execute isso no Databricks.

   CREATE VIEW view_name AS 
   SELECT * FROM table_name;

2. Adicione a exibição view_name ao compartilhamento Delta em vez da tabela.

   Os consumidores do Autonomous AI Database podem executar a consulta a seguir:

   SELECT * 
   FROM "MY_SHARE"."MY_SCHEMA"."view_name";

Neste cenário, a tabela base do Databricks continua usando os vetores de exclusão. O Databricks resolve os Vetores de Exclusão ao executar a view, para que o Autonomous AI Database não os veja. Para destinatários que não são do Databricks, como o Autonomous AI Database, o Databricks pode materializar a view e cobrar do provedor a computação e o armazenamento. O provedor pode configurar um TTL de materialização no Databricks para controlar o saldo entre o custo e a atualização de dados, um TTL mais curto ou mais baixo para novos dados ou um TTL mais longo ou mais alto para economia.

Cenário 3 - Desativar vetores de exclusão nas configurações do espaço de trabalho para tabelas futuras

Use esta opção para impedir que novas tabelas usem Vetores de Exclusão por padrão.

1. Abra Configurações do espaço de trabalho ou o console de administração como o usuário administrador do Databricks e vá para Avançado.

2. Localize Ativar Automaticamente Vetores de Exclusão e defina-o como Desativado.

3. Salve as alterações e reinicie a computação em execução.

ALTER TABLE table_name 
SET TBLPROPERTIES ('delta.enableDeletionVectors' = FALSE);

Nesse cenário, todas as novas tabelas criadas após essa alteração não terão Vetores de Exclusão ativados por padrão. No entanto, as tabelas existentes que já usam Vetores de Exclusão exigiriam os cenários explicados anteriormente.

Verificar se os Vetores de Exclusão estão Ativados em Databricks

Para verificar se os Vetores de Exclusão estão ativados para uma tabela específica no Databricks, execute este comando:

SHOW TBLPROPERTIES table_name ('delta.enableDeletionVectors');