Databricks-tabellen openen vanuit Delta-clients

Op deze pagina wordt beschreven hoe u de Unity REST API gebruikt om beheerde en externe tabellen van externe Delta-clients te maken, lezen en schrijven naar Unity Catalog. Zie Unity Catalog-integraties voor een volledige lijst met ondersteunde integraties.

Maken, lezen en schrijven met behulp van de Unity REST API

De Unity REST API biedt externe clients toegang tot tabellen die zijn geregistreerd bij Unity Catalog, maken, lezen en schrijven. Configureer de toegang met behulp van de werkruimte-URL als eindpunt. De volgende tabeltypen zijn toegankelijk:

* Ondersteund voor beheerde Delta-tabellen met cataloguscommits.

Requirements

Azure Databricks ondersteunt Unity REST API-toegang tot tabellen als onderdeel van Unity Catalog. U moet Unity Catalog in uw werkruimte hebben ingeschakeld om deze eindpunten te kunnen gebruiken.

U moet ook de volgende configuratiestappen uitvoeren om de toegang tot tabellen van Delta-clients te configureren met behulp van de Unity REST API:

• Schakel externe gegevenstoegang in voor uw metastore. Zie Externe gegevenstoegang inschakelen in de metastore.
• Verleen de principal die extern toegang heeft tot gegevens de EXTERNAL USE SCHEMA bevoegdheid voor het schema dat de objecten bevat. Zie Unity Catalog-rechten aan een principal verlenen.
• Voor externe tabellen die per pad worden geopend: Verken de principal de EXTERNAL USE LOCATION bevoegdheid op de externe locatie die het tabelpad bevat. Zie Unity Catalog-rechten aan een principal verlenen.
• Zorg ervoor dat de principal relevante bevoegdheden heeft:
  • SELECT in de tabel voor leesbewerkingen
  • MODIFY in de tabel voor schrijfbewerkingen
  • CREATE in het schema voor het maken van tabellen
  • Controleer of voor externe schrijfbewerkingen naar beheerde Delta-tabellen de catalogusdoorvoeringen zijn ingeschakeld voor de tabel waarnaar wordt geschreven.
• Verifieer met behulp van een van de volgende methoden:
  • Persoonlijk toegangstoken (PAT): Zie Toegang tot Azure Databricks resources controleren.
  • OAuth-verificatie van machine-naar-machine (M2M): ondersteunt automatische referentie- en tokenvernieuwing voor langlopende Spark-taken (>1 uur). Zie Authorize service-principaltoegang tot Azure Databricks met OAuth.

Beperkingen

• Externe toegang tot UniForm-tabellen met IcebergCompatV3 wordt momenteel niet ondersteund. Nadat u extern naar een UniForm-tabel hebt geschreven, moet u MSCK REPAIR TABLE in Databricks uitvoeren om Iceberg-metagegevens te genereren.
• Schemawijzigingen (bijvoorbeeld ALTER TABLE), updates van tabeleigenschappen en wijzigingen in tabelfuncties worden momenteel niet ondersteund voor beheerde tabellen van externe clients.
• Externe clients kunnen geen tabelonderhoudsbewerkingen uitvoeren, zoals OPTIMIZE, VACUUMen ANALYZE, op beheerde Delta-tabellen.
• Externe clients kunnen geen ondiepe klonen maken.
• Externe clients kunnen geen tabellen maken met gegenereerde kolommen, standaardkolommen of beperkte kolommen.
• Wanneer u externe tabellen maakt, wordt Azure Databricks aangeraden Apache Spark te gebruiken om ervoor te zorgen dat kolomdefinities een indeling hebben die compatibel is met Apache Spark. De API valideert niet de juistheid van de kolomspecificatie. Als de specificatie niet compatibel is met Apache Spark, kan Databricks Runtime de tabellen mogelijk niet lezen.

Toegang tot Delta-tabellen met Apache Spark met behulp van PAT-verificatie

De volgende configuratie is vereist voor het lezen of schrijven naar beheerde en externe Delta-tabellen van Unity Catalog met Apache Spark met behulp van PAT-verificatie:

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

Vervang de volgende variabelen:

• <uc-catalog-name>: de naam van de catalogus in Unity Catalog die uw tabellen bevat.
• <token>: Persoonlijk toegangstoken (PAT) voor de principal die de integratie configureert.

• <workspace-url>: de url van de Azure Databricks werkruimte, inclusief de werkruimte-id. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.

Zie de DOCUMENTATIE van Unity Catalog OSS voor meer informatie over het configureren van Apache Spark voor cloudobjectopslag.

Gebruik de volgende SQL om beheerde Delta-tabellen te maken met catalogusdoorvoeringen:

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

Gebruik de volgende SQL om externe Delta-tabellen te maken:

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

Toegang tot Delta-tabellen met Apache Spark met behulp van OAuth-verificatie

Azure Databricks ondersteunt ook verificatie van OAuth-machine-naar-machine (M2M). OAuth verwerkt automatisch het vernieuwen van tokens en referenties voor Unity Catalog-verificatie.

OAuth-verificatie voor externe Spark-clients vereist:

• Unity Catalog Spark-clientversie 0.4.1 of hoger (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 of hoger
• Delta Spark 4.2.0 of hoger
• Een OAuth M2M-service-principal met de juiste machtigingen. Zie Authorize service-principaltoegang tot Azure Databricks met OAuth.

De volgende configuratie is vereist voor het maken, lezen of schrijven van beheerde tabellen in Unity Catalog en externe Delta-tabellen met Apache Spark met behulp van OAuth-verificatie:

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

Vervang de volgende variabelen:

• <uc-catalog-name>: de naam van de catalogus in Unity Catalog die uw tabellen bevat.
• <oauth-token-endpoint>: EINDPUNT-URL van OAuth-token. Ga als volgt te werk om deze URL te maken:
  1. Zoek uw Azure Databricks account-id. Zie Uw account-id opzoeken.
  2. Gebruik de notatie: https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: OAuth-client-id voor uw service-principal. Zie Authorize service-principaltoegang tot Azure Databricks met OAuth.
• <oauth-client-secret>: OAuth-clientgeheim voor uw service-principal. Zie Authorize service-principaltoegang tot Azure Databricks met OAuth.

• <workspace-url>: de url van de Azure Databricks werkruimte, inclusief de werkruimte-id. Bijvoorbeeld: adb-1234567890123456.12.azuredatabricks.net.

Delta-tabellen maken met behulp van de API

Voer de volgende stappen uit om een externe Delta-tabel te maken met behulp van de REST API van Unity Catalog:

Stap 1: Dien een POST-verzoek in bij de Create Table API

Gebruik de volgende API-aanvraag om de metagegevens van de tabel in Unity Catalog te registreren:

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

Vervang de volgende variabelen:

• <workspace-url>: URL van de Azure Databricks-werkruimte
• <token>: Token voor de principal die de API-aanroep maakt
• <uc-catalog-name>: Naam van de catalogus in Unity Catalog die de externe tabel bevat
• <schema-name>: Naam van het schema in de catalogus waarin de tabel wordt gemaakt
• <table-name>: Naam van de externe tabel
• <path>: Volledig gekwalificeerd pad naar de tabelgegevens

Stap 2: De locatie van de Delta-tabel initialiseren

De bovenstaande API-aanroep registreert de tabel in :[UC], maar maakt de Delta-bestanden niet op de opslaglocatie. Als u de tabellocatie wilt initialiseren, schrijft u een lege Delta-tabel met behulp van Spark:

Het schema dat in deze stap wordt gebruikt, moet exact overeenkomen met de kolomdefinities die zijn opgegeven in de API-aanvraag.

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