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

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

Um destinatário é um objeto nomeado que representa a identidade de um usuário ou grupo de usuários no mundo real que consome os 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 o Catálogo do Unity:

• Para destinatários com acesso a um workspace do Databricks habilitado para o Catálogo do Unity, você pode criar um objeto destinatário com uma conexão segura gerenciada inteiramente pelo Databricks. Esse modo de compartilhamento é chamado Compartilhamento do Databricks para o Databricks.
• Para destinatários sem acesso a um workspace do Databricks habilitado para o Catálogo do Unity, você deve usar o compartilhamento aberto, com uma conexão segura que você gerencia usando a autenticação baseada em token.

Para obter mais informações sobre esses dois modos de compartilhamento e quando escolher qual, consulte Abrir compartilhamento versus compartilhamento do Databricks para Databricks.

Requisitos

Para criar um destinatário:

• É necessário ser um administrador de metastore ou ter o privilégio CREATE_RECIPIENT para o metastore do Catálogo do Unity em que os dados que você deseja compartilhar estão registrados.
• Você deve criar o destinatário usando um workspace do Azure Databricks que tenha o metastore do Catálogo do Unity anexado.
• Se você usar um notebook do Databricks para criar o destinatário, o cluster deverá usar o Databricks Runtime 11.3 LTS ou superior e o modo de acesso de cluster compartilhado ou de usuário único.

Para outras operações de gerenciamento de destinatários (como exibir, excluir, atualizar e conceder acesso de destinatário a um compartilhamento), consulte os requisitos de permissões listados nas seções específicas da operação deste artigo.

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

Se o destinatário de dados tiver acesso a um workspace do Databricks que foi habilitado para o Catálogo do Unity, você poderá criar um objeto destinatário com um tipo de autenticação.DATABRICKS

Um objeto destinatário com o tipo de autenticação de representa um destinatário de DATABRICKS dados em um metastore específico do Catálogo do Unity, identificado na definição de objeto do destinatário por uma cadeia de caracteres de identificador de compartilhamento que consiste na nuvem, região e UUID do metastore. Os dados compartilhados com esse destinatário só poderão ser acessados nesse metastore.

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

Peça a um usuário destinatário para enviar o identificador de compartilhamento para o metastore do Catálogo do Unity anexado aos workspaces em que o usuário destinatário ou o grupo de usuários trabalhará com os dados compartilhados.

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

Por exemplo, na captura de tela a seguir, a cadeia de caracteres do identificador de compartilhamento completa é aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

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

Explorador do Catálogo

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

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado comigo, clique no nome da organização de compartilhamento do Databricks no canto superior direito e selecione Copiar identificador de compartilhamento.

SQL

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

SELECT CURRENT_METASTORE();

CLI

Execute o comando a seguir usando a CLI do Databricks. O identificador de compartilhamento é retornado como o global_metastore_id.

databricks metastores summary

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

Etapa 2: Criar o destinatário

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

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Novo destinatário.

4. Insira o Nome do destinatário e Identificador do compartilhamento.

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

5. (Opcional) Insira um comentário.

6. Clique em Criar.

7. (Opcional) Criar propriedades do Destinatário personalizadas.

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

SQL

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

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

Use toda a cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

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

CLI

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

• <recipient-name>: o nome do destinatário.
• <sharing-identifier>: Use toda a cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid>. Por exemplo, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.
• <authentication-type>: defina para DATABRICKS quando uma cadeia de caracteres do identificador de compartilhamento no formato <cloud>:<region>:<uuid> for fornecida para <sharing-identifier>.

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

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

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

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

Se você deseja compartilhar dados com usuários fora do workspace do Azure Databricks, independentemente de eles próprios usarem o Databricks, você poder usar o Compartilhamento Delta aberto para compartilhar seus dados com segurança. Aqui está como isso funciona:

1. Como provedor de dados, você cria o objeto destinatário no metastore do Catálogo do Unity.
2. Quando você cria o objeto de destinatário, o Azure Databricks gera um token, um arquivo de credencial que inclui o token e um link de ativação para você compartilhar com o destinatário. O objeto destinatário tem o tipo de autenticação de TOKEN.
3. O destinatário acessa o link de ativação, baixa 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ê lhes dá acesso.

Etapa 1: Criar o destinatário

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

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Novo destinatário.

4. Insira o Nome do 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. Copie o link de ativação.

   Como alternativa, você pode obter o link de ativação mais tarde. Consulte Etapa 2: obtenha o link de ativação.

8. (Opcional) Criar propriedades do Destinatário personalizadas.

   Na guia Detalhes do destinatário, clique em Editar propriedades > +Adicionar propriedade. Em seguida, adicione um nome de propriedade (Chave) e Valor. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas do 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.

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients create <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. Confira Restringir o acesso do destinatário do Delta Sharing usando listas de acesso IP (compartilhamento aberto).

Etapa 2: obtenha o link de ativação

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

Se o destinatário já tiver baixado o 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 o proprietário do objeto do destinatário.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Na página de detalhes do destinatário, copie o link Ativação.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DESCRIBE RECIPIENT <recipient-name>;

A saída inclui activation_link.

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients get <recipient-name>

A saída inclui activation_url.

Conceder ao destinatário acesso a um compartilhamento

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

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

Permissões necessárias: uma das seguintes:

• Administrador de metastore.
• permissões delegadas ou propriedade no compartilhamento e nos objetos de 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, veja Gerenciar o acesso aos compartilhamentos de dados do Delta Sharing (para provedores).

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

Você deve informar ao destinatário como acessar os dados que está compartilhando com ele. As informações que você compartilha com o destinatário dependem se você está usando o compartilhamento do Databricks para o Databricks ou o compartilhamento aberto:

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

  Um objeto de 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 exibir e selecionar os compartilhamentos que desejam usar. Consulte Leitura de dados compartilhados utilizando o compartilhamento Delta do Databricks para o Databricks (para destinatários).

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

  Você pode baixar o arquivo de credenciais apenas uma vez. Os destinatários precisam tratar a credencial baixada como um segredo e não devem compartilhá-la fora da organização. Se você tiver preocupações de que uma credencial possa ter sido tratada de forma insegura, poderá girar a credencial de um destinatário a qualquer momento. Para obter mais informações sobre como gerenciar credenciais para garantir o acesso seguro ao destinatário, consulte Considerações de segurança para tokens.

Exibir destinatários

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

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks. Opcionalmente, substitua <pattern> por um predicado LIKE.

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients list

Exibir detalhes do destinatário

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

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

Os detalhes incluem:

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DESCRIBE RECIPIENT <recipient-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients get <recipient-name>

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

Para exibir a lista de compartilhamentos aos quais um destinatário recebeu acesso, use o Explorador de catálogos, a CLI do Databricks ou o comando SHOW GRANTS TO RECIPIENT SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Acesse a guia Compartilhamentos para exibir a lista de compartilhamentos compartilhados com o destinatário.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients share-permissions <recipient-name>

Atualizar um destinatário

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

As propriedades que você pode atualizar incluem nome do destinatário, proprietário, comentário e propriedades personalizadas.

Permissões necessárias: você deve ser um administrador de metastore ou um proprietário do objeto do destinatário para atualizar o proprietário. É necessário ser um administrador de metastore (ou um usuário com o privilégio CREATE_RECIPIENT) e o proprietário para atualizar o nome. Você deve ser o proprietário para atualizar o comentário ou as propriedades personalizadas.

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em 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 de Destinatário personalizadas.

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

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

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.

CLI

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

{
    "name": "new-recipient-name",
    "owner": "someone-else@example.com",
    "comment": "something new",
    "ip_access_list": {
            "allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
    },
    "property": {
            "country": "us",
            "id": "001"
    }
}

Em seguida, execute o comando a seguir usando a CLI do Databricks. Substitua <recipient-name> pelo nome do destinatário atual e substitua update-recipient-settings.json pelo nome do arquivo JSON.

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

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

Gerenciar tokens de destinatário (compartilhamento aberto)

Se você estiver compartilhando dados com um destinatário usando o compartilhamento aberto, talvez seja necessário girar o token desse destinatário. Girar um token consiste em definir um token existente para expirar e substituí-lo por um novo token e URL de ativação.

Você deverá girar a credencial de um destinatário e gerar uma nova URL de ativação nas seguintes circunstâncias:

• Quando o token de destinatário existente estiver prestes a expirar.
• Se um destinatário perder a URL de ativação ou se ela estiver comprometida.
• Se a credencial estiver corrompida, for perdida ou estiver comprometida depois que for baixada por um destinatário.
• Quando você modifica o tempo de vida do token do destinatário para um metastore. Consulte Modificar o tempo de vida do token 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 girado. O token girado é aquele que foi definido para expirar e ser substituído pelo token ativo. Até que o token girado expire, tentar girar o token novamente resultará em um erro.

Ao girar um token de um destinatário, opcionalmente, você pode definir --existing-token-expire-in-seconds como o número de segundos antes que o token de destinatário a ser girado existente expire. Se você definir o valor como 0, o token de destinatário existente vai expirar imediatamente.

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

Se a URL de ativação existente de um destinatário nunca tiver sido acessada, girar o token existente invalida essa URL de ativação e a substituirá por uma nova.

Se todos os tokens de destinatário expiraram, girar o destinatário substitui a URL de ativação existente por uma nova. O Databricks recomenda que você gire ou remova imediatamente um destinatário cujo token expirou.

Se um link de ativação do destinatário for enviado inadvertidamente para a pessoa errada ou for enviado por um canal não seguro, 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 a nova URL de ativação com o destinatário pretendido em um canal seguro.
4. Depois que a URL de ativação tiver sido acessada, permita novamente o acesso do destinatário ao compartilhamento.

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

Girar o token de um destinatário

Para girar o token de um destinatário, você pode usar o Esplorador de Catálogos ou a CLI do Catálogo do Unity Databricks.

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

4. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

5. Na guia Detalhes, em Expiração do Token, clique em Girar.

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

7. Clique em Girar.

8. Na guia Detalhes, copie o novo link ativação e compartilhe-o com o destinatário em um canal seguro. Consulte Etapa 2: obtenha o link de ativação.

CLI

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

   • <recipient-name>: o nome do destinatário.
   • <expiration-seconds>: o número de segundos até que o token do destinatário existente expire. Durante esse período, o token existente continuará funcionando. Um valor igual a 0 significa que o token existente expira imediatamente. Para obter conselhos sobre quando expirar tokens existentes, consulte Considerações de segurança para tokens.

   databricks recipients rotate-token \
   <recipient-name> \
   <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. Consulte Etapa 2: obtenha o link de ativação.

Modificar o tempo de vida do token do destinatário

Se você precisar modificar o tempo de vida do token de destinatário padrão para seu metastore do Catálogo do Unity, poderá usar o Explorador de Catálogos ou a CLI do Catálogo do Unity Databricks.

Observação

O tempo de vida do token de destinatários existentes não é atualizado automaticamente ao alterar o tempo de vida do token de destinatário padrão para um metastore. Para aplicar o novo tempo de vida de token a um determinado destinatário, é necessário girar o token. Confira Gerenciar tokens de destinatário (compartilhamento aberto).

Permissões necessárias: administrador da conta.

Explorador do Catálogo

1. Faça logon no console da conta.
2. Na barra lateral, clique em Catálogo.
3. Clique no nome do metastore.
4. Em Tempo de vida do token de destinatário do Compartilhamento Delta, clique em Editar.
5. Habilite Definir validade.
6. Insira um número de segundos, minutos, horas ou dias e selecione a unidade de medida.
7. Clique em Save (Salvar).

Se você desabilitar Definir validade, os tokens de destinatário não vão expirar. O Databricks recomenda que você configure os tokens para que eles expirem.

CLI

Execute o comando a seguir usando a CLI do Databricks. Substitua 12a345b6-7890-1cd2-3456-e789f0a12b34 pela UUID do metastore e substitua 86400 pelo número de segundos antes que o token do destinatário expire. Se você definir esse valor como 0, os tokens de destinatário não expirarão. O Databricks recomenda que você configure os tokens para que eles expirem.

databricks metastores update \
12a345b6-7890-1cd2-3456-e789f0a12b34 \
--delta-sharing-recipient-token-lifetime-in-seconds 86400

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

Gerenciar propriedades do destinatário

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

• Compartilhe diferentes partições de tabela com diferentes destinatários, permitindo que você use os mesmos compartilhamentos com vários destinatários, mantendo os limites de dados entre eles.
• Compartilhe exibições dinâmicas que limitam 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: A conta do Azure Databricks à qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
• databricks.metastoreId: O metastore do Catálogo do Unity ao qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
• databricks.name: O nome do destinatário dos dados.

As propriedades personalizadas que podem ser de valor podem incluir, por exemplo, country. Por exemplo, se você anexar a propriedade 'country' = 'us' personalizada a um destinatário, poderá particionar dados de tabela por país e compartilhar apenas linhas que tenham dados dos EUA com os destinatários que têm essa propriedade atribuída. Você também pode compartilhar uma exibição dinâmica que restringe o acesso a linhas ou colunas com base nas propriedades do destinatário. Para obter exemplos mais detalhados, confira Usar propriedades de destinatário para filtrar partições e Adicionar exibições dinâmicas a um compartilhamento para filtrar linhas e colunas.

Requisitos

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

Adicionar propriedades ao criar ou atualizar um destinatário

Você pode adicionar propriedades ao criar um destinatário ou atualizá-las para um destinatário existente. Você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

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

Explorador do Catálogo

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

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

   Se você estiver criando um novo destinatário, você entrará nesta página depois de clicar em Criar. Se você estiver atualizando um destinatário existente, vá para esta página clicando no ícone de engrenagem > Compartilhamento Delta > Compartilhado por mim > Destinatários e selecionando o destinatário.

2. Clique em Editar propriedades > +Adicionar propriedade.

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

   Por exemplo, se você quiser filtrar dados compartilhados por país e compartilhar apenas dados dos EUA com esse destinatário, poderá criar uma chave chamada "país" com um valor de "EUA".

4. Clique em Save (Salvar).

SQL

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

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

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>' );

CLI

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

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

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

Por exemplo:

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

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

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

Exibir propriedades do destinatário

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

Excluir um destinatário

Para excluir um destinatário, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando SQL DROP RECIPIENT em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks. Você deve ser o proprietário do objeto destinatário para excluir o destinatário.

Quando você exclui um destinatário, os usuários representados pelo destinatário não podem mais acessar os dados compartilhados. Os tokens que os destinatários usam em um cenário de compartilhamento aberto são invalidados.

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

Explorador do Catálogo

1. No workspace do Azure Databricks, clique em Catálogo.

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

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Na guia Compartilhamentos, 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 comando a seguir em um notebook ou no editor de SQL do Databricks.

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients delete <recipient-name>