Crie e gerencie destinatários de dados para compartilhamento Delta

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

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

  • Para destinatários com acesso a um workspace do Databricks habilitado para Unity Catalog, você pode criar um objeto de destinatário com uma conexão segura gerenciada inteiramente pelo Databricks. Esse modo de compartilhamento é chamado de compartilhamento Databricks-to-Databricks.

  • 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 qual, consulte Compartilhamento aberto versus compartilhamento Databricks-to-Databricks .

Requisitos

Para criar um destinatário:

  • Você 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.

  • Você deve criar o destinatário usando um workspace do Databricks que tenha esse metastore do Unity Catalog anexado.

  • Se você usar um Databricks Notebook para criar o destinatário, seus clusters deverão usar o Databricks Runtime 11.3 LTS ouacima e o modo de acesso clusters compartilhados ou 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 da operação destes artigos.

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

Se o destinatário de dados tiver acesso a um espaço de trabalho do Databricks que foi habilitado para 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 em um determinado metastore Unity Catalog , identificado na definição do objeto de destinatário por uma strings de identificador de compartilhamento que consiste na cloud, região e UUID do metastore. Os dados compartilhados com esse destinatário podem ser acessados apenas nesse metastore.

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

Peça a um usuário destinatário para enviar a você o identificador de compartilhamento para o metastore do Unity Catalog que está anexado ao workspace onde o usuário destinatário ou grupo de usuários trabalhará com os dados compartilhados.

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

Por exemplo, na captura de tela a seguir, as strings completas do identificador de compartilhamento são aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

exemplo de CURRENT_METASTORE

O destinatário pode encontrar o identificador usando o Catalog Explorer, a CLI Unity Catalog ou a função SQL default CURRENT_METASTORE em um Notebook do Databricks ou query Databricks SQL que é executada em clusters compatíveis com Unity-Catalog no workspace que eles pretendem usar.

Para obter o identificador de compartilhamento usando o Catalog Explorer:

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado comigo.

  3. acima da tab Provedores , clique no ícone Cópia do identificador de compartilhamento .

execução do seguinte comando em um Notebook ou no editor query Databricks SQL :

SELECT CURRENT_METASTORE();

execução do seguinte comando usando a CLI do Databricks. O identificador de compartilhamento é retornado como global_metastore_id.

databricks unity-catalog metastores get-summary

Você pode ajudar o destinatário enviando ao seu contato as informações contidas neste passo ou pode apontá-lo para Obter acesso no modelo Databricks-to-Databricks.

passo 2: criar o destinatário

Para criar um destinatário para compartilhamento de Databricks para Databricks, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL CREATE RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL .

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Clique em Novo Destinatário.

  4. Digite o nome do destinatário e o identificador de compartilhamento.

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

  5. (Opcional) Insira um comentário.

  6. Clique em Criar.

  7. (Opcional) Crie propriedades de Destinatário personalizadas.

    Clique em Editar propriedades > +Adicionar propriedade. Em seguida, adicione um nome de propriedade (key) e Valor. Para obter detalhes, consulte gerenciar propriedades do destinatário.

execução do seguinte comando em um Notebook ou no editor query Databricks SQL :

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

Use todas as strings 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.

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

  • <recipient-name>: O nome do destinatário.

  • <sharing-identifier>: todas as strings do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

databricks unity-catalog recipients create --name <recipient-name> --sharing-id <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.

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

Se você deseja compartilhar dados com usuários fora do seu workspace do Databricks, independentemente de eles usarem o próprio Databricks, você pode usar o Delta compartilhamento aberto para compartilhar seus dados com segurança. Veja como funciona:

  1. Como um provedor de dados, você cria o objeto destinatário em seu metastore do Unity Catalog.

  2. Quando você cria o objeto de destinatário, o Databricks gera um tokens, um arquivo de credencial que inclui os tokens e um link de ativação para você compartilhar 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 autenticar e obter acesso de leitura às tabelas incluídas nos compartilhamentos aos quais você concede acesso.

passo 1: criar o destinatário

Para criar um destinatário para compartilhamento aberto, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL CREATE RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL .

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Clique em Novo Destinatário.

  4. Digite o nomedo destinatário

  5. (Opcional) Insira um comentário.

  6. Clique em Criar.

    Você não usa o identificador de compartilhamento para destinatários de compartilhamento aberto.

  7. (Opcional) Crie propriedades de Destinatário personalizadas.

    Clique em Editar propriedades > +Adicionar propriedade. Em seguida, adicione um nome de propriedade (key) e Valor. Para obter detalhes, consulte gerenciar propriedades do destinatário.

execução do seguinte comando em um Notebook ou no editor query Databricks SQL :

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[COMMENT "<comment>"];

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

execução do seguinte comando usando a CLI do Databricks.

databricks unity-catalog recipients create --name <recipient-name>

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

A saída inclui o activation_url que você compartilha com o destinatário.

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

Observação

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 Usar listas de acesso IP para restringir o acesso de destinatários Delta Sharing (compartilhamento aberto).

Conceda ao destinatário acesso a um compartilhamento

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 Catalog Explorer, a CLI Unity Catalog ou o comando SQL GRANT ON SHARE em um Notebook do Databricks ou no editor query Databricks SQL .

Permissões necessárias: Uma das seguintes:

  • Administrador de 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 Conceder e gerenciar acesso a compartilhamentos de dados de compartilhamento Delta (para provedores).

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

Você deve informar ao destinatário como acessar os dados que você está compartilhando com ele. A informação que você compartilha com o destinatário depende se você está usando o compartilhamento Databricks-to-Databricks ou o compartilhamento aberto:

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

    Um objeto provedor que lista os compartilhamentos disponíveis é criado automaticamente no 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 o compartilhamento Delta do Databricks-to-Databricks (para destinatários).

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

    Você pode downloads o arquivo de credencial apenas uma vez. Os destinatários devem tratar a credencial downloads como um segredo e não devem compartilhá-la fora de sua organização. Se você tem dúvidas de que uma credencial pode ter sido manipulada de forma insegura, você pode alternar a credencial de um destinatário a qualquer momento. Para obter mais informações sobre como gerenciar 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, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL SHOW RECIPIENTS em um Notebook do Databricks ou no editor query Databricks SQL .

Permissões necessárias: você 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 apenas aos destinatários de sua propriedade.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Abra a tab Destinatários .

execução do seguinte comando em um Notebook ou no editor query Databricks SQL . Opcionalmente, substitua <pattern> por um predicado `LIKE`.

SHOW RECIPIENTS [LIKE <pattern>];

execução do seguinte comando usando a CLI do Databricks.

databricks unity-catalog recipients list

Ver detalhes do destinatário

Para view detalhes sobre um destinatário, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL DESCRIBE RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL .

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

Os detalhes incluem:

  • O criador do destinatário, carimbo de data/hora de criação, comentários e tipo de autenticação (TOKEN ou DATABRICKS).

  • Se o destinatário usar compartilhamento aberto: o tempo de vida tokens , link de ativação, status de ativação (se a credencial foi downloads) e listas de acesso IP, se atribuídas.

  • Se o destinatário usar o compartilhamento Databricks-para-Databricks: a cloud, a região e a ID do metastore do metastore do Unity Catalog do destinatário, bem como o status de ativação.

  • Propriedades do destinatário, incluindo propriedades personalizadas. Consulte gerenciar as propriedades do destinatário.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Na tab Destinatários , localize e selecione o destinatário.

  4. view os detalhes do destinatário na tab Detalhes .

execução do seguinte comando em um Notebook ou no editor query Databricks SQL .

DESCRIBE RECIPIENT <recipient-name>;

execução do seguinte comando usando a CLI do Databricks.

databricks unity-catalog recipients get --name <recipient-name>

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

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

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Na tab Destinatários , localize e selecione o destinatário.

  4. Vá para a tab Compartilhamentos para view a lista de compartilhamentos compartilhados com o destinatário.

execução do seguinte comando em um Notebook ou no editor query Databricks SQL .

SHOW GRANTS TO RECIPIENT <recipient-name>;

execução do seguinte comando usando a CLI do Databricks.

databricks unity-catalog recipients list-permissions --name <recipient-name>

Atualizar um destinatário

Para atualizar um destinatário, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL ALTER RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL .

As propriedades que você pode atualizar incluem nome do destinatário, proprietário, comentário e propriedades personalizadas. Você não pode atualizar o nome do destinatário usando o Catalog Explorer.

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 do metastore (ou usuário 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 customizadas.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Na tab Destinatários , localize e selecione o destinatário.

  4. Na página de detalhes, você pode:

    • Atualize o proprietário.

    • Edite ou adicione um comentário.

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

      Clique em Editar propriedades. Para adicionar uma propriedade, clique em +Adicionar propriedade e insira um nome de propriedade (key) e Valor. Para obter detalhes, consulte gerenciar propriedades do destinatário.

execução de um ou mais dos seguintes comandos em um Notebook ou no editor query 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 do destinatário.

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 unity-catalog recipients update --name <recipient-name> --json-file update-recipient-settings.json

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

gerenciar tokens de destinatários (compartilhamento aberto)

Se você estiver compartilhando dados com um destinatário usando compartilhamento aberto, pode ser necessário alternar os tokens desse destinatário.

Você deve alternar a credencial de um destinatário e gerar um novo link de ativação nas seguintes circunstâncias:

  • Quando os tokens de destinatário existentes estão prestes a expirar.

  • Se um destinatário perder seu URL de ativação ou se ele estiver comprometido.

  • Se a credencial for corrompida, perdida ou comprometida após o downloads por um destinatário.

  • Quando você modifica o tempo de vida tokens de destinatário para um metastore. Consulte Modificar o tempo de vida 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. Até que os tokens girados expirem, tentar girar os tokens novamente resultará em erro.

Ao alternar os tokens de um destinatário, você pode, opcionalmente, definir --existing-token-expire-in-seconds para o número de segundos antes que os tokens de destinatário existentes expirem. Se você definir o valor como 0, os tokens destinatário existentes expirarão imediatamente.

Databricks recomenda que você defina --existing-token-expire-in-seconds para um período relativamente curto que dê à organização do destinatário tempo para acessar a nova URL de ativação, minimizando a quantidade de tempo que o destinatário tem dois tokens ativos. Se você suspeitar que os tokens de destinatário estão comprometidos, o Databricks recomenda que você force os tokens destinatário existentes a expirar imediatamente.

Se o URL de ativação existente de um destinatário nunca foi acessado e o destinatário não foi alternado, a rotação do destinatário invalida o URL de ativação existente e o substitui por um novo.

Se todos os tokens de destinatário tiverem expirado, a rotação do destinatário substituirá a URL de ativação existente por uma nova. Databricks recomenda que você gire ou descarte imediatamente um destinatário cujos tokens expiraram.

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

  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 link de ativação com o destinatário pretendido em um canal seguro.

  4. Depois que a URL de ativação for acessada, conceda ao destinatário acesso ao compartilhamento novamente.

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

Girar os tokensde um destinatário

Para girar os tokens de um destinatário, você pode usar o Catalog Explorer ou a CLI Unity Catalog .

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Na tab Destinatários , localize e selecione o destinatário.

  4. Na tab Detalhes, em Expiraçãotokens , clique em Girar.

  5. Na caixa de diálogo Girar tokens , defina os tokens para expirar imediatamente ou por um determinado período de tempo. Para obter conselhos sobre quando expirar os tokens existentes, consulte Considerações de segurança para tokens.

  6. Clique em Girar.

  7. Na tab Detalhes , copie o novo link de ativação e compartilhe-o com o destinatário em um canal seguro. Veja o passo 2: Obtenha o link de ativação.

  1. execute o seguinte comando usando a CLI do Unity Catalog. Os argumentos entre colchetes são opcionais. Substitua os valores de espaço reservado:

    • <recipient-name>: o nome do destinatário.

    • <expiration-seconds>: Opcional. O número de segundos até que os tokens destinatário existentes expirem. Durante esse período, os tokens existentes continuarão funcionando. Um valor de 0 significa que os tokens existentes expiram imediatamente. Para obter conselhos sobre quando expirar os tokens existentes, consulte Considerações de segurança para tokens.

    databricks unity-catalog rotate-recipient-token \
      --name <recipient-name> \
      [--existing-token-expire-in-seconds <expiration-seconds>]
    
  2. Obtenha o novo link de ativação do destinatário e compartilhe-o com o destinatário por meio de um canal seguro. Veja o passo 2: Obtenha o link de ativação.

Modifique o tempo de vida tokens do destinatário

Se precisar modificar o tempo de vida tokens de destinatário default para seu metastore do Catálogo do Unity, você poderá usar o Catalog Explorer ou a CLI do Databricks Unity Catalog.

Observação

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

Permissões necessárias: account admin.

  1. log in no console da conta.

  2. Na barra lateral, clique em Ícone de catálogo Catalog.

  3. Clique no nome do metastore.

  4. Habilite Definir expiração.

  5. Insira um número de segundos, minutos, horas ou dias e selecione a unidade de medida.

  6. Clique em Habilitar.

Se você desabilitar Definir expiração, os tokens de destinatário não expiram. Databricks recomenda que você configure os tokens para expirar.

Crie um arquivo JSON que inclua uma atualização para o valor delta_sharing_recipient_token_lifetime_in_seconds do metastore. Se você definir esse valor como 0, os tokens de destinatário não expirarão. Databricks recomenda que você configure os tokens para expirar.

{
  "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
}

Em seguida, execute o seguinte comando usando a CLI do Databricks. Substitua 12a345b6-7890-1cd2-3456-e789f0a12b34 pelo metastore UUID e substitua update-metastore.json pelo nome do arquivo JSON.

databricks unity-catalog metastores update --id 12a345b6-7890-1cd2-3456-e789f0a12b34 \
  --json-file update-metastore.json

(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 destinatário. Consulte Usar listas de acesso IP para restringir o acesso de destinatários Delta Sharing (compartilhamento aberto).

gerenciar propriedades do destinatário

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

  • Compartilhe diferentes partições de tabela com diferentes destinatários, permitindo usar os mesmos compartilhamentos com vários destinatários, mantendo os limites de dados entre eles.

  • Compartilhe view dinâmicas que limitam o acesso do destinatário aos dados da tabela no nível de 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 account do Databricks à qual um destinatário de dados pertence (somente compartilhamento de Databricks para Databricks).

  • databricks.metastoreId: o metastore 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.

Propriedades customizadas que podem ter valor 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 apenas as linhas que contenham dados dos EUA com os destinatários que tenham essa propriedade atribuída. Você também pode compartilhar uma view dinâmica 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 filtrar partições e Adicionar view dinâmica a um compartilhamento para filtrar linhas e colunas.

Requisitos

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

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 Catalog Explorer, a CLI Unity Catalog ou comandos SQL em um Notebook do Databricks ou no editor query Databricks SQL .

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

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

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

    Se estiver criando um novo destinatário, você chegará a esta página depois de clicar em Criar. Se você estiver atualizando um destinatário existente, vá para esta página clicando em Delta compartilhamento > Compartilhado por mim > Destinatários e selecionando o destinatário.

  2. Clique em Editar propriedades > +Adicionar propriedade.

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

    Por exemplo, se você deseja filtrar os dados compartilhados por país e compartilhar apenas os dados dos EUA com esse destinatário, pode criar uma key denominada “país” com o valor “EUA”.

  4. Clique em Salvar.

Para adicionar uma propriedade personalizada ao criar um destinatário, execute o seguinte comando em um Notebook ou no editor query 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 uma strings literal ou um identificador. <property-value> deve ser uma strings literal.

Por exemplo:

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

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

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

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

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 uma strings literal ou um identificador.

  • <property-value> deve ser uma strings literal.

databricks unity-catalog recipients create --name <recipient-name> --property <property-key>=<property-value>

Por exemplo:

databricks unity-catalog recipients create --name acme --property country=us --property partner_id=001

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

databricks unity-catalog recipients update --name acme --property country=us --property partner_id=001

Exibir propriedades do destinatário

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

Excluir um destinatário

Para excluir um destinatário, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL DROP RECIPIENT em um Notebook do Databricks ou no editor query 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 destinatário.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

  2. No painel esquerdo, expanda o menu Delta compartilhamento e selecione Compartilhado por mim.

  3. Na tab Destinatários , localize e selecione o destinatário.

  4. Clique no Menu Kebab menu kebab (também conhecido como menu de três pontos) e selecione Excluir.

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

execução do seguinte comando em um Notebook ou no editor query Databricks SQL .

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

execução do seguinte comando usando a CLI do Databricks.

databricks unity-catalog recipients delete --name <recipient-name>