Gerenciar provedores de compartilhamento Delta para destinatários de dados

Esta página descreve como usar o Catálogo do Unity para obter informações sobre provedores de dados que estão compartilhando dados com você usando o Compartilhamento Delta. Ele também descreve o que é um objeto de provedor e quando talvez seja necessário criar um objeto de provedor no metastore do Catálogo do Unity, uma tarefa que a maioria dos destinatários nunca deve precisar fazer.

Os destinatários precisam criar objetos do provedor?

No Delta Sharing no Databricks, o termo “provedor” pode se referir tanto à organização que compartilha dados com você quanto a um objeto seguro no metastore do Catálogo Unity de um destinatário, que representa essa organização. A existência desse objeto protegível no metastore do Catálogo do Unity de um destinatário permite que os destinatários gerenciem o acesso de sua equipe a dados compartilhados usando o Catálogo do Unity.

Como um destinatário com acesso a um metastore do Catálogo do Unity, normalmente você não precisa criar objetos do 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 Catálogo do Unity.

Antes de começar

Para gerir fornecedores no seu espaço de trabalho Azure Databricks:

• Seu workspace deve estar habilitado para o Catálogo do Unity.
• Para visualizar um provedor, você deve ser um administrador do metastore ou um administrador do metastore deve conceder a você o privilégio USE PROVIDER.
• Para criar um provedor, você deve ser um administrador de metastore ou um administrador de metastore deve conceder-lhe o privilégio CREATE PROVIDER.
• Para criar um provedor, você deve ser um administrador de metastore ou um administrador de metastore deve conceder-lhe o privilégio CREATE PROVIDER. Para obter detalhes, veja Atualizar um provedor (renomear, alterar proprietário, comentar).

Por esse motivo, se o seu espaço de trabalho foi criado sem um administrador de metastore, um administrador de conta Azure Databricks deve conceder a um utilizador ou grupo a função de administrador de metastore antes de poder trabalhar com objetos de fornecedor em Azure Databricks. Veja Habilitação automática do Catálogo Unity e (opcional) Atribuir a função de administrador do metastore.

Exibir provedores

Para exibir uma lista de provedores de dados disponíveis, use o Explorador do Catálogo, a CLI do Catálogo do Unity do Databricks ou o comando SQL SHOW PROVIDERS em um notebook do Azure Databricks ou o editor de consulta SQL do Databricks.

Permissões necessárias: você deve ter o USE PROVIDER privilégio de exibir todos os provedores no metastore. Outros usuários têm acesso somente aos provedores que possuem.

Explorador do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > Delta Sharing.

3. Na guia Compartilhado comigo , exiba todos os dados compartilhados com sua organização. Para cada compartilhamento, os seguintes detalhes são fornecidos:

   • Nome: 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 o email do provedor.
   • Criado em: A data e a hora de quando o compartilhamento foi criado.
   • Descrição: A descrição do compartilhamento.

SQL

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

SHOW PROVIDERS [LIKE <pattern>];

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks providers list

Ver detalhes do provedor

Para exibir detalhes sobre um provedor, use o Explorador de Catálogos, a CLI do Catálogo do Unity do Databricks ou o comando SQL DESCRIBE PROVIDER em um notebook do Azure Databricks ou o editor de consulta do Databricks SQL.

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

Os detalhes incluem:

• Compartilhamentos compartilhados pelo provedor (consulte Exibir compartilhamentos que um provedor compartilhou com você).
• O criador do provedor, carimbo de data/hora de criação, comentários e tipo de autenticação (TOKEN ou DATABRICKS). TOKEN representa provedores que compartilharam dados com você usando o protocolo de compartilhamento aberto do Compartilhamento Delta. DATABRICKS representa provedores que compartilharam dados com você usando o protocolo de compartilhamento de Databricks para Databricks.
• Se o provedor usar o compartilhamento do Databricks para Databricks: a nuvem, a região e o ID do metastore do Catálogo do Unity do provedor.
• Se o provedor usar o compartilhamento aberto: seu ponto de extremidade do perfil do destinatário, que é o local em que o servidor de compartilhamento Delta está hospedado.

Explorador do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > Delta Sharing.

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

SQL

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

DESC PROVIDER <provider-name>;

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks providers get <provider-name>

Ver compartilhamentos que um provedor compartilhou com você

Para exibir os compartilhamentos que um provedor compartilhou com você, use o Explorador do Catálogo, a CLI do Catálogo do Unity do Databricks ou o comando SQL SHOW SHARES IN PROVIDER em um notebook do Azure Databricks ou o editor de consulta do Databricks SQL.

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

Explorador do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > Delta Sharing.

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

SQL

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

SHOW SHARES IN PROVIDER [LIKE <pattern>];

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

 databricks providers list-shares <provider-name>

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

Você pode usar o Explorador de Catálogos, a CLI do Catálogo do Unity do Databricks ou o comando SQL ALTER PROVIDER em um notebook do Azure Databricks ou o editor de consulta SQL do Databricks para modificar o objeto do provedor em seu metastore do Catálogo do Unity:

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

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

Explorador do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > Delta Sharing.

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

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

   Para renomear um provedor, clique no Menu kebab e selecione Renomear.

SQL

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

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 comando a seguir 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>

Renovar credenciais para destinatários públicos

Esta seção se aplica a objetos de provedor com o tipo TOKENde autenticação, OAUTH_CLIENT_CREDENTIALSou OIDC_FEDERATION. Os provedores Databricks a Databricks (tipo de autenticação DATABRICKS) rotacionam automaticamente. Se você acessar dados sem um objeto de provedor, por exemplo, usando o conector delta-sharing Python ou Spark, aplique o novo arquivo de credencial na configuração do conector. Consulte Ler dados compartilhados usando o compartilhamento aberto delta com tokens de portador.

Um provedor que usa o protocolo de compartilhamento aberto pode girar seu token de portador e enviar um novo arquivo de credencial. Quando isso acontecer, use a API REST do Databricks para atualizar o objeto do provedor. Não remova e recrie o provedor para aplicar uma nova credencial. Os catálogos se associam à ID interna do provedor, não ao nome dele. Recriar um provedor com o mesmo nome interrompe a conexão do catálogo com os dados compartilhados.

ALTER PROVIDER, a CLI do Databricks e o Catalog Explorer não dão suporte à atualização das credenciais do provedor.

Atualizar a credencial

Envie uma solicitação PATCH para o endpoint do provedor com o conteúdo do novo arquivo de credencial no campo recipient_profile_str.

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

Python

Execute o seguinte em um notebook no espaço de trabalho do destinatário. Substitua <provider-name> pelo nome do objeto do provedor em seu metastore e atualize new_profile com os valores do novo arquivo de credencial.

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 resposta a seguir com os metadados atualizados do provedor.

{
  "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 obter detalhes, consulte a API REST de atualização de um provedor .

Verificar a rotação

Confirme se 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 do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > Delta Sharing.

3. Na guia Compartilhado comigo , localize seu provedor.

As faixas de erro anteriores devem ter desaparecido e as ações devem ser listadas novamente. O catálogo listado deve ser o mesmo que era anteriormente.

SQL

Execute o SQL a seguir em um notebook 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 forem bem-sucedidas, a rotação será concluída e todas as consultas, trabalhos e dashboards existentes continuarão funcionando.

Solução de problemas

Excluir um provedor

Para excluir um provedor, você pode usar o Gerenciador de Catálogos, a CLI do Databricks ou o comando SQL DROP PROVIDER em um bloco de anotações Azure Databricks ou no 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 do Catálogo

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

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

   Como alternativa, no canto superior direito, clique em Compartilhar > 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 comando a seguir em um notebook ou no editor de SQL do Databricks.

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

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks providers delete <provider-name>

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