Zugreifen auf Databricks-Tabellen von Delta-Clients

Auf dieser Seite wird beschrieben, wie Sie die Unity-REST-API zum Erstellen, Lesen und Schreiben in verwaltete und externe Tabellen aus externen Delta-Clients verwenden. Eine vollständige Liste der unterstützten Integrationen finden Sie unter Unity Catalog-Integrationen.

Erstellen, Lesen und Schreiben mithilfe der Unity-REST-API

Die Unity-REST-API bietet externen Clients Zugriff auf Tabellen, die im Unity-Katalog registriert sind, zu erstellen, zu lesen und zu schreiben. Konfigurieren Sie den Zugriff mithilfe der Arbeitsbereichs-URL als Endpunkt. Auf die folgenden Tabellentypen kann zugegriffen werden:

* Unterstützt für gemanagte Delta-Tabellen mit Katalog-Commits.

Anforderungen

Azure Databricks unterstützt den Unity-REST-API-Zugriff auf Tabellen als Teil des Unity-Katalogs. Sie müssen den Unity-Katalog in Ihrem Arbeitsbereich aktiviert haben, um diese Endpunkte zu verwenden.

Sie müssen auch die folgenden Konfigurationsschritte ausführen, um den Zugriff auf Tabellen von Delta-Clients mithilfe der Unity-REST-API zu konfigurieren:

• Aktivieren Sie den Zugriff auf externe Daten für Ihren Metastore. Siehe Aktivieren des externen Datenzugriffs im Metastore.
• Gewähren Sie dem Prinzipal, der extern auf Daten zugreift, die EXTERNAL USE SCHEMA Berechtigungen für das Schema, das die Objekte enthält. Siehe Gewähren von Hauptbenutzerberechtigungen im Unity-Katalog.
• Für externe Tabellen, auf die nach Pfad zugegriffen wird: Gewähren Sie dem Prinzipal die EXTERNAL USE LOCATION Berechtigung für den externen Speicherort, der den Tabellenpfad enthält. Siehe Gewähren von Hauptbenutzerberechtigungen im Unity-Katalog.
• Stellen Sie sicher, dass der Prinzipal über relevante Berechtigungen verfügt:
  • SELECT in der Tabelle für Lesevorgänge
  • MODIFY in der Tabelle für Schreibvorgänge
  • CREATE auf dem Schema für die Tabellenerstellung
  • Überprüfen Sie bei externen Schreibvorgängen in verwaltete Delta-Tabellen, ob für die Tabelle, in die geschrieben wird, Katalog-Commits aktiviert sind.
• Authentifizieren Sie sich mit einer der folgenden Methoden:
  • Persönlicher Zugriffstoken (PAT): Siehe Zugriff auf Azure Databricks-Ressourcen autorisieren.
  • OAuth-Computer-zu-Computer-Authentifizierung (M2M): Unterstützt die automatische Aktualisierung von Anmeldeinformationen und Token für lange ausgeführte Spark-Aufträge (>1 Stunde). Siehe Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.

Einschränkungen

• Externer Zugriff auf UniForm-Tabellen mit IcebergCompatV3 wird derzeit nicht unterstützt. Nachdem Sie extern in eine UniForm-Tabelle geschrieben haben, müssen Sie MSCK REPAIR TABLE in Databricks ausführen, um Iceberg-Metadaten zu generieren.
• Schemaänderungen (z. B. ALTER TABLE), Aktualisierungen der Tabelleneigenschaften und Änderungen der Tabellenfunktionen werden derzeit für verwaltete Tabellen von externen Clients nicht unterstützt.
• Externe Clients können keine Tabellenwartungsvorgänge wie OPTIMIZE, VACUUM und ANALYZE auf verwalteten Delta-Tabellen ausführen.
• Externe Clients können keine flachen Klonen erstellen.
• Externe Clients können keine Tabellen mit generierten Spalten, Standardspalten oder Einschränkungsspalten erstellen.
• Beim Erstellen externer Tabellen empfiehlt Azure Databricks die Verwendung von Apache Spark, um sicherzustellen, dass Spaltendefinitionen in einem Format vorliegen, das mit Apache Spark kompatibel ist. Die API überprüft nicht die Richtigkeit der Spaltenspezifikation. Wenn die Spezifikation nicht mit Apache Spark kompatibel ist, kann Databricks Runtime die Tabellen möglicherweise nicht lesen.

Zugreifen auf Delta-Tabellen mit Apache Spark mithilfe der PAT-Authentifizierung

Die folgende Konfiguration ist erforderlich, um in Unity Catalog verwaltete und externe Delta-Tabellen mit Apache Spark mithilfe der PAT-Authentifizierung zu schreiben oder zu lesen:

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

Ersetzen Sie die folgenden Variablen:

• <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, der Ihre Tabellen enthält.
• <token>: Persönliches Zugriffstoken (PAT) für den Hauptverantwortlichen, der die Integration konfiguriert.

• <workspace-url>: Die Azure Databricks workspace-URL einschließlich der Arbeitsbereichs-ID. Beispiel: adb-1234567890123456.12.azuredatabricks.net.

Weitere Details zum Konfigurieren von Apache Spark für Cloudobjektspeicher finden Sie in der Unity Catalog OSS-Dokumentation.

Um verwaltete Delta-Tabellen mit Katalog-Commits zu erstellen, verwenden Sie die folgende SQL-Anweisung:

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

Verwenden Sie zum Erstellen externer Delta-Tabellen die folgende SQL-Anweisung:

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

Zugreifen auf Delta-Tabellen mit Apache Spark mithilfe der OAuth-Authentifizierung

Azure Databricks unterstützt auch die OAuth-Computer-zu-Computer-Authentifizierung (M2M). OAuth verarbeitet automatisch die Verlängerung von Token und Anmeldeinformationen für die Unity-Katalog-Authentifizierung.

Für die OAuth-Authentifizierung für externe Spark-Clients ist Folgendes erforderlich:

• Unity Catalog Spark-Clientversion 0.4.1 oder höher (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 oder höher
• Delta Spark 4.2.0 oder höher
• Ein OAuth M2M-Dienstprinzipal mit entsprechenden Berechtigungen. Siehe Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.

Die folgende Konfiguration ist erforderlich, um verwaltete Tabellen im Unity-Katalog und externe Delta-Tabellen mit Apache Spark mithilfe der OAuth-Authentifizierung zu erstellen, zu lesen oder zu schreiben:

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

Ersetzen Sie die folgenden Variablen:

• <uc-catalog-name>: Der Name des Katalogs im Unity-Katalog, der Ihre Tabellen enthält.
• <oauth-token-endpoint>: OAuth-Tokenendpunkt-URL. So erstellen Sie diese URL:
  1. Suchen Sie Ihre Azure Databricks Konto-ID. Siehe So finden Sie Ihre Konto-ID.
  2. Verwenden Sie das Format: https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: OAuth-Client-ID für Ihren Dienstprinzipal. Siehe Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.
• <oauth-client-secret>: Der geheime OAuth-Clientschlüssel für Ihren Dienstprinzipal. Siehe Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.

• <workspace-url>: Die Azure Databricks workspace-URL einschließlich der Arbeitsbereichs-ID. Beispiel: adb-1234567890123456.12.azuredatabricks.net.

Erstellen von Delta-Tabellen mithilfe der API

Führen Sie die folgenden Schritte aus, um eine externe Delta-Tabelle mit der Unity Catalog-REST-API zu erstellen:

Schritt 1: Erstellen einer POST-Anforderung an die Create Table-API

Verwenden Sie die folgende API-Anforderung, um die Tabellenmetadaten im Unity-Katalog zu registrieren:

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

Ersetzen Sie die folgenden Variablen:

• <workspace-url>: URL des arbeitsbereichs Azure Databricks
• <token>: Token für den Verantwortlichen, der den API-Aufruf durchführt
• <uc-catalog-name>: Name des Katalogs im Unity-Katalog, der die externe Tabelle enthält
• <schema-name>: Name des Schemas innerhalb des Katalogs, in dem die Tabelle erstellt wird
• <table-name>: Name der externen Tabelle
• <path>: Vollqualifizierter Pfad zu den Tabellendaten

Schritt 2: Den Speicherort der Delta-Tabelle initialisieren

Der obige API-Aufruf registriert die Tabelle in :[UC], erstellt aber nicht die Delta-Dateien am Speicherort. Um die Tabellenposition zu initialisieren, schreiben Sie eine leere Delta-Tabelle mit Spark:

Das in diesem Schritt verwendete Schema muss genau mit den Spaltendefinitionen übereinstimmen, die in der API-Anforderung bereitgestellt werden.

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