Leggi e scrivi metadati aggiuntivi della tabella (anteprima)

Usa l'API aggiuntiva di metadati di tabelle OneLake per leggere e scrivere descrizioni e tag chiave-valore per una tabella e le sue colonne. Questa API utilizza una route REST comune anziché le route di Iceberg REST Catalog o quelle compatibili con Unity Catalog.

Ad esempio, aggiungi una descrizione che spieghi lo scopo aziendale di una tabella, etichetta la tabella con il team proprietario e descrivi come interpretare una colonna. Queste operazioni lavorano con metadati descrittivi, non con righe di tabella. Per recuperare righe, usa l'API di lettura delle tabelle OneLake.

Prerequisiti

• Completa i prerequisiti dell'API a tabelle condivise e i passaggi di autenticazione.
• Identifica l'ID dello spazio di lavoro, l'ID dell'elemento, il nome dello schema e il nome della tabella per la tabella di destinazione.
• Identifica le colonne esistenti che vuoi descrivere o taggare.
• Usa un'identità con i permessi necessari per leggere o scrivere i metadati per la tabella di destinazione.

Gli esempi utilizzano una tabella nominata sales nello dbo schema e una colonna esistente chiamata customer_id. Sostituisci questi nomi con quelli della tua tabella.

Endpoint e operazioni

Usa il seguente URL di base:

https://onelake.table.fabric.microsoft.com

Entrambe le operazioni utilizzano lo stesso percorso:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata

Usa i GUID per <WorkspaceID> e <ItemID>. Codifica in URL i nomi dello schema e della tabella come singoli segmenti di percorso. Includi un'intestazione Authorization: Bearer <Token> con un token di accesso Microsoft Entra ID per il pubblico https://storage.azure.com/. Per POST, includi Content-Type: application/json anche.

Descrizioni e tag supportati

Usa questi campi in una POST richiesta:

Leggi metadati aggiuntivi

Invia una GET richiesta per ottenere metadati a livello di tabella e colonna.

GET https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales/additionalMetadata
Authorization: Bearer <Token>
Accept: application/json

Una richiesta riuscita restituisce 200 OK. Il seguente JSON mostra il formato delle risposte:

{
  "description": "Sales transactions.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Customer identifier.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

I valori, i nomi delle colonne e i campi nella tua risposta dipendono dalla tabella target e dai suoi metadati. Il contratto non richiede la presenza di ogni campo.

Scrivi metadati aggiuntivi

Invia una POST richiesta con un corpo JSON per sostituire i metadati aggiuntivi della tabella.

Questo esempio imposta una descrizione della tabella e dei tag, più una descrizione e un tag per customer_id. Identifica la colonna usando columnName.

POST https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales/additionalMetadata
Authorization: Bearer <Token>
Content-Type: application/json
Accept: application/json

Corpo della richiesta:

{
  "description": "Sales transactions used for revenue reporting.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Identifier of the customer associated with the sale.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

Una richiesta riuscita restituisce 200 OK con un'ulteriore risposta di metadati. Ad esempio:

{
  "description": "Sales transactions used for revenue reporting.",
  "tags": {
    "domain": "sales",
    "owner": "sales-analytics"
  },
  "columns": [
    {
      "columnName": "customer_id",
      "description": "Identifier of the customer associated with the sale.",
      "tags": {
        "role": "customer-key"
      }
    }
  ]
}

Invia un'altra GET richiesta per controllare i metadati dopo la scrittura.

Preservare i metadati esistenti

Per modificare descrizioni o tag selezionati senza rimuovere altri metadati, si utilizza una sequenza di lettura-modifica-scrittura:

1. Invia una GET richiesta per leggere i metadati aggiuntivi attuali.
2. Cambia le descrizioni o i tag che vuoi aggiornare nei metadati restituiti. Conserva gli altri campi, le chiavi dei tag e le voci di colonna che vuoi conservare.
3. Invia i metadati aggiornati completi in una POST richiesta.
4. Invia un'altra GET richiesta per confermare il risultato.

Coordina gli aggiornamenti simultanei dei metadati in modo che non si verifichi un'altra scrittura tra le richieste GET e POST.

Leggi e scrivi metadati con Python

Il seguente esempio si autentica con Microsoft Entra ID, legge i metadati attuali, aggiorna descrizioni e tag selezionati preservando altri metadati e rilegge i metadati. Non chiama un'API di catalogo specifica per un formato né richiede credenziali di archiviazione.

Installare le dipendenze:

python -m pip install azure-identity requests

Configura un metodo di autenticazione di Azure Identity supportato, ad esempio effettuando l'accesso in locale con interfaccia della riga di comando di Azure, prima di eseguire il campione.

import json
from urllib.parse import quote

import requests
from azure.identity import DefaultAzureCredential

workspace_id = "<WorkspaceID>"
item_id = "<ItemID>"
schema_name = "dbo"
table_name = "sales"
column_name = "customer_id"

url = (
    "https://onelake.table.fabric.microsoft.com/common/v1/"
    f"{workspace_id}/{item_id}/schemas/{quote(schema_name, safe='')}/"
    f"tables/{quote(table_name, safe='')}/additionalMetadata"
)

with DefaultAzureCredential() as credential, requests.Session() as session:
    session.headers.update({"Accept": "application/json"})

    def request_metadata(method, **kwargs):
        token = credential.get_token("https://storage.azure.com/.default")
        response = session.request(
            method,
            url,
            headers={"Authorization": f"Bearer {token.token}"},
            timeout=30,
            **kwargs,
        )
        response.raise_for_status()
        return response.json()

    metadata = request_metadata("GET")
    print("Before:")
    print(json.dumps(metadata, indent=2))

    metadata["description"] = "Sales transactions used for revenue reporting."
    metadata.setdefault("tags", {}).update(
        {"domain": "sales", "owner": "sales-analytics"}
    )

    columns = metadata.setdefault("columns", [])
    column = next(
        (entry for entry in columns if entry.get("columnName") == column_name),
        None,
    )
    if column is None:
        column = {"columnName": column_name}
        columns.append(column)

    column["description"] = "Identifier of the customer associated with the sale."
    column.setdefault("tags", {}).update({"role": "customer-key"})

    print("Write response:")
    print(json.dumps(request_metadata("POST", json=metadata), indent=2))

    print("After:")
    print(json.dumps(request_metadata("GET"), indent=2))

L'argomento json imposta l'intestazione di richiesta Content-Type: application/json. L'esempio solleva un'eccezione per una risposta HTTP fallita invece di considerarla un aggiornamento dei metadati riuscito.

Usare i metadati con i collegamenti OneLake

Per un collegamento interno a OneLake, usa l'ID dell'area di lavoro del collegamento, l'ID dell'elemento, il nome dello schema e il nome della tabella nello stesso percorso aggiuntivo dei metadati. Le operazioni lavorano con i metadati della tabella di destinazione, non con una copia separata dei metadati per la scorciatoia:

• GET restituisce i metadati aggiuntivi della tabella target, incluse le sue descrizioni e i tag.
• POST sostituisce i metadati aggiuntivi della tabella target. I cambiamenti sono visibili quando leggi i metadati tramite la scorciatoia o la tabella target.

Ad esempio, se una scorciatoia chiamata sales_shortcut punta a sales, leggi i metadati della tabella sorgente attraverso la scorciatoia usando questa richiesta:

GET https://onelake.table.fabric.microsoft.com/common/v1/<WorkspaceID>/<ItemID>/schemas/dbo/tables/sales_shortcut/additionalMetadata
Authorization: Bearer <token>
Accept: application/json

Per aggiornare i metadati tramite la scorciatoia, invia una POST richiesta allo stesso URL. La semantica di sostituzione si applica anche alla tabella target: una richiesta basata solo sulla descrizione tramite la scorciatoia rimuove i tag e i metadati delle colonne esistenti della tabella target. Usa la sequenza di lettura-modifica-scrittura per conservare i metadati che vuoi conservare.

L'accesso richiede i permessi per l'operazione sia sul percorso del collegamento che sul percorso della tabella di destinazione. Per le scorciatoie passthrough, la tua identità richiede entrambi i tipi di permessi; i permessi della sola tabella target non sono sufficienti. Per le scorciatoie delegate, l'accesso target utilizza l'identità di connessione configurata. Per i dettagli, vedi sicurezza dei collegamenti OneLake.

Gestire errori e diagnosticare richieste

Per una richiesta non riuscita, ispezionare lo stato HTTP e la risposta di errore JSON. La struttura dell'errore ha la seguente forma; i segnaposto del codice e del messaggio non sono valori di errore specifici del servizio:

{
  "error": {
    "code": "<ErrorCode>",
    "message": "<ErrorMessage>"
  }
}

L'oggetto error può anche includere un array target e un array details. Ogni dettaglio contiene un code e un message, e può includere un target. Il contratto non elenca codici di errore o codici di stato specifici per l'operazione.

Per la diagnostica, puoi inviare un'intestazione opzionale x-ms-root-activity-id contenente un GUID. Registra l'intestazione x-ms-root-activity-id della risposta quando esegui il troubleshooting di una richiesta. Non registrare il bearer token.

Contenuti correlati

• Panoramica delle API di tabelle OneLake.
• API di metadati OneLake Iceberg.
• OneLake Delta metadata API.
• Scorciatoie OneLake.
• Leggi i dati delle tabelle OneLake.