Přístup k tabulkám Azure Databricks z klientů Apache Iceberg

Katalog Apache Iceberg REST umožňuje podporovaným klientům, jako jsou Apache Spark, Apache Flink a Trino, číst a zapisovat do tabulek Iceberg registrovaných v Katalogu Unity v Azure Databricks.

Úplný seznam podporovaných integrací najdete v tématu Integrace katalogu Unity.

Poznámka

Katalog Unity má také koncový bod API katalogu Iceberg REST, který je pouze pro čtení. Toto je starší koncový bod. Viz Čtení tabulek Databricks z klientů Apache Iceberg (starší verze).

Použití koncového bodu katalogu Iceberg Unity Catalog

Unity Catalog poskytuje implementaci specifikace rozhraní REST API katalogu Iceberg.

Konfigurace přístupu pomocí koncového bodu /api/2.1/unity-catalog/iceberg-rest. Podrobnosti o použití tohoto rozhraní REST API najdete ve specifikaci rozhraní REST API Iceberg .

Poznámka

Služba Azure Databricks zavedla distribuci přihlašovacích údajů pro některé klienty čtečky Icebergu. Databricks doporučuje používat předávání přihlašovacích údajů k řízení přístupu k cloudovým úložištím pro podporované systémy. Viz vydávání přihlašovacích údajů v katalogu Unity pro přístup k externím systémům a používání tabulek Iceberg s externími systémy.

Pokud pro vašeho klienta není podporováno vydávání přihlašovacích údajů, musíte nakonfigurovat, aby měl klient přístup do umístění úložiště obsahujícího soubory a metadata pro tabulku Delta nebo Iceberg. Podrobnosti o konfiguraci najdete v dokumentaci ke klientovi Icebergu.

Požadavky

Azure Databricks podporuje přístup k tabulkám prostřednictvím katalogu Iceberg REST jako součást katalogu Unity. Abyste mohli tyto koncové body používat, musíte mít ve svém pracovním prostoru povolený katalog Unity. Následující typy tabulek jsou přístupné pomocí katalogu ICEBERG REST Catalog:

Téma Čti Napiš
Spravovaný iceberg Ano Ano
Cizí ledovec Ano Ne
Spravovaná delta (s povolenými čteními Icebergu) Ano Ne
Externí Delta (s povoleným čtením Icebergu) Ano Ne

Při použití REST API katalogu Iceberg se externí tabulky Iceberg při čtení tabulek automaticky neaktualizují. Abyste obnovili, musíte spustit REFRESH FOREIGN TABLE, abyste načetli nejnovější snímek. Zprostředkování přihlašovacích údajů v tabulkách Cizí Iceberg není podporováno.

Poznámka

Tabulky Delta musíte nakonfigurovat tak, aby byly přístupné pomocí rozhraní API katalogu Iceberg REST. Viz Čtení tabulek Delta Lake s klienty Iceberg pomocí UniFormu.

Pokud chcete nakonfigurovat přístup ke čtení nebo zápisu do tabulek Azure Databricks z klientů Icebergu pomocí katalogu Iceberg REST, musíte provést následující kroky konfigurace:

Poznámka

Specifikace Iceberg neumožňuje duplicitní datové soubory v jednom snímku tabulky. Aby tomu předešel, katalog Unity blokuje externí nástroje od potvrzování duplicitních datových souborů do tabulky, jakmile jsou zjištěny.

Poznámka

Chcete-li číst tabulky, u nichž jsou použity filtry řádků nebo masky sloupců, pomocí externího klienta Iceberg, informace o požadovaných verzích klienta a jeho konfiguraci najdete v tématu Řízení přístupu na základě atributů (ABAC) napříč enginy.

Použití tabulek Iceberg s Apache Sparkem

Následující příklady ukazují, jak nakonfigurovat Apache Spark pro přístup k Azure Databricks tabulkám prostřednictvím rozhraní API katalogu ICEBERG. Azure Databricks podporuje ověřování pomocí OAuth a tokenu osobního přístupu (PAT).

Pokud chcete přistupovat k tabulkám napříč více katalogy, musíte nakonfigurovat každý katalog samostatně.

Poznámka

Do balíčků Spark musíte zahrnout soubor JAR modulu runtime pro Iceberg Spark a soubor JAR balíčku pro daný cloud. Verze modulu runtime JAR musí odpovídat vašim verzím Spark a Scala. Například pro Spark 3.5 s Scala 2.12:

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

Navíc sada specifická pro 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>

Podrobnosti najdete v dokumentaci k integraci Iceberg AWS pro Spark. Tyto soubory JAR nejsou vyžadovány při přístupu k tabulkám Iceberg z clusterů služby Azure Databricks.

Ověřování OAuth

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()

Nahraďte následující proměnné:

  • <spark-catalog-name>: Název, který chcete přiřadit katalogu ve vaší Spark seanci.
  • <uc-catalog-name>: Název katalogu Unity, který obsahuje tabulky.
  • <oauth_client_id>: ID klienta OAuth pro ověřující subjekt.
  • <oauth_client_secret>: Klientský tajný klíč OAuth pro autentizační subjekt.
  • <iceberg-version>: Verze nástroje Iceberg, která se použije, například 1.9.2.

Ověřování PAT

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()

Nahraďte následující proměnné:

Přístup k tabulkám Azure Databricks pomocí Snowflake

Snowflake nabízí dvě možnosti pro přístup k tabulkám prostřednictvím katalogu Iceberg REST: použití databází propojených s katalogem Snowflake nebo použití externích tabulek.

Pro obě možnosti nejprve nakonfigurujte integraci katalogu Snowflake. Azure Databricks podporuje následující metody ověřování pro integrace katalogu Snowflake:

  • Bearer token: Používá osobní přístupový token (PAT) Azure Databricks nebo token OAuth. Podporováno ve všech cloudech.
  • Entra služba principal OAuth (pouze Azure): Používá službu principal Microsoft Entra ID k ověření přímo vůči koncovému bodu tokenu Entra.

Další podrobnosti o možnostech ověřování Snowflake pro integrace katalogu REST najdete v dokumentaci snowflake.

Snowflake s ověřením pomocí nosného tokenu

Následující příklad nakonfiguruje integraci katalogu Snowflake pomocí nosné tokeny. Můžete použít osobní přístupový token (PAT) Azure Databricks nebo OAuth token vygenerovaný prostřednictvím service principal Azure Databricks. Podrobnosti o generování tokenů OAuth najdete v tématu Autorizace přístupu instančního objektu k Azure Databricks pomocí OAuth.

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;

Nahraďte následující proměnné:

  • <catalog-integration-name>: Název, který chcete přiřadit katalogu registrovanému ve Snowflake.
  • <uc-schema-name>: Název schématu v katalogu Unity, ke kterému potřebujete přístup.
  • <uc-catalog-name>: Název katalogu v katalogu Unity, ke kterému potřebujete získat přístup.
  • <workspace-url>: Adresa URL pracovního prostoru Azure Databricks. Například https://cust-success.cloud.databricks.com nebo https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Osobní přístupový token (PAT) pro hlavní prvek, který konfiguruje integraci.

Snowflake se služebním zástupcem Entra OAuth

Na Azure nemohou integrace katalogu Snowflake, které používají Entra založený instanční objekt služby, využívat koncový bod tokenu OIDC platformy Azure Databricks <workspace-url>/oidc/v1/token. Místo toho je nutné provést ověření přímo vůči koncovému bodu tokenu Microsoft Entra. To se liší od přístupu OAuth používaného pro ostatní klienty Icebergu (například Apache Spark) v Azure.

Poznámka

Dokumentace Snowflake může uvádět, že ID Entra není podporováno. Následující konfigurace používá Entra OAuth, který cílí na obor prostředků Azure Databricks a je podporovanou cestou ke čtení katalogu Unity z Snowflake v Azure.

Dříve začnete, ujistěte se, že máte:

Ve Snowflake spusťte následující SQL:

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;

Nahraďte následující proměnné:

  • <catalog-integration-name>: Název, který chcete přiřadit katalogu registrovanému ve Snowflake.
  • <uc-schema-name>: Název schématu v katalogu Unity, ke které potřebujete přístup.
  • <uc-catalog-name>: Název katalogu v Unity Catalog, k němuž potřebujete přístup.
  • <workspace-url>: Adresa URL pracovního prostoru Azure Databricks. Například: adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: ID vašeho tenanta Microsoft Entra.
  • <entra-client-id>: ID aplikace (klienta) služebního objektu Entra.
  • <entra-client-secret>: Tajemství klienta pro službu principal Entra.

Důležité

Obor 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default je ID aplikace Azure Databricks zaregistrované v Entra. Toto je odlišné od rozsahu all-apis, který se používá s koncovým bodem Azure Databricks OIDC. Použití nesprávného oboru je běžnou příčinou selhání ověřování při konfiguraci této integrace.

Po vytvoření integrace katalogu pomocí dokumentace Snowflake vytvořte databázi propojenou s katalogem pro přístup k vašim tabulkám.

Další informace o vytváření a správě instančních objektů Entra pro Azure Databricks najdete v tématu Ověřování pomocí instančních objektů Microsoft Entra.

Poznámka

Snowflake nepodporuje ověřování Entra pro integrace katalogu, které pro připojení k Azure Databricks používají privátní sítě (Azure Private Link). Připojení ke koncovému bodu REST katalogu Azure Databricks Iceberg musí při ověřování pomocí instančního objektu služby Entra používat veřejná síťová připojení.

Databáze propojené s katalogem

Databáze propojené s katalogem Snowflake se automaticky synchronizují s Katalogem Unity a detekují schémata a tabulky Iceberg. To eliminuje potřebu ruční aktualizace metadat.

Po konfiguraci integrace katalogu Snowflake si projděte dokumentaci Snowflake a vytvořte databázi propojenou s katalogem pro přístup k tabulkám.

Důležité

Při pokusu o zápis z Snowflake do tabulek Azure Databricks jen pro čtení může dojít k chybám. Informace o podporovaných operacích najdete v dokumentaci ke Snowflake .

Externí tabulky

Případně můžete po vytvoření integrace katalogu Snowflake vytvořit externí tabulky. Tento přístup vyžaduje ruční aktualizaci metadat, aby se zobrazily aktualizace.

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

Použití tabulek Azure Databricks s PyIcebergem

Pokud chcete pro přístup k tabulkám Azure Databricks použít PyIceberg, musíte PyIceberg nainstalovat s požadovanými závislostmi. PyIceberg vyžaduje pyarrow pro operace tabulek, jako je čtení dat a kontrola metadat tabulek. Nainstalujte PyIceberg navíc pyarrow :

pip install "pyiceberg[pyarrow]"

Poznámka

Pokud nenainstalujete pyarrowoperace, jako je popis nebo čtení tabulek, selžou. Úplný seznam volitelných závislostí najdete v dokumentaci k PyIcebergu.

Následuje příklad nastavení konfigurace, které PyIcebergu umožní přístup k tabulkám Azure Databricks připojením ke katalogu Iceberg REST v Katalogu Unity:

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

Nahraďte následující proměnné:

  • <uc-catalog-name>: Název katalogu v katalogu Unity, ke kterému potřebujete získat přístup.
  • <token>: Osobní přístupový token (PAT) pro hlavní prvek, který konfiguruje integraci.

Viz dokumentace ke konfiguraci katalogu REST PyIceberg.

Příklad curl pomocí rozhraní REST API

Následující curl příklad načte tabulku pomocí rozhraní 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>

Odpověď vypadá takto:

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

Poznámka

Pole expires-at-ms označuje, kdy vyprší platnost přihlašovacích údajů. Výchozí doba vypršení platnosti je jedna hodina. Pokud chcete dosáhnout lepšího výkonu, požádejte klienta o uložení přihlašovacích údajů do mezipaměti, dokud nevyprší platnost, než si vyžádá nové.

  • Last updated on