Læs og skriv yderligere tabelmetadata (forhåndsvisning)

Brug OneLake additional table metadata API til at læse og skrive beskrivelser og nøgleværdi-tags for en tabel og dens kolonner. Dette API bruger en fælles REST-rute i stedet for Iceberg REST Catalog eller Unity Catalog-kompatible ruter.

For eksempel kan du tilføje en beskrivelse, der forklarer en tabels forretningsformål, tagge tabellen med dens eget team og beskrive, hvordan en kolonne skal fortolkes. Disse operationer arbejder med beskrivende metadata, ikke tabelrækker. For at hente rækker skal du bruge OneLake table read API.

Forudsætninger

• Fuldfør forudsætningerne for shared table API og autentificeringstrin.
• Identificér arbejdsområde-ID, artikel-ID, skemanavn og tabelnavn for din måltabel.
• Identificer de eksisterende kolonner, du vil beskrive eller tagge.
• Brug en identitet med de nødvendige tilladelser til at læse eller skrive metadata for måltabelen.

Eksemplerne bruger en tabel navngivet sales i skemaet dbo og en eksisterende kolonne kaldet customer_id. Erstat disse navne med navnene til din tabel.

Endepunkt og operationer

Brug følgende basis-URL:

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

Begge ruter benytter samme rute:

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

Brug GUIDs til <WorkspaceID> og <ItemID>. URL-kod skema- og tabelnavnene som individuelle stisegmenter. Inkluder en Authorization: Bearer <Token> header med en Microsoft Entra ID-adgangstoken til målgruppenhttps://storage.azure.com/. For POST, inkluderer Content-Type: application/jsonogså .

Understøttede beskrivelser og tags

Brug disse felter i en POST anmodning:

Læs yderligere metadata

Send en GET anmodning om at få metadata på tabel- og kolonneniveau.

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

En vellykket anmodning returnerer 200 OK. Følgende JSON viser svarformatet:

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

Værdierne, kolonnenavnene og felterne i dit svar afhænger af måltabellen og dens metadata. Kontrakten kræver ikke, at alle felter er til stede.

Skriv yderligere metadata

Send en POST anmodning med en JSON-body for at erstatte tabellens ekstra metadata.

Dette eksempel sætter en tabelbeskrivelse og tags samt en beskrivelse og tag for customer_id. Den identificerer kolonnen ved at bruge 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ørgselskrop

{
  "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 anmodning returneres 200 OK med et yderligere metadata-svar. F.eks.:

{
  "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 anmodning om at tjekke metadata efter skrivningen.

Bevar eksisterende metadata

For at ændre udvalgte beskrivelser eller tags uden at fjerne anden metadata, brug en læs-modificer-skriv-sekvens:

1. Send en GET anmodning om at læse de aktuelle yderligere metadata.
2. Ændr de beskrivelser eller tags, du vil opdatere i de returnerede metadata. Behold de andre felter, tag-nøgler og kolonneposter, som du vil beholde.
3. Send de komplette opdaterede metadata i en POST anmodning.
4. Send en ny GET anmodning for at bekræfte resultatet.

Koordiner samtidige metadataopdateringer, så der ikke sker endnu en skrivning mellem dine GET og POST anmodningerne.

Læs og skriv metadata med Python

Følgende eksempel autentificeres med Microsoft Entra ID, læser de aktuelle metadata, opdaterer udvalgte beskrivelser og tags samtidig med at andre metadata bevares, og læser metadataene igen. Den kalder ikke et format-specifikt katalog-API eller anmoder om lagringsoplysninger.

Installér afhængighederne:

python -m pip install azure-identity requests

Konfigurér en understøttet Azure Identity-autentificeringsmetode, såsom at logge ind lokalt med Azure CLI, før du kø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 sætter Content-Type: application/json anmodningsheaderen. Eksemplet fremsætter en undtagelse for et mislykket HTTP-svar i stedet for at behandle det som en vellykket metadataopdatering.

Arbejd med metadata via OneLake-genveje

For en intern OneLake-tabelgenvej skal genvejen bruges arbejdsområdets ID, item ID, skemanavn og tabelnavn i samme ekstra metadata-rute. Operationerne arbejder med måltabelens metadata, ikke en separat kopi af metadata til genvejen:

• GET returnerer måltabelens yderligere metadata, inklusive dens beskrivelser og tags.
• POST udskifter måltabelens yderligere metadata. Ændringerne er synlige, når du læser metadata gennem enten genvejen eller måltabellen.

For eksempel, hvis en genvej med navnet sales_shortcut peger på sales, læs kildetabellens metadata gennem genvejen ved at bruge denne anmodning:

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

For at opdatere metadata via genvejen, send en POST anmodning til samme URL. Erstatningssemantikken gælder også for måltabellen: en beskrivelsesanmodning via genvejen fjerner måltabellens eksisterende tags og kolonnemetadata. Brug læs-modificer-skrive-sekvensen til at bevare metadata, som du vil beholde.

Adgang kræver tilladelser for operationen både på genvejsstien og måltabelstien. For genveje til passthrough har din identitet brug for begge sæt af tilladelser; måltabel-tilladelser alene er ikke tilstrækkelige. For delegerede genveje bruger måladgang den konfigurerede forbindelsesidentitet. For detaljer, se OneLake genvej sikkerhed.

Håndter fejl og diagnosticér anmodninger

For en mislykket anmodning skal HTTP-status og JSON-fejlsvaret inspiceres. Fejlkontrakten har følgende form; kode- og beskedpladsholderne er ikke specifikke servicefejlværdier:

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

Objektet error kan også inkludere et target og et details array. Hver detalje indeholder en code og message, og kan inkludere en target. Kontrakten opregner ikke operation-specifikke fejlkoder eller statuskoder.

Til diagnostik kan du sende en valgfri x-ms-root-activity-id header, der indeholder en GUID. Optag x-ms-root-activity-id svarheaderen, når du fejlsøger en forespørgsel. Log ikke bærertokenet.

Relateret indhold

• Oversigt over OneLake table API'er.
• OneLake Iceberg metadata API.
• OneLake Delta metadata API.
• OneLake genveje.
• Læs OneLake-tabeldata.