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

Este artigo explica como criar e gerenciar destinatários em Delta Sharing, quando esses destinatários estiverem em um Databricks workspace que esteja habilitado para Unity Catalog.

Um destinatário é o objeto nomeado que representa a identidade de um usuário ou grupo de usuários no mundo real que consome dados compartilhados. A maneira como o senhor cria destinatários difere dependendo de o destinatário ter ou não acesso a um Databricks workspace que esteja habilitado para Unity Catalog:

• Para destinatários com acesso a um Databricks workspace que esteja habilitado para Unity Catalog, o senhor pode criar um objeto destinatário com uma conexão segura gerenciada inteiramente por Databricks. Esse modo de compartilhamento é chamado de Databricks-to-Databricks compartilhamento e está documentado neste artigo.
• Para destinatários sem acesso a um Databricks workspace que esteja habilitado para Unity Catalog, 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 para 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

To get the sharing identifier using Catalog Explorer:

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared with me tab, click your Databricks sharing organization name in the upper right, and select Copy sharing identifier.

SQL

Run the following command in a notebook or the Databricks SQL query editor:

SQL

SELECT CURRENT_METASTORE();

CLI

Run the following command using the Databricks CLI. The sharing identifier is returned as the global_metastore_id.

Bash

databricks metastores summary

O senhor pode ajudar o destinatário enviando ao seu contato 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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click New recipient.

4. Enter the Recipient name.

5. For Recipient type, select Databricks.

6. Enter the recipient's Sharing identifier.

   Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

7. (Optional) Enter a comment.

8. Click Create.

9. (Optional) Create custom Recipient properties.

   On the recipient Overview tab, click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

SQL

Run the following command in a notebook or the Databricks SQL query editor:

SQL

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

Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

You can also add custom properties for the recipient. For details, see Manage recipient properties.

CLI

Run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.
• <sharing-identifier>: The entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.
• <authentication-type>: Set to DATABRICKS when a sharing identifier string in the format <cloud>:<region>:<uuid> is provided for <sharing-identifier>.

Bash

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

You can also add custom properties for the recipient. For details, see Manage recipient properties.

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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients.

SQL

Run the following command in a notebook or the Databricks SQL query editor. Optionally, replace <pattern> with a LIKE predicate.

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Run the following command using the 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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

DESCRIBE RECIPIENT <recipient-name>;

CLI

Run the following command using the 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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. Go to the Shares tab to view the list of shares shared with the recipient.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Run the following command using the 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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. On the recipient details page:

   • Update the owner.

   • Edit or add a comment.

   • Rename the recipient.

     Click the kebab menu and select Rename.

   • Edit, remove, or add custom Recipient properties.

     Click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

   • Token-authenticated recipients only:

     • View and copy the Authentication link. See Get the activation link
     • Under Token Management, rotate or update the bearer token. See Manage recipient tokens.

   • OIDC federated recipients only:

     • Under OIDC federation policies, click Add policies. See LINK.
     • View and copy Recipient endpoint and Recipient MTLS endpoint.

SQL

Run one or more of the following commands in a notebook or the Databricks SQL query editor.

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> [, ...] )

For more information about properties, see Manage recipient properties.

CLI

Create a JSON file that includes an update to the recipient name, comment, owner, IP access list, or custom properties.

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"
  }
}

Then run the following command using the Databricks CLI. Replace <recipient-name> with the current recipient name and replace update-recipient-settings.json with the filename of the JSON file.

Bash

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

For more information about properties, see Manage recipient properties.

(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

When you create or update a recipient using Catalog Explorer, add or update custom properties by doing the following:

1. Go to the Recipient details page.

   If you are creating a new recipient, you land on this page after you click Create. If you are updating an existing recipient, go to this page by clicking the gear icon > Delta Sharing > Shared by me > Recipients and selecting the recipient.

2. Click Edit properties > +Add property.

3. Enter a property name (Key) and Value.

   For example, if you want to filter shared data by country and share only US data with this recipient, you can create a key named “country” with a value of “US.”

4. Click Save.

SQL

To add a custom property when you create a recipient, run the following command in a notebook or the Databricks SQL query editor:

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> can be a string literal or identifier. <property-value> must be a string literal.

For example:

SQL

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

To add, edit, or delete custom properties for an existing recipient, run one of the following:

SQL

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

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

CLI

To add custom properties when you create a recipient, run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.
• <property-key> can be a string literal or identifier.
• <property-value> must be a string literal.

Bash

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

For example:

Bash

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

To add or edit custom properties for an existing recipient, use update instead of 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. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. On the Recipients tab, find and select the recipient.

5. Click the kebab menu and select Delete.

6. On the confirmation dialog, click Delete.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

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

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients delete <recipient-name>