Apache Iceberg istemcilerinden Azure Databricks tablolarına erişme

Apache Iceberg REST kataloğu Apache Spark, Apache Flink ve Trino gibi desteklenen istemcilerin Azure Databricks'te Unity Kataloğu'na kayıtlı Iceberg tablolarından okumasına ve bu tablolara yazmasına olanak tanır.

Desteklenen tümleştirmelerin tam listesi için bkz. Unity Kataloğu tümleştirmeleri.

Not

Unity Kataloğu'nun salt okunur bir Iceberg REST Kataloğu API'si uç noktası da vardır. Bu eski bir uç noktadır. Bkz. Apache Iceberg istemcilerinden Databricks tablolarını okuma (eski).

Unity Kataloğu Iceberg katalog uç noktasını kullanma

Unity Kataloğu, Iceberg REST kataloğu API belirtiminin bir uygulamasını sağlar.

uç nokta /api/2.1/unity-catalog/iceberg-restkullanarak erişimi yapılandırın. Bu REST API'yi kullanma hakkında ayrıntılı bilgi için bkz. Iceberg REST API belirtimi.

Not

Azure Databricks, bazı Iceberg okuyucu müşterileri için kimlik bilgisi verme özelliğini tanıttı. Databricks, desteklenen sistemler için bulut depolama konumlarına erişimi kontrol etmek için kimlik bilgisi yönetiminin kullanılmasını önerir. Bkz. Dış sistem erişimi için Unity Catalog kimlik bilgisi sağlama ve dış sistemleri kullanarak Iceberg tablolarına erişme.

Kimlik bilgisi sağlama istemciniz için desteklenmiyorsa, delta veya Iceberg tablosu için dosyaları ve meta verileri içeren depolama konumuna istemciden erişimi yapılandırmanız gerekir. Yapılandırma ayrıntıları için Iceberg istemcinizin belgelerine bakın.

Gereksinimler

Azure Databricks, Unity Kataloğu'nun bir parçası olarak Iceberg REST kataloğunun tablolara erişimini destekler. Bu uç noktaları kullanmak için çalışma alanınızda Unity Kataloğu'nu etkinleştirmiş olmanız gerekir. Aşağıdaki tablo türlerine Iceberg REST Kataloğu kullanılarak erişilebilir:

Konu Okumak Yazmak
Yönetilen Buzdağı Evet Evet
Yabancı Buzdağı Evet Hayı
Yönetilen Delta (Iceberg okuma özelliği etkinleştirildiğinde) Evet Hayı
Dış Delta (Iceberg okumaları etkin olduğunda) Evet Hayı

Yabancı Iceberg tabloları, Iceberg REST Katalog API'si kullanılarak tabloları okurken otomatik olarak yenilenmez. Yenilemek için en son anlık görüntüyü okumak için komutunu çalıştırmanız REFRESH FOREIGN TABLE gerekir. Yabancı Iceberg tablolarında kimlik bilgisi dağıtımı desteklenmiyor.

Not

Delta tablolarını Iceberg REST Katalog API'sini kullanarak erişilebilir olacak şekilde yapılandırmanız gerekir. Bkz. Iceberg istemcileri ile Delta tablolarını okuma.

Iceberg REST kataloğunu kullanarak Iceberg istemcilerinden Azure Databricks tablolarından okuma veya yazma erişimini yapılandırmak için aşağıdaki yapılandırma adımlarını tamamlamanız gerekir:

Not

Iceberg belirtimi tek bir tablo anlık görüntüsünde yinelenen veri dosyalarına izin vermez. Bunu önlemek için, Unity Kataloğu algılandığında dış altyapıların tabloya yinelenen veri dosyaları işlemesini engeller.

Apache Spark ile Iceberg tablolarını kullanma

Aşağıda, Apache Spark'ın OAuth kimlik doğrulamasını kullanarak Iceberg REST Katalog API'sini kullanarak Azure Databricks tablolarına erişecek şekilde nasıl yapılandırılmaya yönelik bir örnek verilmiştir:

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

Aşağıdaki değişkenleri değiştirin:

  • <uc-catalog-name>: Unity Kataloğu'nda tablolarınızı içeren kataloğun adı.
  • <spark-catalog-name>: Spark oturumunuzda kataloğu atamak istediğiniz ad.
  • <oauth_client_id>: Kimlik doğrulama sorumlusu için OAuth istemci kimliği.
  • <oauth_client_secret>: Kimlik doğrulayıcı için OAuth istemci gizli anahtarı.

Bu yapılandırmalarla, Apache Spark kullanarak Unity Kataloğu'ndaki tabloları sorgulayabilirsiniz. Birden çok katalogda tablolara erişmek için her kataloğu ayrı ayrı yapılandırmanız gerekir.

Spark yapılandırmalarını kullanarak Unity Kataloğu'nda tabloları sorgularken aşağıdakileri göz önünde bulundurun:

  • ""spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" yalnızca Iceberg'e özgü saklı yordamlarıçalıştırıyorsanız gereklidir."

  • Azure Databricks, tüm tablolar için bulut nesne depolama kullanır. Iceberg-spark-runtime JAR dosyasını Spark paketleri olarak eklemeniz gerekir:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Gök mavisi: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Ayrıntılar için Iceberg AWS tümleştirmesi belgelerine , Spark'e bakın.

    Not

    Azure Databricks'ten Iceberg tablolarına erişirken bu yapılandırmalar gerekli değildir. Dış Iceberg JAR'lerinin Azure Databricks kümelerine yüklenmesi desteklenmez.

Snowflake ile Azure Databricks tablolarına erişme

Snowflake, Iceberg REST kataloğu aracılığıyla tablolara erişmek için iki seçenek sunar: Snowflake'in katalog bağlantılı veritabanlarını veya dış tabloları kullanma.

Her iki seçenek için önce bir Snowflake kataloğu tümleştirmesi yapılandırın. Azure Databricks, Snowflake kataloğu tümleştirmeleri için aşağıdaki kimlik doğrulama yöntemlerini destekler:

  • Bearer Token: Azure Databricks kişisel erişim belirteci (PAT) veya OAuth belirteci kullanır. Tüm bulutlarda desteklenir.
  • Entra hizmet sorumlusu OAuth (yalnızca Azure):Doğrudan Entra belirteci uç noktasında kimlik doğrulaması yapmak için Microsoft Entra ID hizmet sorumlusunu kullanır.

REST kataloğu tümleştirmeleri için Snowflake kimlik doğrulama seçenekleri hakkında daha fazla bilgi için Snowflake belgelerine bakın.

Snowflake ile bearer token (taşıyıcı belirteç) kimlik doğrulaması

Aşağıdaki örnekte taşıyıcı belirteci kullanarak Snowflake kataloğu tümleştirmesi yapılandırılır. Azure Databricks kişisel erişim belirteci (PAT) veya Azure Databricks hizmet sorumlusundan oluşturulan bir OAuth belirteci kullanabilirsiniz. OAuth belirteçleri oluşturma hakkında ayrıntılı bilgi için bkz. OAuth ile Azure Databricks'e hizmet sorumlusu erişimi yetkilendirme.

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;

Aşağıdaki değişkenleri değiştirin:

  • <catalog-integration-name>: Snowflake'e kayıtlı kataloğu atamak istediğiniz ad.
  • <uc-schema-name>: Unity Kataloğu'nda erişmeniz gereken şemanın adı.
  • <uc-catalog-name>: Unity Kataloğu'nda erişmeniz gereken kataloğun adı.
  • <workspace-url>: Azure Databricks çalışma alanı URL'si. Örneğin, https://cust-success.cloud.databricks.com veya https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Tümleştirmeyi yapılandıran sorumlu için kişisel erişim belirteci (PAT).

Entra hizmet sorumlusu OAuth ile Snowflake

Azure'da, Entra destekli hizmet sorumlusu kullanan Snowflake kataloğu tümleştirmeleri Azure Databricks OIDC belirteç uç noktasını (<workspace-url>/oidc/v1/token ) kullanamaz. Bunun yerine, doğrudan Microsoft Entra belirteci uç noktasında kimlik doğrulaması yapmanız gerekir. Bu, Azure'da diğer Iceberg istemcileri (Apache Spark gibi) için kullanılan OAuth yaklaşımından farklıdır.

Not

Snowflake'in belgeleri, Entra Kimliğinin desteklenmediğini gösterebilir. Azure Databricks kaynak kapsamını hedef alan Entra OAuth'un kullanıldığı aşağıdaki yapılandırma, Azure üzerinde Snowflake'ten Unity Kataloğu'nu okumak için desteklenen yoldur.

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

  • Unity Kataloğu'ndaki hedef şemada EXTERNAL USE SCHEMA ayrıcalığı verilmiş bir Entra hizmet ilkesi. Bkz. Bir özneye Unity Catalog ayrıcalıkları verme.
  • Hizmet sorumlusunun istemci kimliği ve istemci gizli dizisi.
  • Azure kiracı kimliğiniz.

Snowflake'de aşağıdaki SQL'i çalıştırın:

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;

Aşağıdaki değişkenleri değiştirin:

  • <catalog-integration-name>: Snowflake'e kayıtlı kataloğu atamak istediğiniz ad.
  • <uc-schema-name>: Erişmeniz gereken Unity Kataloğu'ndaki şemanın adı.
  • <uc-catalog-name>: Erişmeniz gereken Unity Kataloğu'ndaki kataloğun adı.
  • <workspace-url>: Azure Databricks çalışma alanı URL'si. Örneğin, adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: Microsoft Entra Tenant ID'niz.
  • <entra-client-id>: Entra hizmet sorumlusunun uygulama (istemci) kimliği.
  • <entra-client-secret>: Entra hizmet sorumlusu için bir istemci sırrı.

Önemli

Kapsam 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default , Entra'da kayıtlı Azure Databricks uygulama kimliğidir. Bu, Azure Databricks OIDC uç noktasıyla kullanılan kapsamdan farklıdır all-apis . Yanlış kapsamın kullanılması, bu tümleştirmeyi yapılandırırken karşılaşılan kimlik doğrulama hatalarının yaygın bir nedenidir.

Katalog tümleştirmesini oluşturduktan sonra, tablolarınıza erişmek üzere katalog bağlantılı veritabanı oluşturmak için Snowflake belgelerini izleyin.

Azure Databricks için Entra hizmet sorumlularını oluşturma ve yönetme hakkında daha fazla bilgi için bkz. Microsoft Entra hizmet sorumlularıyla kimlik doğrulaması yapma.

Not

Snowflake, Azure Databricks'e bağlanmak için özel ağ (Azure Özel Bağlantı) kullanan katalog tümleştirmeleri için Entra kimlik doğrulamasını desteklemez. Azure Databricks Iceberg REST katalog uç noktası bağlantısı, Entra hizmet sorumlusuyla kimlik doğrulaması yaparken genel ağ kullanmalıdır.

Katalog bağlantılı veritabanları

Snowflake'in katalog bağlantılı veritabanları, şemaları ve Iceberg tablolarını algılamak için Unity Kataloğu ile otomatik olarak eşitlenir. Bu, el ile meta veri yenileme gereksinimini ortadan kaldırır.

Snowflake katalog tümleştirmesini yapılandırdıktan sonra, tablolarınıza erişmek üzere katalog bağlantılı veritabanı oluşturmak için Snowflake belgelerine bakın .

Önemli

Snowflake'ten salt okunur Azure Databricks tablolarına yazma girişimi hatalara neden olabilir. Desteklenen işlemler için Snowflake belgelerine bakın .

Dış tablolar

Alternatif olarak, Snowflake katalog tümleştirmesi oluşturduktan sonra dış tablolar oluşturabilirsiniz. Bu yaklaşım, güncelleştirmeleri görmek için meta verilerin el ile yenilenmesini gerektirir.

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

PyIceberg ile Azure Databricks tablolarını kullanma

Azure Databricks tablolarına erişmek için PyIceberg'i kullanmak için gerekli bağımlılıklarla PyIceberg'i yüklemeniz gerekir. PyIceberg, verileri okuma ve tablo meta verilerini inceleme gibi tablo işlemleri gerektirir pyarrow . PyIceberg'i şu ek özellikleriyle pyarrow yükleyin:

pip install "pyiceberg[pyarrow]"

Not

yüklemezseniz pyarrow, tabloları açıklama veya okuma gibi işlemler başarısız olur. İsteğe bağlı bağımlılıkların tam listesi için PyIceberg belgelerine bakın.

Aşağıda, PyIceberg'in Unity Kataloğu'ndaki Iceberg REST Kataloğu'na bağlanarak Azure Databricks tablolarına erişmesine izin veren yapılandırma ayarlarına bir örnek verilmiştir:

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

Aşağıdaki değişkenleri değiştirin:

  • <uc-catalog-name>: Unity Kataloğu'nda erişmeniz gereken kataloğun adı.
  • <token>: Tümleştirmeyi yapılandıran sorumlu için kişisel erişim belirteci (PAT).

PyIceberg REST katalog yapılandırması belgelerine bakın.

REST API curl örneği

Aşağıdaki curl örnek REST API kullanarak bir tablo yükler:

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>

Yanıt şöyle görünür:

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

Not

Alanı expires-at-ms , kimlik bilgilerinin süresinin ne zaman dolduğunda gösterir. Varsayılan süre sonu bir saattir. Daha iyi performans için, istemcinin kimlik bilgilerini yeni kimlik bilgileri istemeden önce süresi dolana kadar önbelleğe almalarını sağlayın.

  • Last updated on