Toegang tot Azure Databricks-tabellen vanuit Apache Iceberg-clients

Met de Apache Iceberg REST-catalogus kunnen ondersteunde clients, zoals Apache Spark, Apache Flink en Trino, Iceberg-tabellen die zijn geregistreerd bij Unity Catalog in Azure Databricks lezen en beschrijven.

Zie Unity Catalog-integraties voor een volledige lijst met ondersteunde integraties.

Notitie

Unity Catalog biedt ook een alleen-lezen Iceberg REST Catalog API-eindpunt. Dit is een verouderd eindpunt. Zie Databricks-tabellen lezen van Apache Iceberg-clients (verouderd).

Het eindpunt van de Unity Catalog Iceberg-catalogus gebruiken

Unity Catalog biedt een implementatie van de ICEBERG REST Catalog API-specificatie.

Toegang configureren met behulp van het eindpunt /api/2.1/unity-catalog/iceberg-rest. Zie de Iceberg REST API-specificatie voor meer informatie over het gebruik van deze REST API.

Notitie

Azure Databricks heeft referentieverkoop geïntroduceerd voor sommige Iceberg-lezersclients. Databricks raadt het gebruik van referentieverkoop aan om de toegang tot cloudopslaglocaties voor ondersteunde systemen te beheren. Zie Unity Catalog-credentialdistributie voor externe systeemtoegang en Iceberg-tabellen openen met behulp van externe systemen.

Als het verstrekken van referenties niet wordt ondersteund voor uw client, moet u de toegang van de client configureren tot de opslaglocatie met de bestanden en metagegevens voor de Delta- of Iceberg-tabel. Raadpleeg de documentatie voor uw Iceberg-client voor configuratiedetails.

Eisen

Azure Databricks biedt ondersteuning voor iceberg REST-catalogustoegang tot tabellen als onderdeel van Unity Catalog. U moet Unity Catalog in uw werkruimte hebben ingeschakeld om deze eindpunten te kunnen gebruiken. De volgende tabeltypen zijn toegankelijk met behulp van de Iceberg REST Catalog:

Onderwerp Lezen Schrijven
Gereguleerde ijsberg Ja Ja
Buitenlandse IJsberg Ja Nee.
Beheerde Delta (met Iceberg-leesbewerkingen ingeschakeld) Ja Nee.
Externe delta (met Iceberg-lezen ingeschakeld) Ja Nee.

Buitenlandse Iceberg-tabellen worden niet automatisch vernieuwd wanneer u de ICEBERG REST Catalog-API gebruikt om tabellen te lezen. Om te vernieuwen, moet u REFRESH FOREIGN TABLE runnen om de meest recente momentopname te lezen. Referentieverkoop op Buitenlandse Iceberg-tabellen wordt niet ondersteund.

Notitie

U moet Delta-tabellen configureren om toegankelijk te zijn met behulp van de ICEBERG REST Catalog-API. Zie Delta Lake-tabellen lezen met Iceberg-clients met UniForm.

U moet de volgende configuratiestappen uitvoeren om de toegang te configureren voor lezen van of schrijven naar Azure Databricks-tabellen van Iceberg-clients met behulp van de Iceberg REST-catalogus:

Notitie

De Iceberg-specificatie staat geen dubbele gegevensbestanden toe in één momentopname van een tabel. Om dit te voorkomen, blokkeert Unity Catalog bij detectie dat externe engines dubbele gegevensbestanden doorvoeren in de tabel.

Notitie

Als u tabellen wilt lezen waaraan vanuit een externe Iceberg-client rijfilters of kolommaskers zijn gekoppeld, raadpleegt u Kenmerkgebaseerde toegangscontrole (ABAC) voor de vereiste clientversies en configuratie.

Iceberg-tabellen gebruiken met Apache Spark

In de volgende voorbeelden ziet u hoe u Apache Spark configureert voor toegang tot Azure Databricks tabellen via de ICEBERG REST Catalog-API. Azure Databricks ondersteunt OAuth- en persoonlijke toegangstokenverificatie (PAT).

Als u toegang wilt krijgen tot tabellen in meerdere catalogi, moet u elke catalogus afzonderlijk configureren.

Notitie

U moet het JAR-bestand van de Iceberg Spark-runtime en de cloudspecifieke bundel-JAR in uw Spark-pakketten opnemen. De versie van de runtime-JAR moet overeenkomen met uw Spark- en Scala-versies. Bijvoorbeeld voor Spark 3.5 met Scala 2.12:

  • org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>

Daarnaast de bundel specifiek voor de cloud:

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

Zie de documentatie voor de Iceberg AWS-integratie voor Sparkvoor meer informatie. Deze JAR's zijn niet vereist bij het openen van Iceberg-tabellen vanuit Azure Databricks clusters.

OAuth-verificatie

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.rest.auth.type=oauth2" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri=https://<workspace-url>/oidc/v1/token" \
  --conf "spark.sql.catalog.<spark-catalog-name>.credential=<oauth_client_id>:<oauth_client_secret>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.scope=all-apis"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.rest.auth.type", "oauth2") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri", "https://<workspace-url>/oidc/v1/token") \
    .config("spark.sql.catalog.<spark-catalog-name>.credential", "<oauth_client_id>:<oauth_client_secret>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .config("spark.sql.catalog.<spark-catalog-name>.scope", "all-apis") \
    .getOrCreate()

Vervang de volgende variabelen:

  • <spark-catalog-name>: de naam die u wilt toewijzen aan de catalogus in uw Spark-sessie.
  • <uc-catalog-name>: de naam van de catalogus in Unity Catalog die uw tabellen bevat.
  • <oauth_client_id>: OAuth-client-ID voor de authenticatiegebruiker.
  • <oauth_client_secret>: OAuth-clientgeheim voor de authenticatie-principal.
  • <iceberg-version>: De Iceberg-versie die moet worden gebruikt, bijvoorbeeld 1.9.2.
  • <workspace-url>: de URL van de Azure Databricks-werkruimte. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.

PAT-verificatie

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.token=<token>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.token", "<token>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .getOrCreate()

Vervang de volgende variabelen:

  • <spark-catalog-name>: de naam die u wilt toewijzen aan de catalogus in uw Spark-sessie.
  • <uc-catalog-name>: de naam van de catalogus in Unity Catalog die uw tabellen bevat.
  • <token>: Een persoonlijk toegangstoken (PAT) voor de verificatie-principal. Zie Verifiëren met persoonlijke toegangstokens van Azure Databricks (verouderd).
  • <iceberg-version>: De Iceberg-versie die moet worden gebruikt, bijvoorbeeld 1.9.2.
  • <workspace-url>: de URL van de Azure Databricks-werkruimte. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.

Toegang tot Azure Databricks-tabellen met Snowflake

Snowflake biedt twee opties voor toegang tot tabellen via de Iceberg REST-catalogus: met behulp van de catalogus gekoppelde databases van Snowflake of met behulp van externe tabellen.

Configureer voor beide opties eerst een Snowflake-catalogusintegratie. Azure Databricks ondersteunt de volgende verificatiemethoden voor Snowflake-catalogusintegraties:

  • Bearer-token: maakt gebruik van een persoonlijk toegangstoken (PAT) of OAuth-token van Azure Databricks. Ondersteund op alle clouds.
  • Entra-service-principal OAuth (alleen Azure): maakt gebruik van een Microsoft Entra ID-service-principal om rechtstreeks te verifiëren bij het Entra-tokeneindpunt.

Zie de documentatie van Snowflake voor meer informatie over snowflake-verificatieopties voor REST-catalogusintegraties.

Snowflake met bearer-tokenverificatie

In het volgende voorbeeld wordt een Snowflake-catalogusintegratie geconfigureerd met behulp van een bearer-token. U kunt een persoonlijk toegangstoken (PAT) van Azure Databricks of een OAuth-token gebruiken dat is gegenereerd op basis van een Azure Databricks-service-principal. Zie Service-principaltoegang tot Azure Databricks autoriseren met OAuth voor meer informatie over het genereren van OAuth-tokens.

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;

Vervang de volgende variabelen:

  • <catalog-integration-name>: de naam die u wilt toewijzen aan de catalogus die is geregistreerd bij Snowflake.
  • <uc-schema-name>: De naam van het schema in Unity Catalog waartoe u toegang moet hebben.
  • <uc-catalog-name>: De naam van de catalogus in Unity Catalog waartoe u toegang moet hebben.
  • <workspace-url>: de URL van de Azure Databricks-werkruimte. Een voorbeeld hiervan is https://cust-success.cloud.databricks.com of https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Een persoonlijk toegangstoken (PAT) voor de principal die de integratie configureert.

Snowflake met Entra-service-principal OAuth

In Azure kunnen Snowflake-catalogusintegraties die gebruikmaken van een door Entra ondersteunde service-principal, het Azure Databricks OIDC-tokeneindpunt (<workspace-url>/oidc/v1/token) niet gebruiken. In plaats daarvan moet u zich rechtstreeks verifiëren bij het Microsoft Entra-tokeneindpunt. Dit verschilt van de OAuth-benadering die wordt gebruikt voor andere Iceberg-clients (zoals Apache Spark) in Azure.

Notitie

De documentatie van Snowflake kan erop wijzen dat Entra-id niet wordt ondersteund. De onderstaande configuratie maakt gebruik van Entra OAuth gericht op het Azure Databricks-resourcebereik en is het ondersteunde pad voor het lezen van Unity Catalog vanuit Snowflake in Azure.

Zorg ervoor dat u voordat u begint de volgende zaken paraat hebt:

  • Een Entra-service-principal met de EXTERNAL USE SCHEMA bevoegdheden die zijn verleend aan het doelschema in Unity Catalog. Zie Unity Catalog-rechten aan een principal verlenen.
  • De client-id en het clientgeheim van de service-principal.
  • Uw Azure-tenant-id.

Voer de volgende SQL uit in 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;

Vervang de volgende variabelen:

  • <catalog-integration-name>: de naam die u wilt toewijzen aan de catalogus die is geregistreerd bij Snowflake.
  • <uc-schema-name>: de naam van het schema in Unity Catalog die u moet openen.
  • <uc-catalog-name>: de naam van de catalogus in Unity Catalog die u moet openen.
  • <workspace-url>: de URL van de Azure Databricks-werkruimte. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: uw Microsoft Entra-tenant-ID.
  • <entra-client-id>: De applicatie-ID (client) van de Entra-service-principal.
  • <entra-client-secret>: Een clientgeheim voor de Entra-service-principal.

Belangrijk

Het bereik 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default is de Azure Databricks-toepassings-id die is geregistreerd in Entra. Dit verschilt van het all-apis bereik dat wordt gebruikt met het Azure Databricks OIDC-eindpunt. Het gebruik van het verkeerde bereik is een veelvoorkomende oorzaak van verificatiefouten bij het configureren van deze integratie.

Nadat u de catalogusintegratie hebt gemaakt, volgt u de Snowflake-documentatie om een aan een catalogus gekoppelde database te maken voor toegang tot uw tabellen.

Zie Verifiëren met Microsoft Entra-service-principals voor Meer informatie over het maken en beheren van Entra-service-principals voor Azure Databricks.

Notitie

Snowflake biedt geen ondersteuning voor Entra-verificatie voor catalogusintegraties die gebruikmaken van privénetwerken (Azure Private Link) om verbinding te maken met Azure Databricks. De verbinding met het Azure Databricks Iceberg REST-cataloguseindpunt moet openbare netwerken gebruiken bij verificatie met een Entra-service-principal.

Gekoppelde catalogusdatabases

De aan de catalogus gekoppelde databases van Snowflake worden automatisch gesynchroniseerd met Unity Catalog om schema's en Iceberg-tabellen te detecteren. Hierdoor hoeft u geen handmatige metagegevens te vernieuwen.

Nadat u de integratie van een Snowflake-catalogus hebt geconfigureerd, raadpleegt u de Snowflake-documentatie om een database te maken die is gekoppeld aan een catalogus voor toegang tot uw tabellen.

Belangrijk

Wanneer u probeert gegevens vanuit Snowflake te schrijven naar alleen-lezen Azure Databricks tabellen, kan dit leiden tot fouten. Raadpleeg de Snowflake-documentatie voor ondersteunde bewerkingen.

Externe tabellen

U kunt ook externe tabellen maken nadat u een Snowflake-catalogusintegratie hebt gemaakt. Voor deze aanpak moeten metagegevens handmatig worden vernieuwd om updates te kunnen zien.

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

Azure Databricks-tabellen gebruiken met PyIceberg

Als u PyIceberg wilt gebruiken voor toegang tot Azure Databricks-tabellen, moet u PyIceberg installeren met de vereiste afhankelijkheden. PyIceberg vereist pyarrow voor tabelbewerkingen, zoals het lezen van gegevens en het inspecteren van metagegevens van tabellen. Installeer PyIceberg met de pyarrow toevoeging:

pip install "pyiceberg[pyarrow]"

Notitie

Als u de installatie niet uitvoert pyarrow, mislukken bewerkingen zoals het beschrijven of lezen van tabellen. Zie de PyIceberg-documentatie voor de volledige lijst met optionele afhankelijkheden.

Hier volgt een voorbeeld van de configuratie-instellingen waarmee PyIceberg toegang heeft tot Azure Databricks-tabellen door verbinding te maken met de Iceberg REST Catalog in Unity Catalog:

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

Vervang de volgende variabelen:

  • <workspace-url>: de URL van de Azure Databricks-werkruimte. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.
  • <uc-catalog-name>: De naam van de catalogus in Unity Catalog waartoe u toegang moet hebben.
  • <token>: Een persoonlijk toegangstoken (PAT) voor de principal die de integratie configureert.

Raadpleeg de documentatie voor de configuratie van de PyIceberg REST-catalogus.

Voorbeeld van REST API curl

In het volgende curl voorbeeld wordt een tabel geladen met behulp van de REST API:

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>

Het antwoord ziet er als volgt uit:

{
  "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>"
  }
}

Notitie

Het expires-at-ms veld geeft aan wanneer de referenties verlopen. De standaardverlooptijd is één uur. Voor betere prestaties moet de client de referenties in de cache opslaan totdat ze verlopen voordat ze nieuwe aanvragen.

  • Last updated on