Configure uma integração de catálogo para o Unity Catalog

Use the CREATE CATALOG INTEGRATION (Apache Iceberg™ REST) command to create a REST catalog integration that uses vended credentials or an external volume to connect to Databricks Unity Catalog.

Nota

Você pode criar uma integração de catálogo para o Unity Catalog em que o espaço de trabalho do Databricks esteja hospedado em um dos seguintes provedores de nuvem:

  • AWS

  • Azure

  • Google Cloud

You can configure a catalog integration for Unity Catalog that uses OAuth or bearer authentication:

Configure an OAuth catalog integration

Etapa 1: Encontre o URL do seu espaço de trabalho do Databricks

O URL do espaço de trabalho do Databricks é o URL que você usa para acessar seu espaço de trabalho do Databricks. Você precisa encontrar esse URL porque vai especificá-lo mais tarde quando criar uma integração de catálogo.

  1. Encontre o URL do seu espaço de trabalho do Databricks.

    Para obter instruções sobre como encontrar o URL, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

  2. Copie o URL do seu espaço de trabalho do Databricks para um editor de texto.

Etapa 2: Adicionar uma entidade de serviço ao Databricks

  1. Para adicionar uma entidade de serviço, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

  2. Copie o valor de ID do aplicativo da sua entidade de serviço em um editor de texto e salve-o com segurança. Você especificará esse valor mais tarde quando criar uma integração de catálogo no Snowflake.

Etapa 3: Criar um segredo OAuth para sua entidade de serviço

  1. Para criar um segredo OAuth para sua entidade de serviço, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

  2. Copie o valor do segredo que você gerou em um editor de texto e salve-o com segurança. Você especificará esse valor mais tarde quando criar uma integração de catálogo no Snowflake.

    Importante

    O segredo do cliente só é exibido uma vez. Certifique-se de copiá-lo antes de fechar a caixa de diálogo.

Etapa 4: Habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog

Nesta etapa, você usa o Databricks para habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog.

Para habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog por meio de credenciais fornecidas, primeiro habilite o acesso a dados externos no nível do metastore. Em seguida, você precisa conceder à entidade de serviço os privilégios do Unity Catalog para seu catálogo.

Habilitar o acesso a dados externos no metastore (somente credenciais fornecidas)

Se estiver criando uma integração de catálogo que usa credenciais fornecidas, no Databricks, é necessário habilitar o acesso a dados externos no metastore. Se estiver criando uma integração de catálogo que usa um volume externo, é possível pular esta etapa.

Para obter instruções sobre como habilitar o acesso a dados externos no metastore, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

Atribuir sua entidade de serviço a um espaço de trabalho

Em seguida, você precisa atribuir sua entidade de serviço ao seu espaço de trabalho do Databricks.

Para obter instruções, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

Conceder à entidade de serviço acesso ao seu catálogo

Em seguida, você deve conceder à sua entidade de serviço os privilégios do Unity Catalog. Você precisa conceder esses privilégios à sua entidade de serviço para permitir que o Snowflake acesse o catálogo com base nos privilégios especificados.

Privilégios para funcionalidade completa

Para habilitar a funcionalidade completa no Snowflake, você deve conceder os seguintes privilégios:

Nota

Se quiser restringir o acesso ao Snowflake, consulte Privilégios e objetos protegidos do Unity Catalog na documentação do Databricks.

Privilégio

Descrição

EXTERNAL USE SCHEMA

Permite que o Unity Catalog gere e forneça credenciais temporárias com escopo ao Snowflake para acesso a dados de tabela no armazenamento em nuvem.

Nota

Esse privilégio só é necessário quando você cria uma integração de catálogo que usa credenciais fornecidas. Ele não é necessário quando você cria uma integração de catálogo que usa um volume externo. Portanto, se estiver usando um volume externo, remova-o do bloco de código de exemplo.

MODIFY

Permite que o Snowflake adicione, atualize e exclua dados de uma tabela.

SELECT

Permite que o Snowflake consulte tabelas e acesse metadados das tabelas. Necessário para todas as operações no Snowflake, incluindo a leitura de dados e a descoberta de tabelas no banco de dados vinculado a catálogo.

USE CATALOG

Permite que o Snowflake acesse o catálogo. Necessário para se conectar e interagir com objetos no Unity Catalog.

USE SCHEMA

Permite que o Snowflake acesse os esquemas (namespaces) no catálogo. Necessário para visualizar e trabalhar com tabelas em esquemas específicos.
Privilégios Grant

É possível conceder privilégios usando o Catalog Explorer ou o SQL.

Para conceder permissões usando o Databricks Catalog Explorer, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

Importante

No campo Principals, você deve inserir o nome da sua entidade de serviço, não o endereço de e-mail de um usuário ou o nome de um grupo.

Etapa 5: Criação de uma integração de catálogo

O exemplo a seguir cria uma integração de catálogo REST que usa OAuth:

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_oauth_vended_credentials
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
REST_CONFIG = (
  CATALOG_URI = '<databricks_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
  CATALOG_NAME = '<catalog_name>'
  ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
)
REST_AUTHENTICATION = (
  TYPE = OAUTH
  OAUTH_TOKEN_URI = '<databricks_workspace_url>/oidc/v1/token'
  OAUTH_CLIENT_ID = '<client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_secret>'
  OAUTH_ALLOWED_SCOPES = ('all-apis')
)
ENABLED = TRUE;
Copy

Onde:

  • <databricks_workspace_url> especifica o URL do seu espaço de trabalho do Databricks. Para encontrar esse URL, consulte Etapa 1: Encontre o URL do seu espaço de trabalho do Databricks.

    Veja a seguir um exemplo de URL de espaço de trabalho do Databricks para cada plataforma de nuvem:

    • Databricks no AWS: https://dbc-a1a1a1a1-a1a1.cloud.databricks.com

    • Azure Databricks: https://adb-1111111111111111.1.azuredatabricks.net

    • Databricks no Google Cloud: https://1111111111111111.1.gcp.databricks.com

  • <catalog_name> especifica o nome do seu catálogo no Unity Catalog ao qual você deseja conectar o Snowflake. Você encontra esse nome no espaço de trabalho do Databricks em Data > Catalogs.

  • ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS configura a integração de catálogo para usar as credenciais fornecidas do Unity Catalog.

    Nota

    Se estiver criando uma integração de catálogo que usa um volume externo, você deverá excluir o parâmetro ACCESS_DELEGATION_MODE.

  • <client_id> especifica o ID do cliente OAuth da sua entidade de serviço do Databricks. Você copiou esse valor quando adicionou uma entidade de serviço ao Databricks.

    Nota

    No Databricks, esse valor é chamado ID do aplicativo, e não ID do cliente.

  • <oauth_secret> especifica o segredo OAuth da sua entidade de serviço do Databricks. Você copiou esse valor quando criou um segredo OAuth para sua entidade de serviço.

Etapa 6: Verificar a integração do seu catálogo

Próximos passos

Depois de configurar uma integração de catálogo para o seu catálogo no Unity Catalog, use o comando CREATE DATABASE (vinculado a catálogo) para criar um banco de dados vinculado a catálogo especificando a integração de catálogo que você criou. O Snowflake é sincronizado automaticamente com seu catálogo no Unity Catalog para detectar esquemas e tabelas Iceberg, e registra as tabelas remotas no banco de dados vinculado a catálogo.

Ao criar seu banco de dados vinculado a catálogo, você especifica a integração de catálogo.

For example:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'unity_catalog_int_oauth_vended_credentials'
   );
Copy

Nota

Configure a bearer token catalog integration

Etapa 1: Encontre o URL do seu espaço de trabalho do Databricks

O URL do espaço de trabalho do Databricks é o URL que você usa para acessar seu espaço de trabalho do Databricks. Você precisa encontrar esse URL porque vai especificá-lo mais tarde quando criar uma integração de catálogo.

  1. Encontre o URL do seu espaço de trabalho do Databricks.

    Para obter instruções sobre como encontrar o URL, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

  2. Copie o URL do seu espaço de trabalho do Databricks para um editor de texto.

Etapa 2: Adicionar um token de acesso pessoal (PAT) ao Databricks

Você precisa adicionar um token de acesso pessoal (Personal Access Token, PAT) porque deverá especificá-lo quando criar uma integração de catálogo que usa um token de portador para autenticação.

  1. Para adicionar um PAT ao Databricks, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

  2. Copie o valor do seu PAT em um editor de texto e salve-o com segurança. Você especificará esse valor mais tarde quando criar uma integração de catálogo no Snowflake.

Etapa 3: Habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog

Nesta etapa, você usa o Databricks para habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog.

Para habilitar o acesso do Snowflake ao seu catálogo no Unity Catalog por meio de credenciais fornecidas, primeiro habilite o acesso a dados externos no nível do metastore. Em seguida, você precisa conceder ao seu usuário Databricks os privilégios do Unity Catalog para seu catálogo, que o PAT herda.

Habilitar o acesso a dados externos no metastore (somente credenciais fornecidas)

Se estiver criando uma integração de catálogo que usa credenciais fornecidas, no Databricks, é necessário habilitar o acesso a dados externos no metastore. Se estiver criando uma integração de catálogo que usa um volume externo, é possível pular esta etapa.

Para obter instruções sobre como habilitar o acesso a dados externos no metastore, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

Conceder ao usuário Databricks acesso ao seu catálogo

Em seguida, você deve conceder ao seu usuário Databricks os privilégios do Unity Catalog. Você precisa conceder esses privilégios ao seu usuário Databricks para permitir que o Snowflake acesse o catálogo com base nos privilégios especificados. Quando você usa um PAT para autenticação, ele herda todos os privilégios concedidos ao usuário Databricks que criou o PAT.

Privilégios para funcionalidade completa

Para habilitar a funcionalidade completa no Snowflake, você deve conceder os seguintes privilégios:

Nota

Se quiser restringir o acesso ao Snowflake, consulte Privilégios e objetos protegidos do Unity Catalog na documentação do Databricks.

Privilégio

Descrição

EXTERNAL USE SCHEMA

Permite que o Unity Catalog gere e forneça credenciais temporárias com escopo ao Snowflake para acesso a dados de tabela no armazenamento em nuvem.

Nota

Esse privilégio só é necessário quando você cria uma integração de catálogo que usa credenciais fornecidas. Ele não é necessário quando você cria uma integração de catálogo que usa um volume externo. Portanto, se estiver usando um volume externo, remova-o do bloco de código de exemplo.

MODIFY

Permite que o Snowflake adicione, atualize e exclua dados de uma tabela.

SELECT

Permite que o Snowflake consulte tabelas e acesse metadados das tabelas. Necessário para todas as operações no Snowflake, incluindo a leitura de dados e a descoberta de tabelas no banco de dados vinculado a catálogo.

USE CATALOG

Permite que o Snowflake acesse o catálogo. Necessário para se conectar e interagir com objetos no Unity Catalog.

USE SCHEMA

Permite que o Snowflake acesse os esquemas (namespaces) no catálogo. Necessário para visualizar e trabalhar com tabelas em esquemas específicos.
Privilégios Grant

É possível conceder privilégios usando o Catalog Explorer ou o SQL.

Para conceder permissões usando o Databricks Catalog Explorer, consulte o tópico de acordo com o local onde sua conta Databricks está hospedada:

Etapa 4: Criação de uma integração de catálogo

The following example creates a REST catalog integration that uses a bearer token with vended credentials:

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_bearer_vended_credentials
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = '<databricks_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<personal_access_token>'
  )
  ENABLED = TRUE;
Copy

Onde:

  • <databricks_workspace_url> especifica o URL do seu espaço de trabalho do Databricks. Para encontrar esse URL, consulte Etapa 1: Encontre o URL do seu espaço de trabalho do Databricks.

    Veja a seguir um exemplo de URL de espaço de trabalho do Databricks para cada plataforma de nuvem:

    • Databricks no AWS: https://dbc-a1a1a1a1-a1a1.cloud.databricks.com

    • Azure Databricks: https://adb-1111111111111111.1.azuredatabricks.net

    • Databricks no Google Cloud: https://1111111111111111.1.gcp.databricks.com

  • <catalog_name> especifica o nome do seu catálogo no Unity Catalog ao qual você deseja conectar o Snowflake. Você encontra esse nome no espaço de trabalho do Databricks em Data > Catalogs.

  • ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS configura a integração de catálogo para usar as credenciais fornecidas do Unity Catalog.

    Nota

    Se estiver criando uma integração de catálogo que usa um volume externo, você deverá excluir o parâmetro ACCESS_DELEGATION_MODE.

  • <personal_access_token> specifies your Databricks personal access token (PAT). An example of a PAT is aaaa111aaaa111a1a1a1a111111a111a1111.

Etapa 5: Verificar a integração do seu catálogo

Próximos passos

Depois de configurar uma integração de catálogo para o seu catálogo no Unity Catalog, use o comando CREATE DATABASE (vinculado a catálogo) para criar um banco de dados vinculado a catálogo especificando a integração de catálogo que você criou. O Snowflake é sincronizado automaticamente com seu catálogo no Unity Catalog para detectar esquemas e tabelas Iceberg, e registra as tabelas remotas no banco de dados vinculado a catálogo.

Ao criar seu banco de dados vinculado a catálogo, você especifica a integração de catálogo.

For example:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'unity_catalog_int_bearer_vended_credentials'
   );
Copy

Nota

Linguagem: Português