Acessar tabelas do Databricks a partir de clientes Delta

Esta página descreve como usar a API REST do Unity para criar, ler e escrever em tabelas gerenciadas e externas do Catálogo Unity a partir de clientes Delta externos. Para obter uma lista completa de integrações com suporte, consulte as integrações do Catálogo do Unity.

Criar, ler e gravar usando a API REST do Unity

A API REST do Unity fornece aos clientes externos acesso de criação, leitura e gravação a tabelas registradas no Catálogo do Unity. Configure o acesso usando a URL do workspace como o endpoint. Os seguintes tipos de tabela são acessíveis:

* Com suporte para tabelas Delta gerenciadas com confirmações de catálogo.

Requisitos

Azure Databricks dá suporte ao acesso à API REST do Unity para tabelas como parte do Catálogo do Unity. Você deve ter o Catálogo do Unity habilitado em seu espaço de trabalho para usar esses endpoints.

Você também deve concluir as seguintes etapas de configuração para configurar o acesso a tabelas de clientes Delta usando a API REST do Unity:

• Habilite o Acesso a dados externos no seu metastore. Confira Habilitar o acesso a dados externos no metastore.
• Conceda ao principal que acessa dados externamente o privilégio EXTERNAL USE SCHEMA no esquema que contém os objetos. Consulte Conceder privilégios de catálogo principal do Unity.
• Para tabelas externas acessadas pelo caminho: conceda ao principal o EXTERNAL USE LOCATION privilégio no local externo que contém o caminho da tabela. Consulte Conceder privilégios de catálogo principal do Unity.
• Verifique se o principal tem privilégios relevantes:
  • SELECT na tabela para leituras
  • MODIFY na tabela para gravações
  • CREATE no esquema para criação de tabela
  • Para gravações externas em tabelas Delta gerenciadas, verifique se a tabela que está sendo gravada tem confirmações de catálogo habilitadas.
• Autenticar usando um dos seguintes métodos:
  • PAT (token de acesso pessoal): consulte Authorize o acesso aos recursos Azure Databricks.
  • Autenticação M2M (máquina a máquina) do OAuth: oferece suporte à atualização automática de credenciais e tokens para trabalhos Spark de longa execução (>1 hora). Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

Limitações

• No momento, não há suporte para o acesso externo às tabelas UniForm com IcebergCompatV3. Depois de gravar externamente em uma tabela UniForm, você deve executar MSCK REPAIR TABLE no Databricks para gerar metadados do Iceberg.
• Atualmente, não há suporte para alterações de esquema (por exemplo), ALTER TABLEatualizações de propriedade de tabela e alterações de recursos de tabela em tabelas gerenciadas de clientes externos.
• Clientes externos não podem executar operações de manutenção de tabela, como OPTIMIZE, VACUUMe ANALYZE, em tabelas Delta gerenciadas.
• Clientes externos não podem criar clones rasos.
• Clientes externos não podem criar tabelas com colunas geradas, colunas padrão ou colunas de restrição.
• Ao criar tabelas externas, Azure Databricks recomenda usar o Apache Spark para garantir que as definições de coluna estejam em um formato compatível com o Apache Spark. A API não valida a correção da especificação da coluna. Se a especificação não for compatível com o Apache Spark, o Databricks Runtime poderá não conseguir ler as tabelas.

Acessar tabelas Delta com Apache Spark usando autenticação PAT

A autenticação pat para clientes externos do Spark requer:

• Cliente Spark do Unity Catalog versão 0.4.1 ou superior (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 ou superior
• Delta Spark 4.2.0 ou superior
• Um token de acesso pessoal para o principal que acessa o Unity Catalog. Consulte Autorizar o acesso aos recursos do Azure Databricks.

A configuração a seguir é necessária para ler ou gravar tabelas Delta gerenciadas e externas do Catálogo do Unity com Apache Spark, usando a autenticação PAT.

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Substitua as seguintes variáveis:

• <uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
• <token>: Token de acesso pessoal (PAT) para o principal que está configurando a integração.

• <workspace-url>: A URL do workspace Azure Databricks , incluindo a ID do workspace. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Para obter detalhes adicionais sobre como configurar o Apache Spark para armazenamento de objetos na nuvem, consulte a documentação do Catálogo do Unity OSS.

Para criar tabelas Delta gerenciadas com confirmações de catálogo, use o seguinte SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

Para criar tabelas Delta externas, use o seguinte SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

Acessar tabelas Delta com o Apache Spark usando a autenticação OAuth

Azure Databricks também dá suporte à autenticação M2M (máquina a máquina) do OAuth. O OAuth manipula automaticamente o token e a renovação de credenciais para a autenticação do Catálogo do Unity.

A autenticação OAuth para clientes externos do Spark requer:

• Cliente Spark do Catálogo do Unity versão 0.4.1 ou posterior (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 ou posterior
• Delta Spark 4.2.0 ou posterior
• Uma entidade de serviço OAuth M2M com permissões apropriadas. Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

A configuração a seguir é necessária para criar, ler ou gravar em tabelas gerenciadas do Catálogo do Unity e tabelas Delta externas com Apache Spark usando a autenticação OAuth:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Substitua as seguintes variáveis:

• <uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
• <oauth-token-endpoint>: URL do ponto de extremidade do token OAuth. Para construir essa URL:
  1. Localize a URL do Azure Databricks workspace.
  2. Use o formato: https://<workspace-url>/oidc/v1/token
• <oauth-client-id>: ID do cliente OAuth para seu principal de serviço. Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.
• <oauth-client-secret>: segredo do cliente OAuth para sua entidade de serviço. Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

• <workspace-url>: A URL do workspace Azure Databricks , incluindo a ID do workspace. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.