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

Esta página explica como criar e gerenciar destinatários em Delta Sharing, quando os destinatários estão em um Databricks workspace que está 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 forma como o senhor cria destinatários difere dependendo se o destinatário tem ou não acesso a um Databricks workspace que está habilitado para Unity Catalog:

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

  O senhor pode criar um objeto destinatário com uma conexão segura gerenciar por Databricks. Esse modo de compartilhamento é chamado de compartilhamento Databricks-to-Databricks e está documentado nesta página.

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

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

Para obter mais informações sobre esses dois modos de compartilhamento e quando escolher um deles, consulte Open compartilhamento versus Databricks-to-Databricks compartilhamento.

Requisitos

Para criar um destinatário:

• O senhor deve ser um administrador de metastore ou ter o privilégio CREATE_RECIPIENT para o metastore do Unity Catalog onde os dados que deseja compartilhar estão registrados.
• O senhor deve criar o destinatário usando um Databricks workspace que tenha o metastore Unity Catalog anexado.
• Se o senhor usar um notebook Databricks para criar o destinatário, seu compute deverá usar Databricks Runtime 11.3 LTS ou acima 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 view, excluir, atualizar e conceder acesso de destinatário a um compartilhamento), consulte os requisitos de permissões listados nas seções específicas de operações deste artigo.

Crie um objeto destinatário para os usuários que têm acesso a Databricks (Databricks-to-Databricks compartilhamento)

Se o destinatário dos dados tiver acesso a um Databricks workspace que tenha sido habilitado para Unity Catalog, o senhor poderá criar um objeto destinatário com um tipo de autenticação DATABRICKS.

Um objeto destinatário com o tipo de autenticação DATABRICKS representa um destinatário de dados em um determinado Unity Catalog metastore, identificado na definição do objeto destinatário por uma cadeia de identificadores de compartilhamento que consiste na nuvem, na região e no UUID do metastore. Os dados compartilhados com esse destinatário só podem ser acessados nessa metastore.

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

Peça a um usuário destinatário que lhe envie o identificador de compartilhamento do metastore Unity Catalog que está anexado ao espaço de trabalho em que o usuário destinatário ou o grupo de usuários trabalhará com os dados compartilhados.

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

Por exemplo, na captura de tela a seguir, a sequência completa de identificadores de compartilhamento é aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

O destinatário pode encontrar o identificador usando o Catalog Explorer, o Databricks Unity Catalog CLI, ou a função default SQL CURRENT_METASTORE em um Databricks Notebook ou Databricks SQL consultar essa execução em um Unity-Catalog compatível com compute no workspace que pretende usar.

Catalog Explorer

Para obter o identificador de compartilhamento usando o Catalog Explorer:

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. No Shared with me tab, clique no nome da sua organização de compartilhamento Databricks no canto superior direito e selecione Copy compartilhamento identifier (Copiar identificador de compartilhamento ).

SQL

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

SQL

SELECT CURRENT_METASTORE();

CLI

execute o seguinte comando usando o Databricks CLI. O identificador de compartilhamento é retornado como global_metastore_id.

Bash

databricks metastores summary

O senhor pode enviar ao seu destinatário as informações contidas nesta etapa ou pode indicá-lo para obter acesso no modelo Databricks-to-Databricks.

Etapa 2: criar o destinatário

Para criar um destinatário para Databricks-to-Databricks compartilhamento, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o CREATE RECIPIENT SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL.

Permissões necessárias : Administrador do metastore ou usuário com o privilégio CREATE_RECIPIENT para o metastore do Unity Catalog onde os dados que o senhor deseja compartilhar estão registrados.

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em New recipient (Novo destinatário ).

4. Insira o nome do destinatário .

5. Para Tipo de destinatário , selecione Databricks .

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

   Use as cadeias de identificadores de todo o 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) Crie propriedades personalizadas do destinatário .

   Na visão geral do destinatário tab, clique no ícone de edição ao lado de Recipient properties (Propriedades do destinatário ). Em seguida, adicione um nome de propriedade (chave ) e Value (valor ). Para obter detalhes, consulte gerenciar propriedades do destinatário.

SQL

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

SQL

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

Use as cadeias de identificadores de todo o 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 seguinte comando usando o Databricks CLI. Substitua os valores do espaço reservado:

• <recipient-name>: O nome do destinatário.
• <sharing-identifier>: As cadeias de identificadores de todo o compartilhamento 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 identificadores de compartilhamento no formato <cloud>:<region>:<uuid> for fornecida para <sharing-identifier>.

Bash

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 de DATABRICKS.

Conceder ao destinatário acesso a um compartilhamento

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

Para conceder acesso de compartilhamento aos destinatários, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando GRANT ON SHARE SQL em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

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

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

ver destinatários

Para view uma lista de destinatários, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando SHOW RECIPIENTS SQL em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em Recipients (Destinatários ).

SQL

Execute o seguinte comando em um Notebook ou no editor de consultas Databricks SQL. Opcionalmente, substitua <pattern> por um predicadoLIKE.

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

execute o seguinte comando usando o Databricks CLI.

Bash

databricks recipients list

ver detalhes do destinatário

Para view detalhes sobre um destinatário, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando DESCRIBE RECIPIENT SQL em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

Os detalhes incluem:

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

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em Recipients (Destinatários ) e selecione o destinatário.

SQL

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

SQL

DESCRIBE RECIPIENT <recipient-name>;

CLI

execute o seguinte comando usando o Databricks CLI.

Bash

databricks recipients get <recipient-name>

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

Para view a lista de compartilhamentos aos quais um destinatário recebeu acesso, o senhor pode usar o Catalog Explorer, o Databricks CLI, ou o comando SHOW GRANTS TO RECIPIENT SQL em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em Recipients (Destinatários ) e selecione o destinatário.

4. Acesse Shares (Ações ) tab para view a lista de ações compartilhadas com o destinatário.

SQL

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

SQL

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

execute o seguinte comando usando o Databricks CLI.

Bash

databricks recipients share-permissions <recipient-name>

Atualizar um destinatário

Para atualizar um destinatário, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando ALTER RECIPIENT SQL em um Databricks Notebook ou o editor de consultas 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ê precisa ser administrador da metastore ou proprietário do objeto destinatário para atualizar o proprietário. Você precisa ser administrador da metastore (ou usuário com o privilégio CREATE_RECIPIENT) e proprietário para atualizar o nome. Você deve ser o proprietário para atualizar o comentário ou as propriedades personalizadas.

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em Recipients (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 personalizadas do destinatário .

     Clique no ícone de edição ao lado das propriedades do destinatário . Em seguida, adicione um nome de propriedade (chave ) e Value (valor ). Para obter detalhes, consulte gerenciar propriedades do destinatário.

   • apenas para destinatários autenticados por tokens:

     • e copie o link Authentication (Autenticação ). Consulte Obter o link de ativação
     • Em Gerenciamento de tokens , gire ou atualize os tokens de portador. Consulte gerenciar destinatário tokens.

   • Somente destinatários federados do OIDC:

     • Em Políticas de federação do OIDC, clique em Adicionar políticas. Veja o LINK.
     • Visualizar e copiar o Recipient endpoint e o Recipient MTLS endpoint .

SQL

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

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ários.

CLI

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

JSON

{
  "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 o comando Databricks CLI. Substitua <recipient-name> pelo nome do destinatário atual e substitua update-recipient-settings.json pelo nome do arquivo JSON.

Bash

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

Para obter mais informações sobre propriedades, consulte gerenciar propriedades de destinatários.

(Opcional) Restrinja 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 do destinatário. Consulte Restringir o acesso do destinatário do Delta Sharing usando listas de acesso IP (compartilhamento aberto).

gerenciar propriedades de destinatários

Os objetos de destinatário incluem propriedades predefinidas que o senhor 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 e, ao mesmo tempo, mantenha os limites de dados entre eles.
• Compartilhe a visualização dinâmica que limita 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: O Databricks account ao qual um destinatário de dados pertence (somenteDatabricks-to-Databricks compartilhamento).
• databricks.metastoreId: O Unity Catalog metastore ao qual um destinatário de dados pertence (somenteDatabricks-to-Databricks compartilhamento).
• 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 personalizada 'country' = 'us' a um destinatário, poderá particionar os dados da tabela por país e compartilhar somente as linhas que tenham dados dos EUA com os destinatários que têm essa propriedade atribuída. O senhor também pode compartilhar um view dinâmico que restringe o acesso a linhas ou colunas com base nas propriedades do destinatário. Para obter exemplos mais detalhados, consulte Use recipient properties to do partition filtering e Add dynamic view to a share to filter rows and columns.

Requisitos

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

Adicione 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. O senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

Catalog Explorer

Ao criar ou atualizar um destinatário usando o Catalog Explorer, adicione ou atualize propriedades personalizadas fazendo o seguinte:

1. Acesse a página de detalhes do destinatário.

   Se você estiver criando um novo destinatário, acessa essa página depois de clicar em Criar . Se o senhor estiver atualizando um destinatário existente, acesse essa página clicando no ícone de engrenagem > Delta Sharing > Shared by me > Recipients e selecione o destinatário.

2. Clique em Editar propriedades > +Adicionar propriedade .

3. Digite um nome de propriedade (chave ) e Value (valor ).

   Por exemplo, se o senhor quiser filtrar os dados compartilhados por país e compartilhar somente dados dos EUA com esse destinatário, poderá criar um key chamado "country" com o valor "US".

4. Clique em Salvar .

SQL

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

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

Por exemplo:

SQL

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 ações:

SQL

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 seguinte comando usando o comando Databricks CLI. Substitua os valores do espaço reservado:

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

Bash

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

Por exemplo:

Bash

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:

Bash

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

visualizar propriedades do destinatário

Para view propriedades do destinatário, siga as instruções em view recipient details (ver detalhes do destinatário).

Excluir um destinatário

Para excluir um destinatário, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando DROP RECIPIENT SQL em um Databricks Notebook ou o editor de consultas Databricks SQL. Você deve ser o proprietário do objeto do destinatário para excluí-lo.

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.

Catalog Explorer

1. Em seu site Databricks workspace, clique em Catalog .

2. Na parte superior do painel Catálogo , clique no ícone de engrenagem e selecione Delta Sharing .

   Como alternativa, na página de acesso rápido , clique no botão Delta Sharing > .

3. Em Shared by me (Compartilhado por mim ) tab, clique em Recipients (Destinatários ) e selecione o destinatário.

4. Em Recipients (Destinatários ) tab, 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 seguinte comando em um notebook ou no editor de consultas SQL do Databricks.

SQL

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

CLI

execute o seguinte comando usando o Databricks CLI.

Bash

databricks recipients delete <recipient-name>