Accéder aux tables Databricks à partir de clients Delta

Cette page explique comment utiliser l’API REST Unity pour créer, lire et écrire dans le catalogue Unity des tables gérées et externes à partir de clients Delta externes. Pour obtenir la liste complète des intégrations prises en charge, consultez intégrations du catalogue Unity.

Conseil / Astuce

Pour plus d’informations sur la lecture des données Azure Databricks à l’aide de Microsoft Fabric, consultez Microsoft Fabric avec Azure Databricks.

Créer, lire et écrire à l’aide de l’API REST Unity

Important

La création et l’écriture dans des tables gérées par le catalogue Unity à partir de clients Delta sont en version bêta.

L’API REST Unity fournit aux clients externes l’accès en création, lecture et écriture aux tables inscrites dans le catalogue Unity. Configurez l’accès à l’aide de l’URL de l’espace de travail comme point de terminaison. Les types de tableau suivants sont accessibles :

Type de table	Lire	Write	Créer
Delta géré	Oui	Oui*	Oui*
Delta externe	Oui	Oui	Oui

* Pris en charge pour les tables Delta managées avec des validations de catalogue.

Spécifications

Azure Databricks prend en charge l’accès de l’API REST Unity aux tables dans le cadre du catalogue Unity. Le catalogue Unity doit être activé dans votre espace de travail pour utiliser ces points de terminaison.

Vous devez également effectuer les étapes de configuration suivantes pour configurer l’accès aux tables à partir de clients Delta à l’aide de l’API REST Unity :

• Activez l’Accès à des données externes pour votre metastore. Consultez Activer l'accès aux données externes dans le metastore.
• Accordez au principal qui accède aux données externes le privilège EXTERNAL USE SCHEMA sur le schéma contenant les objets. Consultez Accorder des privilèges de catalogue Unity principaux.
• Pour les tables externes accessibles par chemin : accordez à l'utilisateur principal le EXTERNAL USE LOCATION privilège sur l'emplacement externe contenant le chemin de la table. Consultez Accorder des privilèges de catalogue Unity principaux.
• Vérifiez que le principal dispose de privilèges pertinents :
  • SELECT sur le tableau pour les lectures
  • MODIFY sur la table pour l'écriture
  • CREATE sur le schéma de création de tables
  • Pour les écritures externes dans des tables Delta gérées, vérifiez que la table dans laquelle vous écrivez a les validations de catalogue activées.
• Authentifiez-vous à l’aide de l’une des méthodes suivantes :
  • Jeton d’accès personnel (PAT) : consultez Autoriser l’accès aux ressources Azure Databricks.
  • Authentification de machine à machine (M2M) OAuth : prend en charge l’actualisation automatique des informations d’identification et des jetons pour les travaux Spark de longue durée (>1 heure). Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.

Limites

• L’accès externe aux tables UniForm avec IcebergCompatV3 n’est actuellement pas pris en charge. Après avoir écrit en externe dans une table UniForm, vous devez exécuter MSCK REPAIR TABLE dans Databricks pour générer des métadonnées Iceberg.
• Les modifications de schéma (par exemple, ALTER TABLE), les mises à jour des propriétés de table et les modifications des fonctionnalités de table ne sont actuellement pas prises en charge sur les tables gérées à partir de clients externes.
• Les clients externes ne peuvent pas effectuer d’opérations de maintenance de table, telles que OPTIMIZE, VACUUMet ANALYZE, sur des tables Delta gérées.
• Les clients externes ne peuvent pas créer de clones peu profonds.
• Les clients externes ne peuvent pas créer de tables avec des colonnes générées, des colonnes par défaut ou des colonnes de contrainte.
• Lors de la création de tables externes, Azure Databricks recommande d’utiliser Apache Spark pour vous assurer que les définitions de colonnes sont dans un format compatible avec Apache Spark. L’API ne valide pas la précision de la spécification de colonne. Si la spécification n’est pas compatible avec Apache Spark, Databricks Runtime peut ne pas pouvoir lire les tables.

Accéder aux tables Delta avec Apache Spark à l’aide de l’authentification PAT

L’authentification PAT pour les clients Spark externes nécessite :

• Client Spark Unity Catalog version 0.4.1 ou supérieure (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 ou version ultérieure
• Delta Spark 4.2.0 ou version ultérieure
• Jeton d’accès personnel pour le principal qui accède à Unity Catalog. Consultez Autoriser l’accès aux ressources Azure Databricks.

La configuration suivante est nécessaire pour lire ou écrire dans les tables Delta managées et externes du catalogue Unity avec Apache Spark à l’aide de l’authentification 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"

Remplacez les variables suivantes :

• <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
• <token>: jeton d’accès personnel (PAT) pour la personne principale configurant l’intégration.

• <workspace-url> : URL Azure Databricks workspace, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.

Note

Les versions de package indiquées ci-dessus sont actuelles à compter de la dernière mise à jour de cette page. Des versions plus récentes peuvent être disponibles. Vérifiez que les versions de package sont compatibles avec votre version Spark.

Pour plus d’informations sur la configuration d’Apache Spark pour le stockage d’objets cloud, consultez la documentation du catalogue Unity OSS.

Important

Databricks Runtime 16.4 et versions ultérieures est nécessaire pour lire, écrire ou créer des tables avec des validations de catalogue activées. Databricks Runtime 18.0 et versions ultérieures est nécessaire pour activer ou désactiver les validations de catalogue sur les tables existantes.

Pour créer des tables Delta managées avec des validations de catalogue, utilisez le code SQL suivant :

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

Pour créer des tables Delta externes, utilisez le code SQL suivant :

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

Accéder aux tables Delta avec Apache Spark à l’aide de l’authentification OAuth

Azure Databricks prend également en charge l’authentification de machine à machine (M2M) OAuth. OAuth gère automatiquement le renouvellement des jetons et des informations d’identification pour l’authentification du catalogue Unity.

L’authentification OAuth pour les clients Spark externes nécessite :

• Client Spark du catalogue Unity version 0.4.1 ou ultérieure (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 ou version ultérieure
• Delta Spark 4.2.0 ou version ultérieure
• Un principal de service OAuth M2M avec les autorisations appropriées. Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.

La configuration suivante est requise pour créer, lire ou écrire dans des tables gérées par le catalogue Unity et des tables Delta externes avec Apache Spark à l’aide de l’authentification 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"

Remplacez les variables suivantes :

• <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
• <oauth-token-endpoint>: URL du point de terminaison de jeton OAuth. Pour construire cette URL :
  1. Localisez l’URL de l’espace de travail Azure Databricks.
  2. Utilisez le format : https://<workspace-url>/oidc/v1/token
• <oauth-client-id>: ID client OAuth pour votre principal de service. Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.
• <oauth-client-secret>: clé secrète client OAuth de votre principal de service. Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.

• <workspace-url> : URL Azure Databricks workspace, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.

Note

Les versions de package indiquées ci-dessus sont actuelles à compter de la dernière mise à jour de cette page. Des versions plus récentes peuvent être disponibles. Vérifiez que les versions de package sont compatibles avec votre version Spark.