Lesen und schreiben Sie zusätzliche Tabellenmetadaten (Vorschau)

Verwenden Sie die zusätzliche Tabellenmetadaten-API von OneLake, um Beschreibungen und Schlüssel-Wert-Tags für eine Tabelle und ihre Spalten zu lesen und zu schreiben. Diese API verwendet eine gemeinsame REST-Route anstelle der Iceberg REST Catalog- oder Unity Catalog-kompatiblen Routen.

Füge zum Beispiel eine Beschreibung hinzu, die den Geschäftszweck einer Tabelle erklärt, tagge die Tabelle mit dem zuständigen Team und beschreibe, wie eine Spalte interpretiert werden soll. Diese Operationen arbeiten mit deskriptiven Metadaten, nicht mit Tabellenzeilen. Um Zeilen abzurufen, verwenden Sie die OneLake Table Read API.

Voraussetzungen

• Erfüllen Sie die Voraussetzungen und Authentifizierungsschritte der geteilten Tabellen-API.
• Identifizieren Sie die Arbeitsbereichs-ID, die Item-ID, den Schemanamen und den Tabellennamen Ihrer Zieltabelle.
• Identifizieren Sie die vorhandenen Spalten, die Sie beschreiben oder markieren möchten.
• Verwenden Sie eine Identität mit den erforderlichen Berechtigungen, um Metadaten für die Zieltabelle zu lesen oder zu schreiben.

Die Beispiele verwenden eine Tabelle namens dbo im Schema sales und eine bestehende Spalte namens customer_id. Ersetzen Sie diese Namen durch die Namen Ihrer Tabelle.

Endpoint und Operationen

Verwenden Sie die folgende Basis-URL:

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

Beide Vorgänge nutzen dieselbe Route:

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

Verwenden Sie GUIDs für <WorkspaceID> und <ItemID>. URL-kodieren Sie das Schema und die Tabellennamen als einzelne Pfadsegmente. Fügen Sie einen Authorization: Bearer <Token> Header mit einem Microsoft Entra ID-Zugriffstoken für die https://storage.azure.com/ Zielgruppe hinzu. Für POST schließen Sie Content-Type: application/json ebenfalls ein.

Unterstützte Beschreibungen und Tags

Verwenden Sie diese Felder in einer POST Anfrage:

Lesen Sie weitere Metadaten

Senden Sie eine GET Anfrage, um Metadaten auf Tabellenebene und Spaltenebene zu erhalten.

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

Eine erfolgreiche Anforderung gibt zurück 200 OK. Das folgende JSON zeigt das Antwortformat:

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

Die Werte, Spaltennamen und Felder in Ihrer Antwort hängen von der Zieltabelle und deren Metadaten ab. Der Vertrag verlangt nicht, dass jedes Feld vorhanden ist.

Zusätzliche Metadaten schreiben

Senden Sie eine POST-Anfrage mit einem JSON-Körper, um die zusätzlichen Metadaten der Tabelle zu ersetzen.

Dieses Beispiel legt eine Tabellenbeschreibung und Tags sowie eine Beschreibung und ein Tag für customer_idfest. Sie identifiziert die Spalte mit 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

Anfrageinhalt:

{
  "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"
      }
    }
  ]
}

Eine erfolgreiche Anfrage gibt 200 OK mit einer zusätzlichen Metadaten-Antwort zurück. Beispiele:

{
  "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"
      }
    }
  ]
}

Senden Sie nach dem Schreiben eine weitere GET Anfrage, um die Metadaten zu überprüfen.

Bestehende Metadaten bewahren

Um ausgewählte Beschreibungen oder Tags zu ändern, ohne andere Metadaten zu entfernen, verwenden Sie eine Read-Modify-Write-Sequenz:

1. Senden Sie eine GET Anfrage, um die aktuellen zusätzlichen Metadaten zu lesen.
2. Ändern Sie die Beschreibungen oder Tags, die Sie in den zurückgegebenen Metadaten aktualisieren möchten. Behalte die anderen Felder, Tag-Schlüssel und Spalteneinträge, die du behalten möchtest.
3. Senden Sie die vollständigen aktualisierten Metadaten in einer POST Anfrage.
4. Senden Sie eine weitere GET Anfrage zur Bestätigung des Ergebnisses.

Koordiniere gleichzeitige Metadaten-Updates, damit zwischen deinen GET- und POST-Anfragen kein weiterer Schreibvorgang erfolgt.

Metadaten mit Python lesen und schreiben

Das folgende Beispiel authentifiziert sich mit Microsoft Entra ID, liest die aktuellen Metadaten, aktualisiert ausgewählte Beschreibungen und Tags, wobei die übrigen Metadaten beibehalten werden, und liest die Metadaten erneut. Es ruft keine formatspezifische Katalog-API auf und fordert keine Speicheranmeldeinformationen an.

Installieren Sie die Abhängigkeiten:

python -m pip install azure-identity requests

Konfigurieren Sie eine unterstützte Azure Identity-Authentifizierungsmethode, wie zum Beispiel die lokale Anmeldung mit der Azure CLI, bevor Sie das Beispiel ausführen.

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

Das Argument json setzt den Content-Type: application/json Request-Header. Das Beispiel erzeugt eine Ausnahme für eine erfolglose HTTP-Antwort, anstatt sie als erfolgreiches Metadaten-Update zu behandeln.

Arbeiten Sie mit Metadaten über OneLake-Verknüpfungen

Für eine interne OneLake-Tabellen-Verknüpfung verwenden Sie die Arbeitsbereich-ID, die Item-ID, den Schemanamen und den Tabellennamen des Shortcuts in derselben zusätzlichen Metadaten-Route. Die Operationen arbeiten mit den Metadaten der Zieltabelle, nicht mit einer separaten Kopie der Metadaten für die Verknüpfung:

• GET gibt die zusätzlichen Metadaten der Zieltabelle zurück, einschließlich ihrer Beschreibungen und Tags.
• POST ersetzt die zusätzlichen Metadaten der Zieltabelle. Die Änderungen sind sichtbar, wenn man Metadaten entweder über die Verknüpfung oder die Zieltabelle liest.

Zum Beispiel, wenn eine Verknüpfung namens sales auf sales_shortcut zeigt, lesen Sie die Metadaten der Quelltabelle durch die Verknüpfung mit folgender Anfrage:

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

Um Metadaten über den Shortcut zu aktualisieren, senden Sie eine POST Anfrage an dieselbe URL. Die Ersetzungssemantik gilt auch für die Zieltabelle: Eine reine Beschreibungsanforderung über den Kurzbefehl entfernt die vorhandenen Tags und Spaltenmetadaten der Zieltabelle. Verwenden Sie die Read-Modify-Write-Sequenz, um die Metadaten zu behalten, die Sie behalten möchten.

Der Zugriff erfordert Berechtigungen für die Operation sowohl auf dem Shortcut-Pfad als auch auf dem Zieltabellenpfad. Für Passthrough-Shortcuts benötigt Ihre Identität beide Berechtigungssätze; Allein die Berechtigungen der Zieltabelle reichen nicht aus. Für delegierte Tastenkombinationen verwendet der Zielzugriff die konfigurierte Verbindungsidentität. Details finden Sie unter OneLake Shortcut Security.

Fehler behandeln und Anfragen diagnostizieren

Bei einer erfolglosen Anfrage inspizieren Sie den HTTP-Status und die JSON-Fehlerantwort. Der Error Contract hat folgende Form; die Code- und Nachrichtenplatzhalter sind keine dienstspezifischen Fehlerwerte:

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

Das Objekt error kann auch ein details und ein target-Array enthalten. Jedes Detail enthält ein code und message, und kann ein target enthalten. Der Vertrag zählt keine operation-spezifischen Fehlercodes oder Statuscodes auf.

Für Diagnostik kannst du einen optionalen x-ms-root-activity-id Header mit einer GUID senden. Nehmen Sie den Antwortheader x-ms-root-activity-id auf, wenn Sie Probleme mit einer Anfrage untersuchen. Protokolliere den Bearer-Token nicht.

Verwandte Inhalte

• Überblick über OneLake-Tabellen-APIs.
• OneLake Iceberg Metadata API.
• OneLake Delta Metadaten-API.
• OneLake-Verknüpfungen.
• Lesen Sie die OneLake-Tabellendaten.