Pular para o conteúdo principal

Criar e gerenciar destinatários de dados para o Delta Sharing

Este artigo explica como criar e gerenciar destinatários para Delta Sharing.

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 .
  • Para destinatários sem acesso a um workspace Databricks habilitado para Unity Catalog, você deve usar compartilhamento aberto , com uma conexão segura que você gerencia usando autenticação baseada em tokens .

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.

exemplo de CURRENT\ _METASTORE

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.

To get the sharing identifier using Catalog Explorer:

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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.

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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 and 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.

  5. (Optional) Enter a comment.

  6. Click Create.

  7. (Optional) Create custom Recipient properties.

    Click Edit properties > +Add property. Then add a property name (Key) and Value. For details, see Manage recipient properties.

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

Crie um objeto destinatário para todos os outros usuários (compartilhamento aberto)​

Se quiser compartilhar dados com usuários fora do seu Databricks workspace, independentemente de eles usarem o Databricks, o senhor pode usar o open Delta Sharing para compartilhar seus dados com segurança. Veja como funciona:

  1. Como provedor de dados, o senhor cria o objeto destinatário no metastore do Unity Catalog.
  2. Quando o objeto destinatário é criado, o site Databricks gera tokens, um arquivo de credenciais que inclui os tokens e um link de ativação para ser compartilhado com o destinatário. O objeto destinatário tem o tipo de autenticação TOKEN.
  3. O destinatário acessa o link de ativação, downloads o arquivo de credencial e usa o arquivo de credencial para se autenticar e obter acesso de leitura às tabelas que o senhor inclui nos compartilhamentos aos quais dá acesso.

Etapa 1: criar o destinatário​

Para criar um destinatário para compartilhamento aberto, 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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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. (Optional) Enter a comment.

  6. Click Create.

    You do not use the sharing identifier for open sharing recipients.

  7. Copy the activation link.

    Alternatively, you can get the activation link later. See Step 2: Get the activation link.

  8. (Optional) Create custom Recipient properties.

    On the recipient Details tab, click Edit properties > +Add property. Then add a property name (Key) and Value. For details, see Manage recipient properties.

O destinatário é criado com o authentication_type de TOKEN.

nota

Ao criar o destinatário, você tem a opção de limitar o acesso do destinatário a um conjunto restrito de endereços IP. Você também pode adicionar uma lista de acesso IP a um destinatário existente. Consulte Restringir o acesso do destinatário do Delta Sharing usando listas de acesso IP (compartilhamento aberto).

Para obter o link de ativação do novo destinatário, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o DESCRIBE RECIPIENT SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL.

Se o destinatário já tiver feito o download do arquivo de credencial, o link de ativação não será retornado ou exibido.

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

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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, copy the Activation link.

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).

Enviar ao destinatário suas informações de conexão​

O senhor deve informar ao destinatário como acessar os dados que está compartilhando com ele. As informações que o senhor compartilha com o destinatário dependem de estar usando o Databricks-to-Databricks compartilhamento ou o compartilhamento aberto:

  • Para o Databricks-to-Databricks compartilhamento , o senhor envia um link com instruções para acessar os dados que está compartilhando.

    Um objeto de provedor que lista os compartilhamentos disponíveis é criado automaticamente na metastore do destinatário. Os destinatários não precisam fazer nada além de view e selecionar os compartilhamentos que desejam usar. Consulte Ler dados compartilhados usando Databricks-to-Databricks Delta Sharing (para destinatários).

  • Para o compartilhamento aberto , o senhor usa um canal seguro para compartilhar o link de ativação e um link para instruções de uso.

    O senhor pode fazer o download do arquivo de credenciais apenas uma vez. Os destinatários devem tratar a credencial de downloads como um segredo e não devem compartilhá-la fora de sua organização. Se você tiver dúvidas de que uma credencial pode ter sido tratada de forma insegura, você pode alternar a credencial de um destinatário a qualquer momento. Para obter mais informações sobre o gerenciamento de credenciais para garantir o acesso seguro do destinatário, consulte Considerações de segurança para tokens.

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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.

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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.

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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.

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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 kebab menu and select Rename.

    • Edit, remove, or add custom Recipient properties.

      Click Edit properties. To add a property, click +Add property and enter a property name (Key) and Value. For details, see Manage recipient properties.

Gerenciar destinatário tokens (compartilhamento aberto)​

Se o senhor estiver compartilhando dados com um destinatário usando o compartilhamento aberto, talvez seja necessário girar os tokens desse destinatário. A rotação de tokens consiste em definir a expiração de um token existente e substituí-lo por um novo token e URL de ativação.

O senhor deve alternar os tokens de um destinatário e gerar um novo URL de ativação nas seguintes circunstâncias:

  • Quando os tokens de destinatário existentes estão prestes a expirar.
  • Se um destinatário perder o URL de ativação ou se ele for comprometido.
  • Se a credencial for corrompida, perdida ou comprometida após ser baixada por um destinatário.
  • Quando o senhor modifica o tempo de vida dos tokens de destinatário de um metastore. Consulte Modificar o tempo de vida dos tokens do destinatário.

Considerações de segurança para tokens​

A qualquer momento, um destinatário pode ter no máximo dois tokens: um token ativo e um token rotacionado. Os tokens rotacionados são aqueles que foram definidos para expirar e serem substituídos pelos tokens ativos. Até que os tokens girados expirem, a tentativa de girar os tokens novamente resulta em um erro.

Ao girar os tokens de um destinatário, o senhor pode, opcionalmente, definir --existing-token-expire-in-seconds como o número de segundos antes da expiração dos tokens do destinatário existente, ou seja, o que será girado. Se o senhor definir o valor como 0, os tokens de destinatário existentes expiram imediatamente.

A Databricks recomenda que o senhor defina --existing-token-expire-in-seconds como um período relativamente curto que dê à organização destinatária tempo para acessar o novo URL de ativação e, ao mesmo tempo, minimize o tempo em que o destinatário tem dois tokens ativos. Se o senhor suspeitar que os tokens de destinatário existentes estão comprometidos, o site Databricks recomenda forçá-los a expirar imediatamente.

Se a URL de ativação existente de um destinatário nunca tiver sido acessada, a rotação dos tokens existentes invalida essa URL de ativação e a substitui por uma nova.

Se todos os destinatários tokens tiverem expirado, a rotação dos tokens substitui o URL de ativação existente por um novo. Databricks recomenda que o senhor desative ou elimine imediatamente um destinatário cujos tokens tenham expirado.

Se um URL de ativação de destinatário for enviado inadvertidamente para a pessoa errada ou por um canal inseguro, a Databricks recomenda que o senhor:

  1. Revogue o acesso do destinatário ao compartilhamento.
  2. Gire o destinatário e defina --existing-token-expire-in-seconds como 0.
  3. Compartilhe o novo URL de ativação com o destinatário pretendido por meio de um canal seguro.
  4. Depois que o URL de ativação for acessado, conceda ao destinatário acesso ao compartilhamento novamente.

Em situações extremas, em vez de girar os tokens do destinatário, o senhor pode soltar e recriar o destinatário.

Girar os tokens de um destinatário​

Para girar os tokens de um destinatário, o senhor pode usar o Catalog Explorer ou o site Databricks Unity Catalog CLI.

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

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

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

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

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

  5. On the Details tab, under Token Expiration, click Rotate.

  6. On the Rotate token dialog, set the token to expire either immediately or for a set period of time. For advice about when to expire existing tokens, see Security considerations for tokens.

  7. Click Rotate.

  8. On the Details tab, copy the new Activation link and share it with the recipient over a secure channel. See Step 2: Get the activation link.

Modificar o tempo de vida dos tokens do destinatário​

Se o senhor precisar modificar o tempo de vida dos tokens do destinatário do default para o seu Unity Catalog metastore, poderá usar o Catalog Explorer ou o Databricks Unity Catalog CLI.

nota

O tempo de vida dos tokens de destinatário para os destinatários existentes não é atualizado automaticamente quando o senhor altera o tempo de vida dos tokens de destinatário do default para um metastore. Para aplicar o novo tempo de vida dos tokens a um determinado destinatário, o senhor deve girar os tokens. Consulte gerenciar destinatário tokens (compartilhamento aberto).

Permissões necessárias : administrador da conta.

  1. Log in to the account console.
  2. In the sidebar, click Catalog icon Catalog.
  3. Click the metastore name.
  4. Under Delta Sharing recipient token lifetime, click Edit.
  5. Enable Set expiration.
  6. Enter a number of seconds, minutes, hours, or days, and select the unit of measure.
  7. Click Save.

If you disable Set expiration, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

(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.

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

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.

  1. In your Databricks workspace, click Catalog icon Catalog.

  2. At the top of the Catalog pane, click the Gear icon 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 kebab menu and select Delete.

  6. On the confirmation dialog, click Delete.

Última atualização em