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 uma parte da conta.

Depois de criar o destinatário e as ações compartilhadas, você pode conceder ao destinatário acesso a essas ações.

Para conceder acesso de compartilhamento aos destinatários, você pode usar o Catalog Explorer, o Databricks Unity Catalog CLI ou o comando SQL GRANT ON SHARE em um Notebook Databricks ou no editor de consultas Databricks SQL .

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 view uma lista de destinatários, você pode usar o Catalog Explorer, o Databricks Unity Catalog CLI ou o comando SQL SHOW RECIPIENTS em um Notebook Databricks ou no editor de consultas Databricks SQL .

Permissões necessárias : Você deve ter o privilégio USE RECIPIENT para view todos os destinatários no metastore. Outros usuários têm acesso apenas aos destinatários que lhes pertencem.

Catalog Explorer

1. No seu workspace Databricks , 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" .

SQL

execute o seguinte comando em um Notebook ou no editor de consultas Databricks SQL . Opcionalmente, substitua <pattern> por um predicadoLIKE.

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

execute o seguinte comando usando a CLIDatabricks.

Bash

databricks recipients list

Ver detalhes do destinatário

Para view detalhes sobre um destinatário, você pode usar o Catalog Explorer, o Databricks Unity Catalog CLI ou o comando SQL DESCRIBE RECIPIENT em um Notebook Databricks ou no editor de consultas 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:

• Criador do destinatário, carimbo de data/hora da criação, comentários e 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 usar 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. Veja gerenciar propriedades do destinatário.

Catalog Explorer

1. No seu workspace Databricks , 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 CLIDatabricks.

Bash

databricks recipients get <recipient-name>

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

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

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

Catalog Explorer

1. No seu workspace Databricks , 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. Acesse a tab "Compartilhamentos" para view a lista de compartilhamentos feitos 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 CLIDatabricks.

Bash

databricks recipients share-permissions <recipient-name>

Atualizar um destinatário

Para atualizar um destinatário, você pode usar o Catalog Explorer, o Databricks Unity Catalog CLI ou o comando SQL ALTER RECIPIENT em um Notebook Databricks ou no 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 um administrador do metastore ou proprietário do objeto destinatário para atualizar o proprietário. Você precisa 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 workspace Databricks , 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 No menu de kebabs, selecione Renomear .

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

     Clique no Ícone de edição ao lado de Propriedades do destinatário . Em seguida, adicione um nome de propriedade ( chave ) e um valor . Para obter detalhes, consulte gerenciar propriedades do destinatário.

   • Apenas destinatários autenticados por token:

     • Veja e copie o link de autenticação . Veja Obter o link de ativação
     • Em Gerenciamento de tokens , gire ou atualize os tokens de portador. Veja gerenciar tokensde destinatário.

   • Apenas destinatários federados do 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 endpointdo destinatário e endpointMTLS do destinatário .

SQL

Executar um ou mais dos seguintes comandos em um Notebook ou no editor de consultas 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 do 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 CLIDatabricks. 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 o acesso dos destinatários 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).

propriedades do destinatário

Os objetos destinatários 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 uma visualização dinâmica que limite 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 account Databricks à qual o destinatário dos dados pertence (apenas Databricks-to-Databricks ).
• databricks.metastoreId: O metastore Unity Catalog ao qual um destinatário de dados pertence (apenas compartilhamento Databricks-to-Databricks ).
• databricks.nameNome do destinatário dos dados.

Propriedades personalizadas que podem ser úteis podem incluir, por exemplo, country. Por exemplo, se você associar 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 exemplos mais detalhados, consulte Usar propriedades do destinatário para fazer filtragem de partição e Adicionar visualização dinâmica a um compartilhamento para filtrar linhas e colunas.

Requisitos

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

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. Você pode usar o Catalog Explorer, a CLI Databricks Unity Catalog ou o comando SQL em um Notebook Databricks ou no editor de consultas Databricks SQL .

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

Catalog Explorer

Ao criar ou atualizar um destinatário usando o Explorador de Catálogo, adicione ou atualize propriedades personalizadas seguindo estes passos:

1. Acesse 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. Na parte inferior direita da página, em Propriedades do destinatário , clique em Marque com um lápis o campo `databricks.metastoreID` para um destinatário do Databricks ou o campo `databricks.name` para um destinatário aberto.

3. Insira um nome de propriedade ( chave ) e um valor .

   Por exemplo, se você quiser filtrar os dados compartilhados por país e compartilhar apenas os dados dos EUA com esse 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 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 uma string literal ou um identificador. <property-value> deve ser uma string literal.

Por exemplo:

SQL

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

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

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 CLIDatabricks. Substitua os valores de espaço reservado:

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

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 view as propriedades do destinatário, siga as instruções em visualizar detalhes do destinatário.

Excluir um destinatário

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

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 workspace Databricks , 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 , localize e selecione o destinatário.

5. Clique no menu de 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 CLIDatabricks.

Bash

databricks recipients delete <recipient-name>