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

2025-04-16

Esta página explica como criar e gerenciar destinatários no Compartilhamento Delta, quando os destinatários estão em um espaço de trabalho Databricks habilitado para o Catálogo Unity.

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 espaço de trabalho Databricks habilitado para o Unity Catalog:

Destinatários com acesso a um espaço de trabalho do Databricks com Catálogo Unity ativado.

Você pode criar um objeto de destinatário com uma conexão segura gerenciada pelo Databricks. Esse modo de compartilhamento é chamado de compartilhamento Databricks-to-Databricks e está documentado nesta página.
Destinatários sem acesso a um espaço de trabalho Databricks habilitado para Unity Catalog:

Você deve usar o compartilhamento aberto, com uma conexão segura que você gerencia usando 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 OIDC (Open ID Connect) para habilitar a autenticação para compartilhamentos Delta Sharing (compartilhamento aberto) e Criar um objeto de destinatário para usuários que não são do Databricks usando tokens de portador (compartilhamento aberto).

Para obter mais informações sobre esses dois modos de partilha e quando escolher cada um, consulte Comparação entre partilha aberta e partilha de Databricks para Databricks.

Requisitos

Para criar um destinatário:

Você deve ser um administrador de metastore ou ter o CREATE RECIPIENT privilégio para o metastore do Unity Catalog onde os dados que você deseja compartilhar estão registrados.
Você deve criar o destinatário usando um espaço de trabalho do Azure Databricks que tenha esse metastore do Catálogo Unity anexado.
Se você usar um bloco de anotações Databricks para criar o destinatário, sua computação deverá usar o Databricks Runtime 11.3 LTS ou superior e o modo de acesso padrão ou dedicado (anteriormente 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.

Se o destinatário dos dados tiver acesso a um espaço de trabalho Databricks habilitado para o Unity Catalog, você poderá criar um objeto de 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 num metastore específico do Unity Catalog, identificado na definição do objeto de destinatário por uma cadeia de caracteres de identificação de partilha, que consiste na nuvem, região, e UUID do metastore. Os dados compartilhados com esse destinatário podem ser acessados somente nesse metastore.

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

Peça a um usuário destinatário para enviar o identificador de compartilhamento para o metastore do Unity Catalog anexado aos espaços de trabalho onde o usuário destinatário ou grupo de usuários trabalhará com os dados compartilhados.

O identificador de compartilhamento é uma cadeia de caracteres que consiste na nuvem, região e UUID (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 completo é aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

O destinatário pode encontrar o identificador usando o Catalog Explorer, a CLI do Databricks Unity Catalog ou a função SQL padrão CURRENT_METASTORE em um bloco de anotações Databricks ou consulta SQL Databricks que é executada em um computador compatível com Unity Catalog no espaço de trabalho que pretende usar.

Explorador de Catálogos

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

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
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 bloco de anotações ou no editor de consultas Databricks SQL:

SELECT CURRENT_METASTORE();

Interface de Linha de Comando (CLI)

Execute o seguinte comando 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 apontá-lo para Obter acesso no modelo Databricks-to-Databricks.

Etapa 2: Criar o destinatário

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

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

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Compartilhado por mim, clique em Novo destinatário.
Introduza o Nome do destinatário.
Para tipo de destinatário, selecione Databricks.
Introduza o identificador de partilha de 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.
(Opcional) Insira um comentário.
Clique em Criar.
(Opcional) Crie propriedades personalizadas de Destinatário.

Na guia Visão Geral do Destinatário, clique no ícone ícone de edição ao lado de Propriedades do Destinatário. Em seguida, adicione um nome de propriedade (Key) e Value. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas 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.

Interface de Linha de Comando (CLI)

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

<recipient-name>: O nome do destinatário.
<sharing-identifier>: A cadeia de caracteres do identificador de compartilhamento inteira no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.
<authentication-type>: Defina como DATABRICKS quando uma cadeia de caracteres de identificador de compartilhamento no formato <cloud>:<region>:<uuid> é 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 usando o authentication_type de DATABRICKS.

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

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

Permissões necessárias: uma das seguintes opções:

Administrador da Metastore.
Permissões delegadas ou propriedade tanto nos objetos da partilha quanto nos objetos do destinatário ((USE SHARE + SET SHARE PERMISSION) ou proprietário da partilha) E (USE RECIPIENT ou proprietário do destinatário).

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

Ver destinatários

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

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

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Partilhado por mim, clique em Destinatários.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL. Opcionalmente, substitua <pattern> por um LIKE predicado.

SHOW RECIPIENTS [LIKE <pattern>];

Interface de Linha de Comando (CLI)

Execute o seguinte comando usando a CLI do Databricks.

databricks recipients list

Ver detalhes do destinatário

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

Permissões necessárias: administrador do Metastore, usuário com o USE RECIPIENT privilégio ou proprietário do objeto 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 da ativação (se a credencial foi baixada) e as listas de acesso IP, se atribuídas.
Se o destinatário utilizar o compartilhamento entre Databricks: a nuvem, a região e o ID do metastore do Unity Catalog do destinatário, assim como o status de ativação.
Propriedades do destinatário, incluindo propriedades personalizadas. Consulte Gerenciar propriedades do destinatário.

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

DESCRIBE RECIPIENT <recipient-name>;

Interface de Linha de Comando (CLI)

Execute o seguinte comando 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, você pode usar o Gerenciador de Catálogos, a CLI do Databricks ou o SHOW GRANTS TO RECIPIENT comando SQL em um bloco de anotações do Azure Databricks ou no editor de consultas do Databricks SQL.

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

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.
Aceda ao separador Partilhas para ver a lista de partilhas partilhadas com o destinatário.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

SHOW GRANTS TO RECIPIENT <recipient-name>;

Interface de Linha de Comando (CLI)

Execute o seguinte comando 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 Unity do Databricks ou o ALTER RECIPIENT comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas do Databricks SQL.

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 proprietário do objeto de destinatário para atualizar o proprietário. Você deve ser um administrador de metastore (ou utilizador com 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 de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.
Na página de detalhes do destinatário:
- Atualize o proprietário.
- Edite ou adicione um comentário.
- Renomeie o destinatário.
  
  Clique no e selecione Renomear.
- Edite, remova ou adicione propriedades personalizadas de Destinatário.
  
  Clique no ao lado de Propriedades do destinatário. Em seguida, adicione um nome de propriedade (Key) e Value. Para obter detalhes, consulte Gerenciar propriedades do destinatário.
- Somente destinatários autenticados por token:
  - Exiba e copie o link de Autenticação . Consulte Obter o link de ativação
  - Em Gerenciamento de Tokens, substitua ou atualize o token de acesso. Consulte Gerenciar tokens de destinatário.
- Somente destinatários federados do OIDC:
  - Em políticas de federação OIDC , clique em Adicionar políticas. Ver LINK.
  - Visualize e copie o endpoint de destinatário e o endpoint MTLS de destinatário .

SQL

Execute um ou mais dos seguintes comandos em um bloco de anotações ou no editor de consultas Databricks SQL.

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 de destinatário.

Interface de Linha de Comando (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 seguinte comando 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 de destinatário.

(Opcional) Restringir o acesso de destinatários usando listas de acesso

Você pode limitar o acesso do destinatário a um conjunto restrito de endereços IP ao configurar o objeto do destinatário. Consulte Restringir o acesso de destinatários do Compartilhamento Delta 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 partições de tabela diferentes com destinatários diferentes, permitindo que você use os mesmos compartilhamentos com vários destinatários enquanto mantém os limites de dados entre eles.
Partilhe vistas dinâmicas que limitam o acesso do destinatário aos dados da tabela ao nível da linha ou 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 pertence um destinatário de dados (somente compartilhamento de Databricks para Databricks).
databricks.metastoreId: O metastore do Unity Catalog ao qual um destinatário de dados pertence (somente compartilhamento de Databricks para Databricks).
databricks.name: O nome do destinatário dos dados.

As propriedades personalizadas que podem ser valiosas podem incluir, por exemplo, country. Por exemplo, se você anexar a propriedade 'country' = 'us' personalizada a um destinatário, poderá particionar dados da 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 um modo de exibição dinâmico que restringe o acesso a linhas ou colunas com base nas propriedades do destinatário. Para obter exemplos mais detalhados, consulte Usar propriedades de destinatário para fazer filtragem de partições e Adicionar exibições dinâmicas a um compartilhamento para filtrar linhas e colunas.

Requisitos

As propriedades do destinatário são suportadas no Databricks Runtime 12.2 e posterior.

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 Databricks Unity ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.

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

Explorador de Catálogos

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

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

Se estiver a criar um novo destinatário, aceda a esta 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.
Clique em Editar propriedades > +Adicionar propriedade.
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".
Clique em Guardar.

SQL

Para adicionar uma propriedade personalizada ao criar um destinatário, execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL:

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 de string ou um identificador. <property-value> deve ser uma cadeia de caracteres literal.

Por exemplo:

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

Para adicionar, editar ou excluir propriedades personalizadas de um destinatário existente, execute uma das seguintes opções:

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

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

Interface de Linha de Comando (CLI)

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

<recipient-name>: O nome do destinatário.
<property-key> pode ser um literal de string ou um identificador.
<property-value> deve ser uma cadeia de caracteres literal.

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 Unity do Databricks ou o DROP RECIPIENT comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas do Databricks SQL. 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 do destinatário.

Explorador de Catálogos

No seu espaço de trabalho do Azure Databricks, clique no Catálogo.
Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Compartilhamento Delta.

Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .
Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.
Na guia Destinatários, localize e selecione o destinatário.
Clique no menu kebab e selecione Excluir.
Na caixa de diálogo de confirmação, clique em Excluir.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

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

Interface de Linha de Comando (CLI)

Execute o seguinte comando usando a CLI do Databricks.

databricks recipients delete <recipient-name>

Partilhar via

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

Requisitos

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

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

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Etapa 2: Criar o destinatário

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Conceder ao destinatário acesso a um compartilhamento

Ver destinatários

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Ver detalhes do destinatário

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

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

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Atualizar um destinatário

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

(Opcional) Restringir o acesso de destinatários usando listas de acesso

Gerenciar propriedades do destinatário

Requisitos

Adicionar propriedades ao criar ou atualizar um destinatário

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Exibir propriedades do destinatário

Excluir um destinatário

Explorador de Catálogos

SQL

Interface de Linha de Comando (CLI)

Comentários

Recursos adicionais