Criar e gerenciar destinatários de dados para o Compartilhamento Delta (compartilhamento do Databricks para o Databricks)

Esta página explica como criar e gerenciar destinatários no Delta Sharing, quando os destinatários estão em um workspace do Databricks habilitado para Unity Catalog.

Um destinatário é o objeto nomeado que representa a identidade de um usuário ou grupo de usuários que consomem dados compartilhados. A maneira como você cria destinatários difere dependendo se o destinatário tem ou não acesso a um workspace do Databricks habilitado para o Catálogo do Unity:

• Destinatários com acesso a um workspace do Databricks habilitado para Catálogo do Unity:

  Você pode criar um objeto de destinatário com uma conexão segura gerenciada pelo Databricks. Esse modo de compartilhamento é chamado de compartilhamento de Databricks para Databricks e está documentado nessa página.

• Destinatários sem acesso a um workspace do Databricks habilitado para Catálogo do Unity:

  Você deve usar o compartilhamento aberto, com uma conexão segura gerenciada usando a autenticação baseada em token (tokens de portador ou federação OAuth). Para obter informações sobre como criar destinatários de compartilhamento aberto, consulte Usar a federação Open ID Connect (OIDC) para habilitar a autenticação para compartilhamentos Delta Sharing (compartilhamento aberto) e Criar um objeto de destinatário para usuários não Databricks usando tokens de portador (compartilhamento aberto).

Para obter mais informações sobre esses dois modos de compartilhamento e quando escolher cada um, confira Compartilhamento aberto versus Compartilhamento de Databricks para Databricks.

Requisitos

Para criar um destinatário:

• É necessário ser um administrador de metastore ou ter o privilégio CREATE RECIPIENT para o metastore do Catálogo do Unity em que os dados que você deseja compartilhar estão registrados.
• Você deve criar o destinatário usando um workspace do Azure Databricks que tenha esse metastore do Catálogo do Unity anexado.
• Se você usar um bloco de anotações do Databricks para criar o destinatário, seu ambiente deve usar o Databricks Runtime 11.3 LTS ou superior e o modo de acesso padrão ou dedicado (anteriormente chamados de modos de acesso compartilhado e de usuário único).

Para outras operações de gerenciamento de destinatários (como exibir, excluir, atualizar e conceder acesso de destinatário a um compartilhamento), consulte os requisitos de permissões listados nas seções específicas da operação deste artigo.

Criar um objeto destinatário para usuários que têm acesso ao Databricks (compartilhamento de Databricks para Databricks)

Se o destinatário de dados tiver acesso a um workspace do Databricks que foi habilitado para o Unity Catalog, você poderá criar um objeto destinatário com um tipo de autenticação de DATABRICKS.

Um objeto de destinatário com o tipo de autenticação de DATABRICKS representa um destinatário de dados em um metastore específico do Catálogo do Unity, identificado na definição do objeto de destinatário por uma cadeia de caracteres de identificador de compartilhamento que consiste na nuvem, região e UUID do metastore. Os dados compartilhados com esse destinatário só poderão ser acessados nesse metastore.

Etapa 1: Solicitar o identificador de compartilhamento do destinatário

Peça a um usuário destinatário para enviar a você o identificador de compartilhamento do metastore do Catálogo do Unity que está anexado aos workspaces nos quais o usuário ou grupo de usuários destinatários trabalhará com os dados compartilhados.

O identificador de compartilhamento é uma cadeia de caracteres que consiste na nuvem, região e UUID do metastore (o identificador exclusivo do metastore), no formato <cloud>:<region>:<uuid>.

Por exemplo, na captura de tela a seguir, a cadeia de caracteres do identificador de compartilhamento completa é aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

O destinatário pode encontrar o identificador usando o Explorador de Catálogos, a CLI do Catálogo do Databricks Unity ou a função SQL padrão CURRENT_METASTORE em um notebook do Databricks ou uma consulta SQL do Databricks que é executada em uma computação capaz de utilizar o Unity-Catalog no workspace que pretende usar.

Explorador do Catálogo

Para obter o identificador de compartilhamento usando o Gerenciador de Catálogos:

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado comigo, clique no nome da organização de compartilhamento do Databricks no canto superior direito e selecione Copiar identificador de compartilhamento.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

SELECT CURRENT_METASTORE();

CLI

Execute o comando a seguir usando a CLI do Databricks. O identificador de compartilhamento é retornado como o global_metastore_id.

databricks metastores summary

Você pode enviar ao destinatário as informações contidas nesta etapa ou orientá-lo para Obter acesso no modelo Databricks-to-Databricks.

Etapa 2: Criar o destinatário

Para criar um destinatário para o compartilhamento de Databricks para Databricks, você pode usar o Explorador de Catálogo, a CLI do Catálogo do Unity do Databricks ou o comando CREATE RECIPIENT SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE RECIPIENT para o metastore do Catálogo do Unity no qual os dados que você deseja compartilhar estão registrados.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Novo destinatário.

4. Insira o nome do destinatário.

5. Para o tipo destinatário, selecione Databricks.

6. Insira o identificador de compartilhamento do destinatário.

   Use toda a cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

7. (Opcional) Insira um comentário.

8. Clique em Criar.

9. (Opcional) Criar propriedades do Destinatário personalizadas.

   Na guia Visão geral do destinatário, clique no ao lado das propriedades do destinatário. Em seguida, adicione um nome de propriedade (Chave) e Valor. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
USING ID '<sharing-identifier>'
[COMMENT "<comment>"];

Use toda a cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

Você também pode adicionar propriedades personalizadas para o destinatário. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

CLI

Execute o comando a seguir usando a CLI do Databricks. Substitua os valores do espaço reservado:

• <recipient-name>: o nome do destinatário.
• <sharing-identifier>: Use toda a cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.
• <authentication-type>: defina para DATABRICKS quando uma cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid> for fornecida para <sharing-identifier>.

databricks recipients create <recipient-name> <authentication-type> --sharing-code <sharing-identifier>

Você também pode adicionar propriedades personalizadas para o destinatário. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

O destinatário é criado com o authentication_type do DATABRICKS.

Conceder ao destinatário acesso a um compartilhamento

Depois de criar o destinatário e criar compartilhamentos, você poderá conceder ao destinatário acesso a esses compartilhamentos.

Para conceder acesso de compartilhamento aos destinatários, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando GRANT ON SHARE SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: uma das seguintes:

• Administrador de metastore.
• Permissões delegadas ou de propriedade no compartilhamento e nos objetos destinatários ((USE SHARE + SET SHARE PERMISSION) ou proprietário do compartilhamento) E (USE RECIPIENT ou proprietário do destinatário).

Para obter instruções, veja Gerenciar o acesso aos compartilhamentos de dados do Delta Sharing (para provedores).

Exibir destinatários

Para exibir uma lista de destinatários, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando SHOW RECIPIENTS SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Você deve ser um administrador de metastore ou ter o privilégio USE RECIPIENT para exibir todos os destinatários no metastore. Outros usuários têm acesso somente aos destinatários que possuem.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks. Opcionalmente, substitua <pattern> por um predicado LIKE.

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients list

Exibir detalhes do destinatário

Para exibir detalhes sobre um destinatário, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando DESCRIBE RECIPIENT SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do metastore, usuário com o privilégio USE RECIPIENT ou o proprietário do objeto do destinatário.

Os detalhes incluem:

• O criador do destinatário, o carimbo de data/hora de criação, os comentários e o tipo de autenticação (TOKEN ou DATABRICKS).
• Se o destinatário usar o compartilhamento aberto: o tempo de vida do token, o link de ativação, o status de ativação (se a credencial foi baixada) e as listas de acesso de IP, se atribuídas.
• Se o destinatário usar o compartilhamento do Databricks para o Databricks: a nuvem, a região e o ID de metastore do metastore do Catálogo do Unity do destinatário, bem como o status de ativação.
• Propriedades do destinatário, incluindo propriedades personalizadas. Consulte Gerenciar propriedades do destinatário.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DESCRIBE RECIPIENT <recipient-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients get <recipient-name>

Exibir as permissões de compartilhamento de um destinatário

Para exibir a lista de compartilhamentos aos quais um destinatário recebeu acesso, use o Explorador de catálogos, a CLI do Databricks ou o comando SHOW GRANTS TO RECIPIENT SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do metastore, usuário com o privilégio USE RECIPIENT ou o proprietário do objeto do destinatário.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Acesse a guia Compartilhamentos para exibir a lista de compartilhamentos compartilhados com o destinatário.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients share-permissions <recipient-name>

Atualizar um destinatário

Para atualizar um destinatário, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando SQL ALTER RECIPIENT em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

As propriedades que você pode atualizar incluem nome do destinatário, proprietário, comentário e propriedades personalizadas.

Permissões necessárias: você deve ser um administrador de metastore ou um proprietário do objeto do destinatário para atualizar o proprietário. É necessário ser um administrador de metastore (ou um usuário com o privilégio CREATE RECIPIENT) e o proprietário para atualizar o nome. Você deve ser o proprietário para atualizar o comentário ou as propriedades personalizadas.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Na página de detalhes do destinatário:

   • Atualize o proprietário.

   • Edite ou adicione um comentário.

   • Renomeie o destinatário.

     Clique no Menu kebab e selecione Renomear.

   • Edite, remova ou adicione propriedades de Destinatário personalizadas.

     Clique no ícone ao lado das propriedades do destinatário. Em seguida, adicione um nome de propriedade (Chave) e Valor. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

   • Somente destinatários autenticados por token:

     • Exibir e copiar o link de Autenticação. Consulte Obter o link de ativação
     • Em Gerenciamento de Tokens, gire ou atualize o token de portador. Consulte Gerenciar os tokens de destinatário.

   • Somente destinatários federados do OIDC:

     • Em políticas de federação OIDC, clique em Adicionar políticas. Consulte LINK.
     • Exibir e copiar o ponto de extremidade do destinatário e o ponto de extremidade MTLS do destinatário.

SQL

Execute um ou mais dos seguintes comandos em um notebook ou no editor de consultas SQL do Databricks.

ALTER RECIPIENT <recipient-name> RENAME TO <new-recipient-name>;

ALTER RECIPIENT <recipient-name> OWNER TO <new-owner>;

COMMENT ON RECIPIENT <recipient-name> IS "<new-comment>";

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( <property-key>  =  property_value [, ...] )

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( <property-key> [, ...] )

Para obter mais informações sobre propriedades, consulte Gerenciar propriedades do destinatário.

CLI

Crie um arquivo JSON que inclua uma atualização para o nome do destinatário, comentário, proprietário, lista de acesso IP ou propriedades personalizadas.

{
  "name": "new-recipient-name",
  "owner": "someone-else@example.com",
  "comment": "something new",
  "ip_access_list": {
    "allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
  },
  "property": {
    "country": "us",
    "id": "001"
  }
}

Em seguida, execute o comando a seguir usando a CLI do Databricks. Substitua <recipient-name> pelo nome do destinatário atual e substitua update-recipient-settings.json pelo nome do arquivo JSON.

databricks recipients update --json-file update-recipient-settings.json

Para obter mais informações sobre propriedades, consulte Gerenciar propriedades do destinatário.

(Opcional) Restringir o acesso do destinatário usando listas de acesso

Você pode limitar o acesso do destinatário a um conjunto restrito de endereços IP ao configurar o objeto de destinatário. Confira Restringir o acesso do destinatário do Delta Sharing usando listas de acesso IP (compartilhamento aberto).

Gerenciar propriedades do destinatário

Os objetos de destinatário incluem propriedades predefinidas que você pode usar para refinar o acesso ao compartilhamento de dados. Por exemplo, você pode usá-los para fazer o seguinte:

• Compartilhe diferentes partições de tabela com diferentes destinatários, permitindo que você use os mesmos compartilhamentos com vários destinatários, mantendo os limites de dados entre eles.
• Compartilhe exibições dinâmicas que limitam o acesso do destinatário aos dados da tabela no nível da linha ou da coluna com base nas propriedades do destinatário.

Você também pode criar propriedades personalizadas.

As propriedades predefinidas começam com databricks. e incluem o seguinte:

• databricks.accountId: A conta do Azure Databricks à qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
• databricks.metastoreId: O metastore do Catálogo do Unity ao qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
• databricks.name: O nome do destinatário dos dados.

As propriedades personalizadas que podem ser de valor podem incluir, por exemplo, country. Por exemplo, se você anexar a propriedade 'country' = 'us' personalizada a um destinatário, poderá particionar dados de tabela por país e compartilhar apenas linhas que tenham dados dos EUA com os destinatários que têm essa propriedade atribuída. Você também pode compartilhar uma exibição dinâmica que restringe o acesso a linhas ou colunas com base nas propriedades do destinatário. Para obter exemplos mais detalhados, confira Usar propriedades de destinatário para filtrar partições e Adicionar exibições dinâmicas a um compartilhamento para filtrar linhas e colunas.

Requisitos

As propriedades do destinatário têm suporte no Databricks Runtime 12.2 e superior.

Adicionar propriedades ao criar ou atualizar um destinatário

Você pode adicionar propriedades ao criar um destinatário ou atualizá-las para um destinatário existente. Você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE RECIPIENT para o metastore do Unity Catalog.

Explorador do Catálogo

Ao criar ou atualizar um destinatário usando o Gerenciador de Catálogos, adicione ou atualize propriedades personalizadas fazendo o seguinte:

1. Vá para a página Detalhes do destinatário.

   Se você estiver criando um novo destinatário, você entrará nesta página depois de clicar em Criar. Se você estiver atualizando um destinatário existente, vá para esta página clicando no ícone de engrenagem > Compartilhamento Delta > Compartilhado por mim > Destinatários e selecionando o destinatário.

2. Clique em Editar propriedades > +Adicionar propriedade.

3. Insira um nome de propriedade (Chave) e Valor.

   Por exemplo, se você quiser filtrar dados compartilhados por país e compartilhar apenas dados dos EUA com esse destinatário, poderá criar uma chave chamada "país" com um valor de "EUA".

4. Clique em Save (Salvar).

SQL

Para adicionar uma propriedade personalizada ao criar um destinatário, execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks:

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[USING ID '<sharing-identifier>'] /* Skip this if you are using open sharing */
[COMMENT "<comment>"]
PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

<property-key> pode ser um literal ou identificador de cadeia de caracteres. <property-value> precisa ser um literal de cadeia de caracteres.

Por exemplo:

CREATE RECIPIENT acme PROPERTIES ('country' = 'us', 'partner_id' = '001');

Para adicionar, editar ou excluir propriedades personalizadas para um destinatário existente, execute um dos seguintes procedimentos:

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( '<property-key>' );

CLI

Para adicionar propriedades personalizadas ao criar um destinatário, execute o comando a seguir usando a CLI do Databricks. Substitua os valores do espaço reservado:

• <recipient-name>: o nome do destinatário.
• <property-key> pode ser um literal ou identificador de cadeia de caracteres.
• <property-value> precisa ser um literal de cadeia de caracteres.

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "<property-key>": "<property-value>",
    }
  }
}'

Por exemplo:

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "partner_id":"001"
    }
  }
}'

Para adicionar ou editar propriedades personalizadas para um destinatário existente, use update em vez de create:

databricks recipients update \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "partner_id":"001"
    }
  }
}'

Exibir propriedades do destinatário

Para exibir as propriedades do destinatário, siga as instruções em Exibir detalhes do destinatário.

Excluir um destinatário

Para excluir um destinatário, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando SQL DROP RECIPIENT em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks. Você deve ser o proprietário do objeto destinatário para excluir o destinatário.

Quando você exclui um destinatário, os usuários representados pelo destinatário não podem mais acessar os dados compartilhados. Os tokens que os destinatários usam em um cenário de compartilhamento aberto são invalidados.

Permissões necessárias: proprietário do objeto destinatário.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Na guia Compartilhamentos, localize e selecione o destinatário.

5. Clique no Menu kebab e selecione Excluir.

6. Na caixa de diálogo de confirmação, clique em Excluir.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DROP RECIPIENT [IF EXISTS] <recipient-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients delete <recipient-name>