Partage via

Accéder aux tables Azure Databricks à partir de clients Apache Iceberg

Importante

L’API de catalogue REST Apache Iceberg du catalogue Unity est disponible en préversion publique dans Databricks Runtime 16.4 LTS et versions ultérieures. Ce point de terminaison est recommandé pour lire et écrire dans des tables à partir de clients Iceberg.

Unity Catalog dispose également d'un point de terminaison d'API de catalogue REST Iceberg en lecture seule. Il s’agit d’un point de terminaison hérité. Consultez Lire des tables Databricks depuis des clients Apache Iceberg (legacy).

Le catalogue REST Apache Iceberg permet aux clients pris en charge, tels qu’Apache Spark, Apache Flink et Trino, de lire et d’écrire dans des tables Iceberg inscrites dans le catalogue Unity sur Azure Databricks.

Pour obtenir la liste complète des intégrations prises en charge, consultez intégrations du catalogue Unity.

Utiliser le point de terminaison du catalogue Iceberg d’Unity Catalog

Unity Catalog fournit une implémentation de la spécification de l’API de catalogue REST Iceberg.

Configurez l’accès à l’aide du point de terminaison /api/2.1/unity-catalog/iceberg-rest. Consultez la spécification de l’API REST Iceberg pour plus d’informations sur l’utilisation de cette API REST.

Importante

L’URL de l’espace de travail utilisée pour le point de terminaison du catalogue REST Iceberg doit inclure l’ID de l’espace de travail. Sans l’ID d’espace de travail, les demandes d’API peuvent renvoyer une redirection vers une 303 page de connexion au lieu de la réponse attendue.

Pour rechercher l’URL et l’ID de votre espace de travail, consultez les noms d’instances d’espace de travail, les URL et les ID.

Remarque

Azure Databricks a introduit la vente d’informations d’identification pour certains clients de lecteur Iceberg. Databricks recommande d’utiliser la distribution d’informations d’identification pour contrôler l’accès aux emplacements de stockage cloud pour les systèmes pris en charge. Consultez Fourniture des informations d’identification Unity Catalog pour l’accès d’un système externe.

Si la distribution des informations d’identification n’est pas prise en charge pour votre client, vous devez configurer l’accès du client à l’emplacement de stockage contenant les fichiers et les métadonnées de la table Delta ou Iceberg. Pour plus d’informations sur la configuration, reportez-vous à la documentation de votre client Iceberg.

Spécifications

Azure Databricks prend en charge l’accès au catalogue REST d'Iceberg pour les tables dans le cadre du Unity Catalog. Le catalogue Unity doit être activé dans votre espace de travail pour utiliser ces points de terminaison. Les types de tableau suivants sont accessibles à l’aide du catalogue REST Iceberg :

Sujet Lire Écrire
Table Iceberg gérée Oui Oui
Table Iceberg étrangère Oui Non
Delta géré (avec les lectures Iceberg activées) Oui Non
Delta externe (avec Iceberg Reads activés) Oui Non

Les tables iceberg étrangères ne sont pas automatiquement actualisées lors de l’utilisation de l’API du catalogue REST Iceberg pour lire les tables. Pour actualiser, vous devez exécuter REFRESH FOREIGN TABLE pour lire la dernière capture instantanée. La distribution d’informations d’identification sur les tables Iceberg étrangères n’est pas prise en charge.

Remarque

Vous devez configurer des tables Delta pour qu’elles soient accessibles à l’aide de l’API du catalogue REST Iceberg. Consultez Lire des tables Delta avec des clients Iceberg.

Vous devez suivre les étapes de configuration suivantes pour configurer l’accès en lecture ou en écriture dans des tables Azure Databricks à partir de clients Iceberg à l’aide du catalogue REST Iceberg :

Remarque

La spécification Iceberg n’autorise pas les fichiers de données en doublons dans un instantané de table unique. Pour éviter cela, lorsqu’il est détecté, Unity Catalog empêche les moteurs externes de valider des fichiers de données en double dans la table.

Utiliser des tables Iceberg avec Apache Spark

Voici un exemple de configuration d’Apache Spark pour accéder aux tables Azure Databricks via l’API du catalogue REST Iceberg à l’aide de l’authentification OAuth :

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

Remplacez les variables suivantes :

  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
  • <spark-catalog-name>: nom que vous souhaitez affecter au catalogue dans votre session Spark.
  • <oauth_client_id> : ID client OAuth pour le principal d’authentification.
  • <oauth_client_secret> : secret client OAuth pour le principal d’authentification.
  • <workspace-url>: URL de l’espace de travail Azure Databricks, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.

Avec ces configurations, vous pouvez interroger des tables dans le catalogue Unity à l’aide d’Apache Spark. Pour accéder aux tables sur plusieurs catalogues, vous devez configurer chaque catalogue séparément.

Lorsque vous interrogez des tables dans le catalogue Unity à l’aide de configurations Spark, gardez à l’esprit ce qui suit :

  • Vous avez besoin de "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" uniquement si vous exécutez des procédures stockées spécifiques à Iceberg.

  • Azure Databricks utilise le stockage d’objets cloud pour toutes les tables. Vous devez ajouter le fichier JAR iceberg-spark-runtime en tant que packages Spark :

    • AWS : org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure : org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • BPC : org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Pour plus d’informations, consultez la documentation relative à l’intégration d’Iceberg AWS pour Spark.

    Remarque

    Ces configurations ne sont pas requises lors de l’accès aux tables Iceberg à partir d’Azure Databricks. Le chargement de JARs Iceberg externes sur des clusters Azure Databricks n’est pas pris en charge.

Accéder aux tables Azure Databricks avec Snowflake

Snowflake propose deux options d’accès aux tables via le catalogue REST Iceberg : à l’aide des bases de données liées au catalogue de Snowflake ou à l’aide de tables externes.

Pour les deux options, commencez par configurer une intégration de catalogue Snowflake :

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Remplacez les variables suivantes :

  • <catalog-integration-name>: Le nom que vous souhaitez attribuer au catalogue enregistré auprès de Snowflake.
  • <uc-schema-name>: nom du schéma dans le catalogue Unity auquel vous devez accéder.
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
  • <workspace-url>: URL de l’espace de travail Azure Databricks, y compris l’ID de l’espace de travail. Par exemple, https://cust-success.cloud.databricks.com/?o=6280049833385130 ou https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: jeton d’accès personnel (PAT) pour la personne principale configurant l’intégration.

Snowflake avec le service principal Entra OAuth

Sur Azure, les intégrations de catalogue Snowflake qui utilisent un principal de service pris en charge par Entra ne peuvent pas utiliser le point de terminaison de jeton OIDC Azure Databricks (<workspace-url>/oidc/v1/token). Au lieu de cela, vous devez vous authentifier directement contre l'endpoint de jeton Microsoft Entra. Cela diffère de l’approche OAuth utilisée pour d’autres clients Iceberg (tels qu’Apache Spark) sur Azure.

Remarque

La documentation de Snowflake peut indiquer que l’ID Entra n’est pas pris en charge. La configuration ci-dessous utilise Entra OAuth pour accéder à l'étendue de ressources Azure Databricks, et constitue la méthode prise en charge pour lire Unity Catalog depuis Snowflake sur Azure.

Avant de commencer, assurez-vous d’avoir :

Exécutez le code SQL suivant dans Snowflake :

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

Remplacez les variables suivantes :

  • <catalog-integration-name>: Le nom que vous souhaitez attribuer au catalogue enregistré auprès de Snowflake.
  • <uc-schema-name>: nom du schéma dans le catalogue Unity auquel vous devez accéder.
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
  • <workspace-url>: URL de l’espace de travail Azure Databricks, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id> : Votre identifiant de tenant Microsoft Entra.
  • <entra-client-id>: ID d’application (client) du principal du service Entra.
  • <entra-client-secret>: secret client pour le principal du service Entra.

Importante

L’étendue 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default est l’ID d'application Azure Databricks enregistré dans Entra. Cela est distinct de l’étendue all-apis utilisée avec le point de terminaison OIDC Azure Databricks. L’utilisation de l’étendue incorrecte est une cause courante des échecs d’authentification lors de la configuration de cette intégration.

Après avoir créé l’intégration du catalogue, suivez la documentation Snowflake pour créer une base de données liée au catalogue pour accéder à vos tables.

Pour plus d’informations sur la création et la gestion des principaux de service Entra pour Azure Databricks, consultez Authentifier auprès des principaux de service Microsoft Entra.

Remarque

Snowflake ne prend pas en charge l’authentification Entra pour les intégrations de catalogue qui utilisent la mise en réseau privée (Azure Private Link) pour se connecter à Azure Databricks. La connexion au point de terminaison du catalogue REST d’Azure Databricks Iceberg doit utiliser la mise en réseau publique lors de l’authentification auprès d’un principal de service Entra.

Bases de données liées au catalogue

Les bases de données liées au catalogue de Snowflake sont automatiquement synchronisées avec Unity Catalog pour détecter les schémas et les tables Iceberg. Cela élimine la nécessité d’actualiser manuellement les métadonnées.

Après avoir configuré une intégration de catalogue Snowflake, reportez-vous à la documentation Snowflake pour créer une base de données liée au catalogue pour accéder à vos tables.

Importante

La tentative d’écriture à partir de Snowflake dans des tables Azure Databricks en lecture seule peut entraîner des erreurs. Reportez-vous à la documentation Snowflake pour les opérations prises en charge.

Tables externes

Vous pouvez également créer des tables externes après avoir créé une intégration de catalogue Snowflake. Cette approche nécessite l’actualisation manuelle des métadonnées pour afficher les mises à jour.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Utiliser des tables Azure Databricks avec PyIceberg

Pour utiliser PyIceberg pour accéder aux tables Azure Databricks, vous devez installer PyIceberg avec les dépendances requises. PyIceberg nécessite pyarrow des opérations de table telles que la lecture de données et l’inspection des métadonnées de table. Installez PyIceberg avec l’option pyarrow supplémentaire :

pip install "pyiceberg[pyarrow]"

Remarque

Si vous n’installez pyarrowpas, les opérations telles que la description ou la lecture des tables échouent. Pour obtenir la liste complète des dépendances facultatives, consultez la documentation PyIceberg.

Voici un exemple des paramètres de configuration permettant à PyIceberg d’accéder aux tables Azure Databricks en se connectant au catalogue REST Iceberg dans le catalogue Unity :

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Remplacez les variables suivantes :

  • <workspace-url>: URL de l’espace de travail Azure Databricks, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
  • <token>: jeton d’accès personnel (PAT) pour le principal configurant l’intégration.

Consultez la documentation relative à la configuration du catalogue REST PyIceberg.

Exemple curl de l’API REST

L’exemple suivant curl charge une table à l’aide de l’API REST :

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

La réponse ressemble à ceci :

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Remarque

Le expires-at-ms champ indique à quel moment les informations d’identification expirent. La durée d’expiration par défaut est d’une heure. Pour de meilleures performances, le client met en cache les informations d’identification jusqu’à ce qu’elles expirent avant de demander de nouvelles informations.

  • Last updated on