Les og skriv ytterligere tabellmetadata (forhåndsvisning)

Bruk OneLake tilleggstabellmetadata-API for å lese og skrive beskrivelser og nøkkelverdi-tagger for en tabell og dens kolonner. Dette API-et bruker en felles REST-rute i stedet for Iceberg REST Catalog eller Unity Catalog-kompatible ruter.

For eksempel, legg til en beskrivelse som forklarer tabellens forretningsformål, merk tabellen med sitt eget team, og beskriver hvordan man tolker en kolonne. Disse operasjonene jobber med beskrivende metadata, ikke tabellrader. For å hente rader, bruk OneLake table read API.

Forutsetninger

• Fullfør forhåndskravene og autentiseringstrinnene for delte tabeller.
• Identifiser arbeidsområde-ID, element-ID, skjemanavn og tabellnavn for måltabellen din.
• Identifiser de eksisterende kolonnene du vil beskrive eller merke.
• Bruk en identitet med nødvendige tillatelser for å lese eller skrive metadata for måltabellen.

Eksemplene bruker en tabell som er navngitt sales i skjemaet dbo og en eksisterende kolonne kalt customer_id. Erstatt disse navnene med navnene på tabellen din.

Endepunkt og operasjoner

Bruk følgende grunn-URL:

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

Begge rutene bruker samme rute:

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

Bruk GUID-er for <WorkspaceID> og <ItemID>. URL-kod skjema- og tabellnavnene som individuelle stisegmenter. Inkluder en Authorization: Bearer <Token> header med en Microsoft Entra ID-tilgangstoken for målgruppenhttps://storage.azure.com/. For POST, inkluderer Content-Type: application/jsonogså .

Støttede beskrivelser og tagger

Bruk disse feltene i en POST forespørsel:

Les ytterligere metadata

Send en GET forespørsel om å hente metadata på tabell- og kolonnenivå.

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

En vellykket forespørsel returnerer 200 OK. Følgende JSON viser responsformatet:

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

Verdiene, kolonnenavnene og feltene i svaret ditt avhenger av måltabellen og dens metadata. Kontrakten krever ikke at alle felt er til stede.

Skriv ytterligere metadata

Send en POST forespørsel med en JSON-kropp for å erstatte tabellens tilleggsmetadata.

Dette eksempelet setter en tabellbeskrivelse og tagger, pluss en beskrivelse og tagg for customer_id. Den identifiserer kolonnen ved å bruke 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

Forespørselstekst:

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

En vellykket forespørsel returneres 200 OK med et ekstra metadata-svar. Eksempel:

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

Send en ny GET forespørsel for å sjekke metadataene etter skrivingen.

Bevar eksisterende metadata

For å endre utvalgte beskrivelser eller tagger uten å fjerne annen metadata, bruk en les-modifiser-skrive-sekvens:

1. Send en GET forespørsel om å lese de nåværende tilleggsmetadataene.
2. Endre beskrivelsene eller taggene du ønsker å oppdatere i de returnerte metadataene. Behold de andre feltene, taggnøklene og kolonneoppføringene du vil beholde.
3. Send fullstendig oppdatert metadata i en POST forespørsel.
4. Send en ny GET forespørsel for å bekrefte resultatet.

Koordiner samtidige metadataoppdateringer slik at det ikke skjer en ny skriving mellom din GET og POST forespørsler.

Les og skriv metadata med Python

Følgende eksempel autentiseres med Microsoft Entra ID, leser gjeldende metadata, oppdaterer utvalgte beskrivelser og tagger samtidig som annen metadata bevares, og leser metadataene på nytt. Den kaller ikke et formatspesifikt katalog-API eller ber om lagringslegitimasjon.

Installer avhengighetene:

python -m pip install azure-identity requests

Konfigurer en støttet Azure Identity-autentiseringsmetode, som å logge inn lokalt med Azure CLI, før du kjører eksemplet.

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

Argumentet json setter forespørselsheaderen Content-Type: application/json . Utvalget oppretter et unntak for et mislykket HTTP-svar i stedet for å behandle det som en vellykket metadataoppdatering.

Arbeid med metadata gjennom OneLake-snarveier

For en intern OneLake-tabellsnarvei, bruk snarveiens arbeidsområde-ID, element-ID, skjemanavn og tabellnavn i samme ekstra metadata-rute. Operasjonene fungerer med måltabellens metadata, ikke en separat kopi av metadata for snarveien:

• GET returnerer måltabellens tilleggsmetadata, inkludert beskrivelser og tagger.
• POST erstatter måltabellens tilleggsmetadata. Endringene er synlige når du leser metadata gjennom enten snarveien eller måltabellen.

For eksempel, hvis en snarvei med navnet peker sales_shortcut til sales, les kildetabellens metadata gjennom snarveien ved å bruke denne forespørselen:

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

For å oppdatere metadata via snarveien, send en POST forespørsel til samme URL. Erstatningssemantikken gjelder også for måltabellen: en beskrivelsesbasert forespørsel via snarveien fjerner måltabellens eksisterende tagger og kolonnemetadata. Bruk les-modifiser-skrive-sekvensen for å beholde metadata du ønsker å beholde.

Tilgang krever tillatelser for operasjonen både på snarveistien og måltabellen. For snarveier trenger identiteten din begge sett med tillatelser; måltabell-tillatelser alene er ikke tilstrekkelig. For delegerte snarveier bruker måltilgangen den konfigurerte tilkoblingsidentiteten. For detaljer, se OneLake snarvei sikkerhet.

Håndter feil og diagnostiser forespørsler

For en mislykket forespørsel, sjekk HTTP-statusen og JSON-feilsvaret. Feilkontrakten har følgende form; kode- og meldingsplassholdere er ikke spesifikke tjenestefeilverdier:

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

Objektet error kan også inkludere a target og et details array. Hver detalj inneholder en code og message, og kan inkludere en target. Kontrakten lister ikke opp operasjonsspesifikke feilkoder eller statuskoder.

For diagnostikk kan du sende en valgfri x-ms-root-activity-id header som inneholder en GUID. Ta opp x-ms-root-activity-id svarheaderen når du feilsøker en forespørsel. Ikke logg bærertokenet.

Relatert innhold

• Oversikt over OneLake-tabell-API-er.
• OneLake Iceberg metadata API.
• OneLake Delta metadata-API.
• OneLake-snarveier.
• Les OneLake-tabelldata.