Delta istemcilerinden Databricks tablolarına erişme

Bu sayfada, Unity REST API'sinin dış Delta istemcilerinden Unity Kataloğu tarafından yönetilen ve dış tablolar oluşturmak, okumak ve bunlara yazmak için nasıl kullanılacağı açıklanmaktadır. Desteklenen tümleştirmelerin tam listesi için bkz. Unity Kataloğu tümleştirmeleri.

Bahşiş

Microsoft Fabric kullanarak Azure Databricks verilerini okuma hakkında bilgi için bkz. Unity Kataloğu'nda kayıtlı verileri okumak için Microsoft Fabric kullanma.

Unity REST API'sini kullanarak oluşturma, okuma ve yazma

Önemli

Delta istemcilerinden Unity Kataloğu yönetilen tabloları oluşturma ve bu tablolara yazma Beta aşamasındadır. Dış istemci desteği sınırlıdır.

Unity REST API,Unity Kataloğu'na kayıtlı tablolara dış istemciler oluşturma, okuma ve yazma erişimi sağlar. Uç nokta olarak çalışma alanı URL'sini kullanarak erişimi yapılandırın. Aşağıdaki tablo türleri erişilebilir:

Tablo türü Read Write Oluştur
Yönetilen Delta Evet Evet* Evet*
Dış Delta Evet Evet Evet

* Katalog işlemeleri ile yönetilen Delta tabloları için desteklenir.

Gereksinimler

Azure Databricks, Unity Kataloğu'nun bir parçası olarak tablolara Unity REST API erişimini destekler. Bu uç noktaları kullanmak için çalışma alanınızda Unity Kataloğu'nu etkinleştirmiş olmanız gerekir.

Unity REST API'sini kullanarak Delta istemcilerinden tablolara erişimi yapılandırmak için aşağıdaki yapılandırma adımlarını da tamamlamanız gerekir:

Sınırlamalar

  • IcebergCompatV3 ile UniForm tablolarına dış erişim şu anda desteklenmiyor. UniForm tablosuna dışarıdan yazdıktan sonra Databricks'te çalıştırarak MSCK REPAIR TABLE Iceberg meta verileri oluşturmanız gerekir.
  • Şema değişiklikleri (örneğin, ALTER TABLE), tablo özelliği güncelleştirmeleri ve tablo özelliği değişiklikleri şu anda dış istemcilerden yönetilen tablolarda desteklenmemektedir.
  • Dış istemciler yönetilen Delta tablolarında , OPTIMIZEve VACUUMgibi ANALYZEtablo bakım işlemlerini gerçekleştiremez.
  • Dış istemciler sığ kopya oluşturamaz.
  • Dış istemciler, oluşturulan sütunlar, varsayılan sütunlar veya kısıtlama sütunları içeren tablolar oluşturamaz.
  • Dış tablolar oluştururken, Azure Databricks sütun tanımlarının Apache Spark ile uyumlu bir biçimde olduğundan emin olmak için Apache Spark kullanılmasını önerir. API, sütun belirtiminin doğruluğunu doğrulamaz. Belirtim Apache Spark ile uyumlu değilse Databricks Runtime tabloları okuyamayabilir.

PAT kimlik doğrulamasını kullanarak Apache Spark ile Delta tablolarına erişme

PAT kimlik doğrulamasını kullanarak Apache Spark ile Unity Kataloğu yönetilen ve dış Delta tablolarını okumak veya bu tablolara yazmak için aşağıdaki yapılandırma gereklidir:

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

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

  • <uc-catalog-name>: Unity Kataloğu'nda tablolarınızı içeren kataloğun adı.
  • <token>: Tümleştirmeyi yapılandıran sorumlu için kişisel erişim belirteci (PAT).
  • <workspace-url>: Azure Databricks çalışma alanı URL'si, çalışma alanı kimliği dahil olmak üzere. Örneğin, adb-1234567890123456.12.azuredatabricks.net.

Uyarı

Yukarıda gösterilen paket sürümleri, bu sayfada yapılan son güncelleştirmeden itibaren geçerlidir. Daha yeni sürümler kullanılabilir. Paket sürümlerinin Spark sürümünüzle uyumlu olduğunu doğrulayın.

Bulut nesne depolaması için Apache Spark'ı yapılandırma hakkında ek ayrıntılar için Unity Kataloğu OSS belgelerine bakın.

Önemli

Databricks Runtime 16.4 ve üzeri, katalog işlemeleri etkinleştirilmiş tabloları okumak, yazmak veya oluşturmak için gereklidir. Mevcut tablolarda katalog işlemelerini etkinleştirmek veya devre dışı bırakmak için Databricks Runtime 18.0 ve üzeri gereklidir.

Katalog işlemeleriyle yönetilen Delta tabloları oluşturmak için aşağıdaki SQL'i kullanın:

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

Dış Delta tabloları oluşturmak için aşağıdaki SQL'i kullanın:

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

OAuth kimlik doğrulamasını kullanarak Apache Spark ile Delta tablolarına erişme

Azure Databricks ayrıca OAuth makineden makineye (M2M) kimlik doğrulamasını da destekler. OAuth, Unity Kataloğu kimlik doğrulaması için belirteci ve kimlik bilgisi yenilemeyi otomatik olarak işler.

Dış Spark istemcileri için OAuth kimlik doğrulaması şunları gerektirir:

  • Unity Kataloğu Spark istemci sürümü 0.4.1 veya üzeri (io.unitycatalog:unitycatalog-spark)
  • Apache Spark 4.0 veya üzeri
  • Delta Spark 4.2.0 veya üzeri
  • Uygun izinlere sahip bir OAuth M2M hizmet sorumlusu. Azure Databricks üzerinde OAuth ile hizmet sorumlusu erişimini yetkilendirme için Yetkilendirmeye bakın.

OAuth kimlik doğrulamasını kullanarak Apache Spark ile Unity Kataloğu yönetilen tabloları ve dış Delta tablolarını oluşturmak, okumak veya yazmak için aşağıdaki yapılandırma gereklidir:

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

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

  • <uc-catalog-name>: Unity Kataloğu'nda tablolarınızı içeren kataloğun adı.
  • <oauth-token-endpoint>: OAuth belirteci uç noktası URL'si. Bu URL'yi oluşturmak için:
    1. Azure Databricks hesap kimliğinizi bulun. Bkz Hesap kimliğinizi bulma.
    2. Şu biçimi kullanın: https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
  • <oauth-client-id>: Hizmet sorumlunuz için OAuth istemci kimliği. Azure Databricks üzerinde OAuth ile hizmet sorumlusu erişimini yetkilendirme için Yetkilendirmeye bakın.
  • <oauth-client-secret>: Hizmet sorumlunuz için OAuth istemci gizli anahtarı. Azure Databricks üzerinde OAuth ile hizmet sorumlusu erişimini yetkilendirme için Yetkilendirmeye bakın.
  • <workspace-url>: Azure Databricks çalışma alanı URL'si, çalışma alanı kimliği dahil olmak üzere. Örneğin, adb-1234567890123456.12.azuredatabricks.net.

Uyarı

Yukarıda gösterilen paket sürümleri, bu sayfada yapılan son güncelleştirmeden itibaren geçerlidir. Daha yeni sürümler kullanılabilir. Paket sürümlerinin Spark sürümünüzle uyumlu olduğunu doğrulayın.

API kullanarak Delta tabloları oluşturma

Unity Kataloğu REST API'sini kullanarak dış Delta tablosu oluşturmak için şu adımları izleyin:

1. Adım: Tablo Oluşturma API'sine POST isteğinde bulunma

Tablo meta verilerini Unity Kataloğu'na kaydetmek için aşağıdaki API isteğini kullanın:

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

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

  • <workspace-url>: Azure Databricks çalışma alanının URL'si
  • <token>: API çağrısı yapan sorumlunun belirteci
  • <uc-catalog-name>: Unity Kataloğu'nda dış tabloyu içerecek kataloğun adı
  • <schema-name>: Tablonun oluşturulacağı katalog içindeki şemanın adı
  • <table-name>: Dış tablonun adı
  • <path>: Tablo verilerinin tam yolu

2. Adım: Delta tablosu konumunu başlatma

Yukarıdaki API çağrısı tabloyu :[UC] konumuna kaydeder, ancak Delta dosyalarını depolama konumunda oluşturmaz. Tablo konumunu başlatmak için Spark kullanarak boş bir Delta tablosu yazın:

Bu adımda kullanılan şema, API isteğinde sağlanan sütun tanımlarıyla tam olarak eşleşmelidir.


from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")

Uyarı

Dış istemciler için Tablo Oluşturma API'sinde aşağıdaki sınırlamalar vardır:

  • Yalnızca dış Delta tabloları desteklenir ("table_type": "EXTERNAL" ve "data_source_format": "DELTA").
  • Yalnızca aşağıdaki alanlara izin verilir:
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • Sütun maskeleri desteklenmez.
  • Last updated on