Gerenciar provedores do OpenSharing para destinatários de dados

Esta página descreve como usar o Unity Catalog para obter informação sobre provedores de dados que estão compartilhando dados com você usando OpenSharing. 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 deveria precisar fazer.

importante

Os destinatários dos dados devem ter acesso a um workspace do Databricks habilitado para o Unity Catalog para usar as funcionalidades descritas. Esta página não se aplica a destinatários que não têm workspaces habilitados para o Unity Catalog.

Os destinatários precisam criar objetos de provedor?

No OpenSharing no Databricks, o termo "provedor" pode significar tanto a organização que está compartilhando dados com você quanto um objeto protegível em um 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 destinatário com acesso a um metastore do Unity Catalog, normalmente não é preciso criar objetos do provedor. Isso ocorre porque os dados devem ser compartilhados com você usando o compartilhamento Databricks-to-Databricks, e os objetos do provedor são criados automaticamente em seu metastore do Unity Catalog.

nota

Se você estiver recebendo dados de um provedor que não está compartilhando de um workspace do Databricks habilitado para Unity Catalog, você pode usar o Catalog Explorer para importar o arquivo de credenciais do provedor. Consulte Importar um provedor e ler dados compartilhados no Databricks.

Antes de começar

Para gerenciar provedores em seu workspace Databricks:

Seu workspace deve estar habilitado para o Unity Catalog.
Para visualizar um provedor, você deve ser um administrador de metastore, ou um administrador de metastore deve conceder a você o privilégio USE PROVIDER.
Para criar um provedor, você deve ser um administrador do metastore, ou um administrador do metastore deve conceder a você o privilégio CREATE PROVIDER.
Para atualizar um provedor, o senhor deve ser o proprietário do objeto do provedor e ter o privilégio CREATE PROVIDER. Para obter detalhes, consulte Atualizar um provedor (renomear, alterar proprietário, comentar).

Por esse motivo, se o seu workspace foi criado sem um administrador de metastore, um administrador de conta do Databricks deve conceder a um usuário ou grupo a função de administrador de metastore antes que seja possível trabalhar com objetos de provedor no Databricks. Consulte Começar a usar o Unity Catalog e Administradores do metastore.

View de provedores

Para visualizar uma lista de provedores de dados disponíveis, pode-se usar o Catalog Explorer, a CLI do Databricks Unity Catalog, ou o comando SQL SHOW PROVIDERS em um notebook Databricks ou o editor de consultas Databricks SQL.

Permissões necessárias : É necessário ter o privilégio USE PROVIDER para visualizar todos os provedores na metastore. Outros usuários possuem acesso somente aos provedores dos quais são proprietários.

Catalog Explorer
SQL
CLI

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na tab Compartilhado comigo , visualize 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 email do provedor.
- Criado em: A data e a hora em que o compartilhamento foi criado.
- Descrição: a descrição do compartilhamento.

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

SQL
SHOW PROVIDERS [LIKE <pattern>];

Para mais detalhes sobre SHOW PROVIDERS, consulte SHOW PROVIDERS.

Execute o seguinte comando usando a CLI do Databricks.

Bash
databricks providers list

View detalhes do provedor

Para visualizar detalhes sobre um provedor, você pode usar o Catalog Explorer, a CLI do Databricks Unity Catalog, ou o comando SQL DESCRIBE PROVIDER em um Notebook do Databricks ou no editor de consultas 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.

Detalhes incluem:

Compartilhamentos compartilhados pelo provedor (consulte Visualizar compartilhamentos que um provedor compartilhou com você).
O criador do provedor, Timestamp 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 Databricks-to-Open. DATABRICKS representa provedores que compartilharam dados com você usando o protocolo de compartilhamento Databricks-to-Databricks.
Se o provedor usar o compartilhamento Databricks-to-Databricks: o cloud, a região e o ID do metastore do Unity Catalog do provedor.
Se o provedor usar o compartilhamento Databricks-para-Open: o endpoint do seu perfil de destinatário, que é onde o servidor de compartilhamento do OpenSharing está hospedado.

Catalog Explorer
SQL
CLI

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na tab **Compartilhados comigo**, localize e selecione o provedor.

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

SQL
DESC PROVIDER <provider-name>;

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

Execute o seguinte comando usando a CLI do Databricks.

Bash
databricks providers get <provider-name>

Visualizar compartilhamentos que um provedor compartilhou com você

Para visualizar os compartilhamentos que um provedor compartilhou com você, você pode usar o Catalog Explorer, a CLI do Databricks Unity Catalog, ou o comando SQL SHOW SHARES IN PROVIDER em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

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

Catalog Explorer
SQL
CLI

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na tab **Compartilhados comigo**, localize e selecione o provedor.

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

SQL
SHOW SHARES IN PROVIDER [LIKE <pattern>];

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

Execute o seguinte comando usando a CLI do Databricks.

Bash
 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 comando SQL ALTER PROVIDER em um Notebook do Databricks ou no editor de consultas do Databricks SQL para modificar o objeto do provedor em seu metastore do Unity Catalog:

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

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

Catalog Explorer
SQL
CLI

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na tab **Compartilhados comigo**, localize e selecione o provedor.
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 .

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

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

Para mais detalhes sobre ALTER PROVIDER, consulte ALTER PROVIDER.

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

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

Altere as credenciais para destinatários abertos

Esta seção se aplica a objetos de provedor com tipo de autenticação TOKEN, OAUTH_CLIENT_CREDENTIALS ou OIDC_FEDERATION. Provedores Databricks-to-Databricks (tipo de autenticação DATABRICKS) alternam 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 sua configuração de conector. Consulte Ler dados compartilhados com tokens de portador.

Um provedor que usa o protocolo de compartilhamento aberto Databricks-to-Open pode renovar seu token de portador e enviar a você um novo arquivo de credenciais. Quando isso ocorre, utilize a API REST do Databricks para atualizar o objeto do provedor. Não exclua e recrie o provedor para aplicar uma nova credencial. Os catálogos vinculam-se ao ID interno do provedor, não ao seu nome. A recriação de um provedor com o mesmo nome rompe a conexão do catálogo com os dados compartilhados.

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

Atualize 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 provedor ou administrador do metastore.

Python
curl

Execute o seguinte a partir de um notebook no workspace 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 credenciais.

Python
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={
        &quot;Authorization&quot;: f&quot;Bearer {token}&quot;,
        &quot;Content-Type&quot;: &quot;application/json&quot;,
    },
    json={&quot;recipient_profile_str&quot;: json.dumps(new_profile)},
)

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

Bash
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 provedor.

JSON
{
  "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 Atualizar um provedor.

Verifique 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.

Catalog Explorer
SQL

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na guia Compartilhados comigo , localize o provedor.

Os banners de erro anteriores devem desaparecer e os compartilhamentos devem ser listados novamente. O catálogo listado deve ser o mesmo que era anteriormente.

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

SQL
-- 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 queries forem bem-sucedidas, a rotação estará completa e todas as queries, Jobs e painéis existentes continuarão funcionando.

Solução de problemas

Erro	Corrigir
A solicitação retorna `403 Forbidden`	Você deve ser o proprietário do provedor ou um administrador do metastore para rotacionar as credenciais. Peça a um administrador do metastore para aplicar a rotação ou transferir a propriedade. Consulte Atualizar um provedor (renomear, alterar proprietário, comentar).
A solicitação retorna `404 Not Found`	O nome do provedor está incorreto. Execute `SHOW PROVIDERS` para listar os nomes exatos em seu metastore.
A solicitação retorna `400 Bad Request` com a mensagem "o perfil do destinatário não pode ser atualizado".	A API atualiza as credenciais apenas para os provedores `TOKEN`, `OAUTH_CLIENT_CREDENTIALS` e `OIDC_FEDERATION`. Para compartilhamento Databricks-to-Databricks, as credenciais são giradas automaticamente.
Consultas retornam `TABLE_OR_VIEW_NOT_FOUND`	O nome do catálogo pode estar incorreto ou a vinculação entre catálogo e provedor pode estar quebrada. Execute `SHOW CATALOGS` e `SHOW SCHEMAS IN <catalog-name>` para confirmar que o catálogo existe.
O Catalog Explorer mostra dados desatualizados ou erros após um `PATCH` bem-sucedido.	Você está vendo resultados em cache de antes da rotação. Atualize a página ou aguarde alguns minutos.

Erro	Corrigir
A solicitação retorna `403 Forbidden`	Você deve ser o proprietário do provedor ou um administrador do metastore para rotacionar as credenciais. Peça a um administrador do metastore para aplicar a rotação ou transferir a propriedade. Consulte Atualizar um provedor (renomear, alterar proprietário, comentar).
A solicitação retorna `404 Not Found`	O nome do provedor está incorreto. Execute `SHOW PROVIDERS` para listar os nomes exatos em seu metastore.
A solicitação retorna `400 Bad Request` com a mensagem "o perfil do destinatário não pode ser atualizado".	A API atualiza as credenciais apenas para os provedores `TOKEN`, `OAUTH_CLIENT_CREDENTIALS` e `OIDC_FEDERATION`. Para compartilhamento Databricks-to-Databricks, as credenciais são giradas automaticamente.
Consultas retornam `TABLE_OR_VIEW_NOT_FOUND`	O nome do catálogo pode estar incorreto ou a vinculação entre catálogo e provedor pode estar quebrada. Execute `SHOW CATALOGS` e `SHOW SCHEMAS IN <catalog-name>` para confirmar que o catálogo existe.
O Catalog Explorer mostra dados desatualizados ou erros após um `PATCH` bem-sucedido.	Você está vendo resultados em cache de antes da rotação. Atualize a página ou aguarde alguns minutos.

Excluir um provedor

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

Quando um provedor é excluído, o usuário e os usuários em sua organização (o destinatário) não conseguem mais acessar os dados compartilhados pelo provedor.

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

Catalog Explorer
SQL
CLI

No seu Databricks workspace, clique em Catálogo .
No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.
Na tab **Compartilhados comigo**, localize e selecione o provedor.
Clique no menu kebab e selecione Excluir .
Na caixa de diálogo de confirmação, clique em Excluir .

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

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

Para mais detalhes sobre DROP PROVIDER, consulte DROP PROVIDER.

Execute o seguinte comando usando a CLI do Databricks.

Bash
databricks providers delete <provider-name>

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

Os destinatários precisam criar objetos de provedor?​

Antes de começar​

View de provedores​

View detalhes do provedor​

Visualizar compartilhamentos que um provedor compartilhou com você​

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

Altere as credenciais para destinatários abertos​

Atualize a credencial​

Verifique a rotação.​

Solução de problemas​

Excluir um provedor​

Os destinatários precisam criar objetos de provedor?

Antes de começar

View de provedores

View detalhes do provedor

Visualizar compartilhamentos que um provedor compartilhou com você

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

Altere as credenciais para destinatários abertos

Atualize a credencial

Verifique a rotação.

Solução de problemas

Excluir um provedor