Accedere alle tabelle di Databricks dai client Delta

Questa pagina descrive come usare l'API REST di Unity per creare, leggere e scrivere in tabelle gestite ed esterne del catalogo Unity da client Delta esterni. Per un elenco completo delle integrazioni supportate, vedere Integrazioni del catalogo Unity.

Creare, leggere e scrivere usando l'API REST di Unity

L'API REST di Unity fornisce ai client esterni l'accesso, la lettura e la scrittura alle tabelle registrate nel catalogo Unity. Configurare l'accesso usando l'URL dell'area di lavoro come endpoint. I tipi di tabella seguenti sono accessibili:

* Supportato per le tabelle Delta gestite con commit del catalogo.

Requisiti

Azure Databricks supporta l'accesso alle tabelle tramite l'API REST di Unity come parte del Catalogo Unity. Per usare questi endpoint, è necessario abilitare Unity Catalog nell'area di lavoro.

È anche necessario completare i passaggi di configurazione seguenti per configurare l'accesso alle tabelle dai client Delta usando l'API REST di Unity:

• Abilitare l'accesso ai dati esterni per il metastore. Vedere Abilitare l'accesso ai dati esterni nel metastore.
• Concedere all'entità di accesso ai dati esternamente il EXTERNAL USE SCHEMA privilegio per lo schema contenente gli oggetti . Vedi Concedere privilegi del catalogo Unity a un'entità di sicurezza.
• Per le tabelle esterne a cui si accede tramite percorso: concedere all'entità il privilegio EXTERNAL USE LOCATION nella posizione esterna contenente il percorso della tabella. Vedi Concedere privilegi del catalogo Unity a un'entità di sicurezza.
• Assicurarsi che il principale disponga dei privilegi pertinenti:
  • SELECT sulla tabella per le letture
  • MODIFY nella tabella per le operazioni di scrittura
  • CREATE nello schema per la creazione di tabelle
  • Per le scritture esterne su tabelle Delta gestite, verificare che la tabella su cui si sta scrivendo abbia i commit del catalogo abilitati.
• Eseguire l'autenticazione con uno dei metodi seguenti:
  • Token di accesso personale (PAT): vedere Autorizzare l'accesso alle risorse Azure Databricks.
  • Autenticazione da computer a computer OAuth (M2M): supporta l'aggiornamento automatico delle credenziali e dei token per i processi Spark a esecuzione prolungata (>1 ora). Vedere Autorizzare l'accesso all'entità servizio per Azure Databricks con OAuth.

Limitazioni

• L'accesso esterno alle tabelle UniForm con IcebergCompatV3 non è attualmente supportato. Dopo la scrittura esterna in una tabella UniForm, è necessario eseguire MSCK REPAIR TABLE in Databricks per generare metadati Iceberg.
• Le modifiche dello schema (ad esempio , ALTER TABLE), gli aggiornamenti delle proprietà della tabella e le modifiche delle funzionalità delle tabelle non sono attualmente supportate nelle tabelle gestite dai client esterni.
• I client esterni non possono eseguire operazioni di manutenzione tabelle, ad esempio OPTIMIZE, VACUUMe ANALYZE, nelle tabelle Delta gestite.
• I client esterni non possono creare cloni superficiali.
• I client esterni non possono creare tabelle con colonne generate, colonne predefinite o colonne vincolo.
• Quando si creano tabelle esterne, Azure Databricks consiglia di usare Apache Spark per assicurarsi che le definizioni di colonna siano in un formato compatibile con Apache Spark. L'API non convalida la correttezza della specifica della colonna. Se la specifica non è compatibile con Apache Spark, Databricks Runtime potrebbe non essere in grado di leggere le tabelle.

Accedere alle tabelle Delta con Apache Spark usando l'autenticazione PAT

La configurazione seguente è necessaria per leggere o scrivere in tabelle Delta gestite ed esterne del catalogo Unity con Apache Spark tramite l'autenticazione PAT:

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

Sostituire le variabili seguenti:

• <uc-catalog-name>: nome del catalogo in Unity Catalog che contiene le tabelle.
• <token>: token di accesso personale (PAT) per l'entità che configura l'integrazione.

• <workspace-url>: URL Azure Databricks workspace, incluso l'ID dell'area di lavoro. Ad esempio: adb-1234567890123456.12.azuredatabricks.net.

Per altri dettagli sulla configurazione di Apache Spark per l'archiviazione di oggetti cloud, vedere la documentazione relativa al sistema operativo del catalogo Unity.

Per creare tabelle Delta gestite con commit del catalogo, usare il codice SQL seguente:

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

Per creare tabelle Delta esterne, usare il codice SQL seguente:

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

Accedere alle tabelle Delta con Apache Spark usando l'autenticazione OAuth

Azure Databricks supporta anche l'autenticazione da computer a computer (M2M) OAuth. OAuth gestisce automaticamente il rinnovo di token e credenziali per l'autenticazione del catalogo Unity.

L'autenticazione OAuth per i client Spark esterni richiede:

• Versione 0.4.1 o successiva del client Spark di Unity Catalog (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 o versione successiva
• Delta Spark 4.2.0 o versione successiva
• Principale del servizio OAuth M2M con autorizzazioni corrette. Vedere Autorizzare l'accesso all'entità servizio per Azure Databricks con OAuth.

La configurazione seguente è necessaria per creare, leggere o scrivere in tabelle gestite del catalogo Unity e tabelle Delta esterne con Apache Spark usando l'autenticazione OAuth:

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

Sostituire le variabili seguenti:

• <uc-catalog-name>: nome del catalogo in Unity Catalog che contiene le tabelle.
• <oauth-token-endpoint>: URL dell'endpoint del token OAuth. Per costruire questo URL:
  1. Trova l'ID account di Azure Databricks. Vedi Trova l'ID del tuo account.
  2. Usare il formato: https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: ID client OAuth per il principale del servizio. Vedere Autorizzare l'accesso all'entità servizio per Azure Databricks con OAuth.
• <oauth-client-secret>: segreto client OAuth per il principale del servizio. Vedere Autorizzare l'accesso all'entità servizio per Azure Databricks con OAuth.

• <workspace-url>: URL Azure Databricks workspace, incluso l'ID dell'area di lavoro. Ad esempio: adb-1234567890123456.12.azuredatabricks.net.

Creare tabelle Delta usando l'API

Per creare una tabella Delta esterna usando l'API REST del catalogo Unity, seguire questa procedura:

Passaggio 1: Effettuare una richiesta POST all'API Crea tabella

Usare la richiesta API seguente per registrare i metadati della tabella nel catalogo unity:

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

Sostituire le variabili seguenti:

• <workspace-url>: URL dell'area di lavoro Azure Databricks
• <token>: token per l'entità che effettua la chiamata API
• <uc-catalog-name>: nome del catalogo in Unity Catalog che conterrà la tabella esterna
• <schema-name>: nome dello schema all'interno del catalogo in cui verrà creata la tabella
• <table-name>: nome della tabella esterna
• <path>: percorso pienamente qualificato ai dati della tabella

Passaggio 2: Inizializzare la posizione della tabella Delta

La chiamata API precedente registra la tabella in :[UC], ma non crea i file Delta nel percorso di archiviazione. Per inizializzare il percorso della tabella, scrivere una tabella Delta vuota usando Spark:

Lo schema usato in questo passaggio deve corrispondere esattamente alle definizioni di colonna fornite nella richiesta 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>")