Aceder a tabelas Databricks a partir de clientes Delta

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

Dica

Para informações sobre como ler dados Azure Databricks usando Microsoft Fabric, veja Microsoft Fabric com Azure Databricks.

Criar, ler e escrever usando a API REST da Unity

Importante

Criar e escrever tabelas geridas pelo Unity Catalog com clientes Delta está atualmente em fase Beta.

A API REST da Unity fornece a clientes externos acesso à criação, leitura e escrita de tabelas registadas no Unity Catalog. Configure o acesso usando a URL do espaço de trabalho como endpoint. Os seguintes tipos de tabelas estão acessíveis:

Tipo de tabela	Leitura	Escreve	Criar
Delta de gestão	Sim	Sim*	Sim*
Delta Externo	Sim	Sim	Sim

* Suportado para tabelas Delta geridas com confirmações de catálogo.

Requerimentos

O Azure Databricks suporta o acesso da API REST da Unity a tabelas como parte do Unity Catalog. Você deve ter o Unity Catalog habilitado em seu espaço de trabalho para usar esses endpoints.

Deve também completar os seguintes passos de configuração para configurar o acesso às tabelas a partir dos clientes Delta usando a API REST da Unity:

Ative o acesso a dados externos para o seu metastore. Consulte Ativar o acesso a dados externos no metastore.
Conceda ao principal que acede dados externamente o EXTERNAL USE SCHEMA privilégio sobre o esquema que contém os objetos. Ver Conceder privilégios a uma entidade no Catálogo Unity.
Para tabelas externas acessadas por caminho: Conceda ao principal o EXTERNAL USE LOCATION privilégio na localização externa que contém o caminho da tabela. Ver Conceder privilégios a uma entidade no Catálogo Unity.
Certifique-se de que o principal tem os privilégios relevantes:
- SELECT na tabela para operações de leitura
- MODIFY na tabela para operação de escrita
- CREATE sobre o esquema para criação de tabelas
- Para escritas externas em tabelas Delta geridas, verifique se a tabela onde está a ser escrita tem commits de catálogo ativados.
Autenticar usando um dos seguintes métodos:
- Token de acesso pessoal (PAT): Ver Autorizar acesso aos recursos do Azure Databricks.
- Autenticação OAuth M2M (machine-to-machine): Suporta a atualização automática de credenciais e tokens para tarefas Spark com duração prolongada (>1 hora). Ver Autorizar o acesso do principal de serviço ao Azure Databricks com OAuth.

Limitações

O acesso externo a tabelas UniForm com o IcebergCompatV3 não é atualmente suportado. Depois de escrever externamente numa tabela UniForm, deve executar MSCK REPAIR TABLE em Databricks para gerar metadados Iceberg.
Alterações de esquema (por exemplo, ALTER TABLE), atualizações de propriedades de tabelas e alterações de funcionalidades de tabela não são atualmente suportadas em tabelas geridas de clientes externos.
Clientes externos não podem realizar operações de manutenção de tabelas, como OPTIMIZE, VACUUM, e ANALYZE, em tabelas Delta geridas.
Clientes externos não conseguem criar clones superficiais.
Clientes externos não podem criar tabelas com colunas geradas, colunas por defeito ou colunas de restrição.
Ao criar tabelas externas, o Azure Databricks recomenda usar o Apache Spark para garantir que as definições das colunas estão num formato compatível com o Apache Spark. A API não valida a exatidão da especificação da coluna. Se a especificação não for compatível com o Apache Spark, o Databricks Runtime pode não conseguir ler as tabelas.

Aceder a tabelas Delta com Apache Spark usando autenticação PAT

A autenticação PAT para clientes externos da Spark requer:

Unity Catalog Spark cliente 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 utilizador que acede ao Unity Catalog. Consulte Autorizar o acesso aos recursos do Azure Databricks.

A seguinte configuração é necessária para ler ou escrever em tabelas Delta geridas pelo Unity Catalog e externas com Apache Spark usando 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 responsável que configura a integração.

: A URL do espaço de trabalho Azure Databricks , incluindo o ID do espaço de trabalho. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Observação

As versões dos pacotes apresentadas acima estão atualizadas até à última atualização desta página. Podem estar disponíveis versões mais recentes. Verifica se as versões dos pacotes são compatíveis com a versão do teu Spark.

Para mais detalhes sobre a configuração do Apache Spark para armazenamento de objetos na cloud, consulte a documentação do Unity Catalog OSS.

Importante

Databricks Runtime 16.4 e superiores são necessários para ler, escrever ou criar tabelas quando os commits de catálogo estão ativados. O Databricks Runtime 18.0 e versões superiores é necessário para poder ativar ou desativar commits de catálogo em tabelas existentes.

Para criar tabelas Delta geridas com commits de catálogo, utilize o seguinte comando 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>;

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

O Azure Databricks também suporta autenticação OAuth máquina-a-máquina (M2M). O OAuth gere automaticamente a renovação de tokens e credenciais para a autenticação do Catálogo Unity.

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

Unity Catalog Spark cliente versão 0.4.1 ou posterior (io.unitycatalog:unitycatalog-spark)
Apache Spark 4.0 ou posterior
Delta Spark 4.2.0 ou posterior
Um principal de serviço OAuth M2M com as permissões apropriadas. Ver Autorizar o acesso do principal de serviço ao Azure Databricks com OAuth.

A seguinte configuração é necessária para criar, ler ou escrever em tabelas geridas pelo Unity Catalog e tabelas Delta externas com Apache Spark usando 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"