Gerenciar destinatários de dados para OpenSharing

Esta página descreve como os provedores gerenciam destinatários do OpenSharing existentes no Databricks. Um *destinatário* é o objeto nomeado que representa a identidade de um usuário ou grupo com quem os dados são compartilhados.

Se for um destinatário de dados que procura gerenciar um objeto de provedor importado de um arquivo de credenciais, consulte Gerenciar provedores OpenSharing para destinatários de dados em vez disso.

Para criar um destinatário, consulte Criar destinatários de dados para OpenSharing (compartilhamento Databricks-to-Databricks), Criar um objeto de destinatário para usuários que não são Databricks usando tokens de portador (compartilhamento Databricks-to-Open), ou Habilitar federação Open ID Connect (OIDC) para destinatários OpenSharing. Para gerenciar compartilhamentos, consulte Gerenciar compartilhamentos para OpenSharing.

Conceda ao destinatário acesso a um compartilhamento

Após criar o destinatário e os compartilhamentos, é possível conceder a ele acesso a esses compartilhamentos.

Para conceder acesso de compartilhamento a destinatários, é possível usar o Catalog Explorer, a CLI do Databricks Unity Catalog ou o comando SQL GRANT ON SHARE em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias : Uma das seguintes:

• Administrador do metastore.
• Permissões delegadas ou propriedade nos objetos de compartilhamento e 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 acesso aos compartilhamentos de dados do OpenSharing (para provedores).

Ver destinatários

Para visualizar uma lista de destinatários, é possível usar o Catalog Explorer, a CLI do Databricks Unity Catalog ou o comando SQL SHOW RECIPIENTS em um Notebook do Databricks ou o editor de consultas Databricks SQL.

Permissões necessárias : É necessário ter o privilégio USE RECIPIENT para visualizar todos os destinatários no metastore. Outros usuários têm acesso somente aos destinatários que possuem.

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

SQL

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

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients list

Ver detalhes do destinatário

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

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

Detalhes incluem:

• O criador do destinatário, o timestamp de criação, os comentários e o tipo de autenticação (DATABRICKS, TOKEN, OAUTH_CLIENT_CREDENTIALS ou OIDC_FEDERATION).
• Se o destinatário usa Databricks-to-Open compartilhamento com tokens portadores: duração do token, link de ativação, status de ativação (se a credencial foi baixada) e listas de acesso IP, se atribuídas.
• Se o destinatário usar compartilhamento Databricks-to-Open com federação OIDC: endpoint do destinatário, endpoint MTLS, políticas de federação e listas de acesso IP, se atribuído.
• Se o destinatário usa o compartilhamento Databricks-to-Databricks: a cloud, 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. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

SQL

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

SQL

DESCRIBE RECIPIENT <recipient-name>;

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients get <recipient-name>

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

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

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

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

4. Vá para a **tab Shares** para view a lista de compartilhamentos com o destinatário.

SQL

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

SQL

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients share-permissions <recipient-name>

Atualizar um destinatário

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

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

Permissões necessárias : Você precisa ser administrador do metastore ou proprietário do objeto destinatário para atualizar o proprietário. Você deve ter o privilégio CREATE RECIPIENT e ser o proprietário para atualizar o nome. Você precisa ser o proprietário para atualizar o comentário ou as propriedades personalizadas.

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

3. Na tab 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.

   • Editar ou adicionar um comentário.

   • Renomeie o destinatário.

     Clique no menu kebab e selecione **Renomear**.

   • Edite, remova ou adicione **propriedades do destinatário** personalizadas.

     Clique no ícone de edição ao lado de Propriedades do destinatário. Em seguida, adicione um nome de propriedade (Key) e Valor. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

   • Apenas destinatários autenticados por token:

     • Visualize e copie o **link de autenticação**. Consulte Obter o link de ativação
     • Em Gerenciamento de tokens , gire ou atualize o token do portador. Consulte Gerenciar tokens do destinatário.

   • Somente destinatários federados OIDC:

     • Em **Políticas de federação do OIDC**, clique em **Adicionar políticas**. Consulte Ativar a federação do Open ID Connect (OIDC) para destinatários do OpenSharing.
     • Visualizar e copiar Endpoint do Destinatário e Endpoint MTLS do Destinatário .

SQL

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

SQL

ALTER RECIPIENT <recipient-name> RENAME TO <new-recipient-name>;

ALTER RECIPIENT <recipient-name> OWNER TO <new-owner>;

COMMENT ON RECIPIENT <recipient-name> IS "<new-comment>";

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

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( <property-key> [, ...] )

Para obter mais informações sobre propriedades, consulte Gerenciar propriedades 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.

JSON

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

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

Bash

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

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

(Opcional) Restringir acesso do destinatário usando listas de acesso

Você pode limitar o acesso do destinatário a um conjunto restrito de endereços IP para destinatários de compartilhamento Databricks-to-Open. Consulte Restringir o acesso do destinatário do OpenSharing usando listas de acesso IP (Databricks para compartilhamento aberto).

Gerenciar propriedades do destinatário

Objetos de destinatário incluem propriedades predefinidas que podem ser utilizadas para refinar o acesso ao compartilhamento de dados. Por exemplo, podem ser utilizados 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 visualizações 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.

Também é possível criar propriedades personalizadas.

As propriedades predefinidas começam com databricks. e incluem o seguinte:

• databricks.accountId: A account Databricks à qual um destinatário de dados pertence (apenas para compartilhamento Databricks-to-Databricks).
• databricks.metastoreId: O metastore do Unity Catalog ao qual um destinatário de dados pertence (somente compartilhamento Databricks-to-Databricks).
• databricks.name: O nome do destinatário de 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 apenas as linhas que contêm dados dos EUA com os destinatários que têm 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 do destinatário para fazer a filtragem de partição e Adicionar views dinâmicas a um compartilhamento para filtrar linhas e colunas.

Requisitos

Você deve usar um SQL warehouse ou compute executando o Databricks Runtime 12.2 ou acima.

Adicione propriedades ao criar ou atualizar um destinatário

É possível adicionar propriedades ao criar um destinatário ou atualizá-las para um destinatário existente. Pode-se usar o Catalog Explorer, a CLI do Databricks Unity Catalog ou comandos SQL em um Notebook do Databricks ou no editor de consultas do Databricks SQL.

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

Catalog Explorer

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

1. Ir para a página de detalhes do destinatário.

   Se estiver criando um novo destinatário, você acessa esta página depois que você clica em Criar . Para atualizar um destinatário existente, acesse esta página clicando no **ícone de engrenagem > OpenSharing > Shared by me > Recipients** e selecionando o destinatário.

2. No canto inferior direito da página, em Propriedades do destinatário , clique no lápis ao lado de databricks.metastoreID para um destinatário Databricks ou ao lado de databricks.name para um destinatário aberto.

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

   Por exemplo, se você quiser filtrar dados compartilhados por país e compartilhar apenas dados dos EUA com este destinatário, você pode criar uma key chamada “country” com o valor “US.”

4. Clique em Salvar .

SQL

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

SQL

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[USING ID '<sharing-identifier>'] /* Skip this if you are using open sharing */
[COMMENT "<comment>"]
PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

<property-key> pode ser um literal de string ou identificador. <property-value> deve ser um literal de string.

Por exemplo:

SQL

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

Para adicionar, editar ou excluir propriedades personalizadas para um destinatário existente, execute uma das seguintes opções:

SQL

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

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

CLI

Para adicionar propriedades personalizadas ao criar um destinatário, execute o seguinte comando usando a CLI do Databricks. Substitua os valores temporários:

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

Bash

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

Por exemplo:

Bash

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

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

Bash

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

Visualizar propriedades do destinatário

Para visualizar as propriedades do destinatário, siga as instruções em Detalhes do destinatário.

Excluir um destinatário

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

Ao excluir um destinatário, os usuários representados por ele não podem mais acessar os dados compartilhados. Tokens que os destinatários utilizam em um cenário de compartilhamento Databricks-to-Open são invalidados.

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

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

4. Na **tab Destinatários**, encontre e selecione o destinatário.

5. Clique no menu kebab e selecione Excluir .

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

SQL

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

SQL

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

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients delete <recipient-name>