Gerir fornecedores de Delta Sharing para destinatários de dados

Esta página descreve como usar o Unity Catalog para obter informações sobre fornecedores de dados que partilham dados consigo através do Delta Sharing. Ele também descreve o que é um objeto de provedor e quando você pode precisar criar um objeto de provedor em seu metastore do Unity Catalog, uma tarefa que a maioria dos destinatários nunca precisa fazer.

Os destinatários precisam criar objetos de provedor?

No Delta Sharing on Databricks, o termo "provedor" pode significar tanto a organização que está compartilhando dados com você quanto um objeto protegível no metastore do Unity Catalog de um destinatário que representa essa organização. A existência desse objeto protegível no metastore do Unity Catalog de um destinatário permite que os destinatários gerenciem o acesso de sua equipe aos dados compartilhados usando o Unity Catalog.

Como um destinatário com acesso a um metastore do Unity Catalog, normalmente não é necessário criar objetos de provedor. Isso ocorre porque os dados devem ser compartilhados com você usando o compartilhamento de Databricks para Databricks, e os objetos do provedor são criados automaticamente no metastore do Unity Catalog.

Antes de começar

Para gerenciar provedores em seu espaço de trabalho do Azure Databricks:

• Seu espaço de trabalho deve estar habilitado para o Catálogo Unity.
• Para exibir um provedor, você deve ser um administrador de metastore ou um administrador de metastore deve conceder-lhe o USE PROVIDER privilégio.
• Para criar um provedor, você deve ser um administrador de metastore ou um administrador de metastore deve conceder-lhe o CREATE PROVIDER privilégio.
• Para atualizar um provedor, você deve ser o proprietário do objeto do provedor e ter o CREATE PROVIDER privilégio. Para obter detalhes, consulte Atualizar um provedor (renomear, alterar proprietário, comentar).

Por esse motivo, se seu espaço de trabalho foi criado sem um administrador de metastore, um administrador de conta do Azure Databricks deve conceder a um usuário ou grupo a função de administrador de metastore antes de poder trabalhar com objetos de provedor no Azure Databricks. Consulte Ativação automática do catálogo Unity e (opcional) Atribuir a função de administrador do metastore.

Ver fornecedores

Para exibir uma lista de provedores de dados disponíveis, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Unity do Databricks ou o SHOW PROVIDERS comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas do Databricks SQL.

Permissões necessárias: Deve ter o privilégio USE PROVIDER de ver todos os fornecedores na metastore. Outros usuários têm acesso apenas aos provedores que possuem.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. No separador Partilhado comigo , veja todos os dados partilhados com a sua organização. Para cada ação, são fornecidos os seguintes detalhes:

   • Designação: O nome da organização, conforme especificado pelo provedor.
   • Tipo de autenticação: O método de compartilhamento usado pelo provedor.
   • Proprietário: O nome ou e-mail do provedor.
   • Criado em: A data e a hora em que o compartilhamento foi criado.
   • Descrição: A descrição da partilha.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL. Opcionalmente, substitua <pattern> por um LIKE predicado.

SHOW PROVIDERS [LIKE <pattern>];

Para obter mais detalhes sobre SHOW PROVIDERS, consulte SHOW PROVIDERS.

CLI

Execute o seguinte comando usando a CLI do Databricks.

databricks providers list

Ver detalhes do fornecedor

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

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

Os detalhes incluem:

• Partilhas partilhadas pelo fornecedor (consulte Ver partilhas que um fornecedor partilhou consigo).
• O criador, o carimbo de data/hora de criação, os comentários e o tipo de autenticação (TOKEN ou DATABRICKS) do provedor TOKEN representa os provedores que compartilharam dados com você usando o protocolo de compartilhamento aberto Delta Sharing. DATABRICKS representa provedores que compartilharam dados com você usando o protocolo de compartilhamento Databricks-to-Databricks.
• Se o provedor usar a partilha de Databricks para Databricks: a nuvem, a região e o ID do metastore do Unity Catalog do provedor.
• Se o provedor usar o compartilhamento aberto: o endpoint do perfil do destinatário, que é o local onde está hospedado o servidor de compartilhamento Delta Sharing.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. Na guia Compartilhado comigo, localize e selecione o provedor.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

DESC PROVIDER <provider-name>;

Para obter mais detalhes sobre DESC PROVIDER, consulte DESCRIBE PROVIDER.

CLI

Execute o seguinte comando usando a CLI do Databricks.

databricks providers get <provider-name>

Ver partilhas que um fornecedor partilhou consigo

Para exibir os compartilhamentos que um provedor compartilhou com você, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Unity do Databricks ou o SHOW SHARES IN PROVIDER comando SQL em um bloco de anotações do Azure Databricks ou no editor de consultas do Databricks SQL.

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

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. Na guia Compartilhado comigo, localize e selecione o provedor.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL. Opcionalmente, substitua <pattern> por um LIKE predicado.

SHOW SHARES IN PROVIDER [LIKE <pattern>];

Para obter mais detalhes sobre SHOW SHARES IN PROVIDER, consulte SHOW SHARES IN PROVIDER.

CLI

Execute o seguinte comando usando a CLI do Databricks.

 databricks providers list-shares <provider-name>

Atualizar um provedor (renomear, alterar proprietário, comentar)

Você pode usar o Catalog Explorer, a CLI do Databricks Unity Catalog ou o ALTER PROVIDER comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas Databricks SQL para modificar o objeto do provedor em seu metastore do Unity Catalog:

• Renomeie o provedor para modificar a maneira como os usuários veem o objeto do provedor em suas interfaces Databricks.
• Altere o proprietário do objeto do provedor.
• Adicione ou modifique comentários.

Permissões necessárias: Você deve ser o proprietário do objeto do provedor para atualizar o proprietário. Você deve ser um administrador de metastore (ou um utilizador com o privilégio CREATE PROVIDER) e proprietário do provedor para atualizar o nome dele. Você deve ser o proprietário para atualizar o comentário. O proprietário inicial é o administrador da metastore.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. Na guia Compartilhado comigo, localize e selecione o provedor.

4. Na página de detalhes, atualize o proprietário, comentário ou nome do provedor.

   Para renomear um provedor, clique no e selecione Renomear.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

ALTER PROVIDER <provider-name> RENAME TO <new-provider-name>
OWNER TO <new-owner>
COMMENT "<comment>";

Para obter mais detalhes sobre ALTER PROVIDER, consulte ALTER PROVIDER.

CLI

Execute o seguinte comando usando a CLI do Databricks. Substitua <provider-name> pelo nome do provedor atual e <new-provider-name> pelo novo nome.

databricks providers update <provider-name> /
--new-name <new-provider-name> /
--comment "<new comment>" /
--owner <new-owner-name>

Rodar credenciais para destinatários abertos

Esta secção aplica-se a objetos de fornecedor com tipo TOKENde autenticação , OAUTH_CLIENT_CREDENTIALS, ou OIDC_FEDERATION. Os fornecedores Databricks-para-Databricks (tipo DATABRICKSde autenticação) rodam automaticamente. Se aceder a dados sem um objeto do fornecedor, por exemplo, usando o conector delta-sharing Python ou Spark, aplique o novo ficheiro de credencial na configuração do seu conector. Veja Ler dados partilhados usando Delta Sharing, partilha aberta com tokens de portador.

Um fornecedor que utilize o protocolo de partilha aberta pode substituir o seu token de acesso e enviar-lhe um novo ficheiro de credenciais. Quando isso acontecer, use a API REST do Databricks para atualizar o objeto fornecedor. Não elimine e crie novamente o fornecedor para aplicar uma nova credencial. Os catálogos ligam-se ao ID interno do fornecedor, não ao seu nome. Recriar um fornecedor com o mesmo nome quebra a ligação do catálogo aos dados partilhados.

ALTER PROVIDER, a CLI Databricks e o Explorador de Catálogo não suportam a atualização das credenciais do fornecedor.

Atualizar a credencial

Envie um PATCH pedido ao endpoint do fornecedor com o conteúdo do novo ficheiro de credencial no campo recipient_profile_str.

Permissões necessárias: Proprietário do objeto fornecedor ou administrador da metastore.

Python

Execute o seguinte a partir de um caderno no espaço de trabalho destinatário. Substitua <provider-name> pelo nome do objeto fornecedor na sua metastore e atualize new_profile com os valores do novo ficheiro de credenciais.

import json
import requests

new_profile = {
    "shareCredentialsVersion": 1,
    "bearerToken": "<new-bearer-token>",
    "endpoint": "https://<provider-workspace>.cloud.databricks.com/api/2.0/delta-sharing/metastores/<metastore-id>",
}

token = (
    dbutils.notebook.entry_point.getDbutils()
    .notebook()
    .getContext()
    .apiToken()
    .get()
)
workspace_url = spark.conf.get("spark.databricks.workspaceUrl")

response = requests.patch(
    f"https://{workspace_url}/api/2.1/unity-catalog/providers/<provider-name>",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={"recipient_profile_str": json.dumps(new_profile)},
)

print(response.status_code)
print(response.json())

curl

curl --request PATCH \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header "Content-Type: application/json" \
  --url "https://<databricks-instance>/api/2.1/unity-catalog/providers/<provider-name>" \
  --data '{
    "recipient_profile_str": "<contents of the new credential file>"
  }'

Uma rotação bem-sucedida retorna a seguinte resposta com os metadados atualizados do fornecedor.

{
  "name": "<provider-name>",
  "authentication_type": "TOKEN",
  "owner": "user@example.com",
  "recipient_profile": {
    "share_credentials_version": 1,
    "endpoint": "https://<provider-workspace>.cloud.databricks.com/api/2.0/delta-sharing/metastores/<metastore-id>"
  },
  "updated_at": 1775804332820,
  "updated_by": "user@example.com",
  "id": "abcd2a5b-c18e-46eb-ae11-3056cfe99bef"
}

Para detalhes, consulte a API REST Atualizar um fornecedor .

Verificar a rotação

Confirme que o catálogo, os esquemas e as tabelas ainda estão acessíveis. O nome do catálogo deve ser o mesmo de antes da rotação.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. No separador Partilhado comigo, encontre o seu fornecedor.

Os banners de erro anteriores devem desaparecer e as ações devem voltar a ser listadas. O catálogo listado deve ser o mesmo de antes.

SQL

Execute o seguinte SQL num caderno ou no editor de consultas SQL do Databricks.

-- The catalog name should match what it was before rotation
SHOW CATALOGS;

-- Schemas in the shared catalog should still appear
SHOW SCHEMAS IN <catalog-name>;

-- Tables should still appear
SHOW TABLES IN <catalog-name>.<schema-name>;

-- A read from a shared table should return data
SELECT * FROM <catalog-name>.<schema-name>.<table-name> LIMIT 10;

Se as consultas tiverem sucesso, a rotação está concluída e todas as consultas, trabalhos e dashboards existentes continuam a funcionar.

Resolução de Problemas

Excluir um provedor

Para eliminar um fornecedor, pode usar o Explorador de Catálogos, a CLI do Databricks, ou o comando SQL DROP PROVIDER num bloco de notas Azure Databricks ou o editor de consultas SQL do Databricks. Você deve ser o proprietário do objeto do provedor para excluir o provedor.

Quando você exclui um provedor, você e os usuários em sua organização (o destinatário) não podem mais acessar os dados compartilhados pelo provedor.

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

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

3. Na guia Compartilhado comigo, localize e selecione o provedor.

4. Clique no menu kebab e selecione Excluir.

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

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

DROP PROVIDER [IF EXISTS] <provider-name>;

Para obter mais detalhes sobre DROP PROVIDER, consulte DROP PROVIDER.

CLI

Execute o seguinte comando usando a CLI do Databricks.

databricks providers delete <provider-name>

Se a operação for bem-sucedida, nenhum resultado será retornado.