デルタ クライアントから Databricks テーブルにアクセスする

このページでは、Unity REST API を使用して、外部 Delta クライアントから Unity カタログのマネージド テーブルと外部テーブルを作成、読み取り、書き込む方法について説明します。 サポートされている統合の完全な一覧については、 Unity カタログの統合を参照してください。

Unity REST API を使用して作成、読み取り、書き込みを行う

Unity REST API は、Unity カタログに登録されているテーブルへの外部クライアントの作成、読み取り、書き込みアクセスを提供します。 ワークスペース URL をエンドポイントとして使用してアクセスを構成します。 次の表の種類にアクセスできます。

* カタログ コミットを持つマネージド Delta テーブルでサポートされます。

要件

Azure Databricksでは、Unity カタログの一部として、テーブルへの Unity REST API アクセスがサポートされます。 これらのエンドポイントを使用するには、ワークスペースで Unity カタログを有効にする必要があります。

Unity REST API を使用して Delta クライアントからテーブルへのアクセスを構成するには、次の構成手順も完了する必要があります。

• メタストアで外部データ アクセスを有効にします。 「メタストアで外部データ アクセスを有効にする」を参照してください。
• 外部からデータにアクセスするプリンシパルに、オブジェクトを含むスキーマに対する EXTERNAL USE SCHEMA 特権を付与します。 Unity カタログのプリンシパル権限の付与について参照してください。
• パスによってアクセスされる外部テーブルの場合: プリンシパルに、テーブル パスを含む外部の場所に対する EXTERNAL USE LOCATION 特権を付与します。 Unity カタログのプリンシパル権限の付与について参照してください。
• プリンシパルに関連する特権があることを確認します。
  • SELECT テーブル上での読み取りに使用
  • MODIFY 書き込み用のテーブル上
  • CREATE テーブル作成のためのスキーマに対する
  • マネージド Delta テーブルへの外部書き込みの場合は、書き込み先のテーブルで カタログ コミット が有効になっていることを確認します。
• 次のいずれかの方法を使用して認証します。
  • 個人用アクセス トークン (PAT): Azure Databricks リソースへのアクセスの認証を参照してください。
  • OAuth マシン間 (M2M) 認証: 実行時間の長い Spark ジョブ (>1 時間) の自動資格情報とトークン更新をサポートします。 Azure Databricks へのサービス プリンシパル アクセスを OAuth で承認する方法については、こちらを参照してください。

制限事項

• IcebergCompatV3 を使用した UniForm テーブルへの外部アクセスは現在サポートされていません。 UniForm テーブルに外部から書き込んだ後、Databricks で MSCK REPAIR TABLE を実行して Iceberg メタデータを生成する必要があります。
• スキーマの変更 ( ALTER TABLEなど)、テーブル プロパティの更新、テーブル機能の変更は、現在、外部クライアントのマネージド テーブルではサポートされていません。
• 外部クライアントは、マネージド Delta テーブルに対してテーブルのメンテナンス操作 ( OPTIMIZE、 VACUUM、 ANALYZEなど) を実行できません。
• 外部クライアントは 浅いクローンを作成できません。
• 外部クライアントは、生成された列、既定の列、または制約列を含むテーブルを作成できません。
• 外部テーブルを作成する場合Azure Databricksは、Apache Spark を使用して、列定義が Apache Spark と互換性のある形式であることを確認することをお勧めします。 API では、列の指定の正確性は検証されません。 仕様が Apache Spark と互換性がない場合、Databricks Runtime がテーブルを読み取ることができない可能性があります。

PAT認証を使用してApache SparkでDeltaテーブルにアクセスする

PAT 認証を使用して Apache Spark を使用して Unity カタログのマネージド および外部 Delta テーブルを読み取りまたは書き込むには、次の構成が必要です。

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

次の変数に置き換える:

• <uc-catalog-name>: テーブルを含む Unity カタログ内のカタログの名前。
• <token>: 統合を構成するプリンシパルの個人用アクセス トークン (PAT)。

• <workspace-url>: ワークスペース ID を含む Azure Databricks の ワークスペース URL。 たとえば、「 adb-1234567890123456.12.azuredatabricks.net 」のように入力します。

クラウド オブジェクト ストレージ用に Apache Spark を構成する方法の詳細については、 Unity カタログ OSS のドキュメントを参照してください。

カタログ コミットを使用してマネージド Delta テーブルを作成するには、次の SQL を使用します。

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

外部差分テーブルを作成するには、次の SQL を使用します。

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

OAuth 認証を使用して Apache Spark を利用し、Delta Lakeのテーブルにアクセスする

Azure Databricksでは、OAuth マシン間 (M2M) 認証もサポートされます。 OAuth は、Unity カタログ認証のトークンと資格情報の更新を自動的に処理します。

外部 Spark クライアントの OAuth 認証には、次のものが必要です。

• Unity Catalog Spark クライアント バージョン 0.4.1 以降 (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 以降
• Delta Spark 4.2.0 以降
• 適切なアクセス許可を持つ OAuth M2M サービス プリンシパル。 Azure Databricks へのサービス プリンシパル アクセスを OAuth で承認する方法については、こちらを参照してください。

OAuth 認証を使用して Apache Spark を使用して Unity カタログのマネージド テーブルと外部 Delta テーブルを作成、読み取り、または書き込むには、次の構成が必要です。

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

次の変数に置き換える:

• <uc-catalog-name>: テーブルを含む Unity カタログ内のカタログの名前。
• <oauth-token-endpoint>: OAuth トークン エンドポイントの URL。 この URL を構築するには:
  1. Azure Databricks アカウント ID を見つけます。 「アカウント ID を特定する」を参照してください。
  2. 次の形式を使用します。 https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: サービス プリンシパルの OAuth クライアント ID。 Azure Databricks へのサービス プリンシパル アクセスを OAuth で承認する方法については、こちらを参照してください。
• <oauth-client-secret>: サービス プリンシパルの OAuth クライアント シークレット。 Azure Databricks へのサービス プリンシパル アクセスを OAuth で承認する方法については、こちらを参照してください。

• <workspace-url>: ワークスペース ID を含む Azure Databricks の ワークスペース URL。 たとえば、「 adb-1234567890123456.12.azuredatabricks.net 」のように入力します。

API を使用してデルタ テーブルを作成する

Unity カタログ REST API を使用して外部 Delta テーブルを作成するには、次の手順に従います。

手順 1: Create Table API に POST 要求を行う

Unity カタログにテーブル メタデータを登録するには、次の API 要求を使用します。

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
    }
  ]
}'

次の変数に置き換える:

• <workspace-url>: Azure Databricks ワークスペースの URL
• <token>: API 呼び出しを行うプリンシパルのトークン
• <uc-catalog-name>: 外部テーブルを含む Unity カタログ内のカタログの名前
• <schema-name>: テーブルが作成されるカタログ内のスキーマの名前
• <table-name>: 外部テーブルの名前
• <path>: テーブル データへの完全修飾パス

手順 2: Delta テーブルの場所を初期化する

上記の API 呼び出しではテーブルが :[UC]に登録されますが、保存場所に Delta ファイルは作成されません。 テーブルの場所を初期化するには、Spark を使用して空の Delta テーブルを作成します。

この手順で使用するスキーマは、API 要求で指定された列定義と完全に一致している必要があります。

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