Lue ja kirjoita lisätaulumetatietoja (esikatselu)

Käytä OneLake-lisätaulun metatietorajapintaa lukeaksesi ja kirjoittaaksesi kuvauksia ja avainarvotunnisteita taululle ja sen sarakkeille. Tämä API käyttää yhteistä REST-reittiä Iceberg REST Catalog- tai Unity Catalog -yhteensopivien reittien sijaan.

Esimerkiksi lisää kuvaus, joka selittää taulukon liiketoimintatarkoituksen, merkitse taulu omistajatiimillä ja kuvaile, miten sarake tulkitaan. Nämä operaatiot toimivat kuvailevan metatiedon avulla, eivät taulukkoriveillä. Rivien hakemiseen käytetään OneLake-taulun lukurajapintaa.

Tärkeää

Lisätaulukko-metatietojen API on julkisessa esikatselussa. Ominaisuudet ja käyttäytyminen voivat muuttua ennen yleistä saatavuutta.

Vaatimukset

  • Suorita jaetun taulukon API-edellytykset ja todennusvaiheet.
  • Tunnista kohdetaulun työtilan ID, kohde-ID, skeeman nimi ja taulun nimi.
  • Tunnista olemassa olevat sarakkeet, joita haluat kuvata tai merkitä.
  • Käytä identiteettiä, jolla on tarvittavat oikeudet kohdetaulun metatietojen lukemiseen tai kirjoittamiseen.

Esimerkeissä käytetään kaaviossa salesdbo nimettyä taulukkoa ja olemassa olevaa saraketta nimeltä customer_id. Korvaa nämä nimet taulukkosi nimillä.

Päätepiste ja toiminnot

Käytä seuraavaa perus-URL-osoitetta:

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

Molemmat operaatiot käyttävät samaa reittiä:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata
Menetelmä Toiminto Onnistunut vastaus
GET Lue lisätietoja taulukosta ja sen sarakkeista. 200 OK JSON-metatietovastauksella.
POST Aseta lisämetatietoja taulukolle ja sen sarakkeille. 200 OK JSON-metatietovastauksella.

Käytä GUIDeja ja <WorkspaceID><ItemID>. URL-koodaa skeeman ja taulukoiden nimet yksittäisinä polkusegmentteinä. Sisällytä otsikkoAuthorization: Bearer <Token>, jossa on Microsoft Entra ID access token yleisöllehttps://storage.azure.com/. Jos POST, sisällytä Content-Type: application/jsonmyös .

Tuetut kuvaukset ja tunnisteet

Käytä näitä kenttiä pyynnössä POST :

Kenttä Tyyppi Kuvaus ja rajat
description Merkkijono Pöydän kuvaus. Enintään 1 024 merkkiä.
tags Objekti Taulukon tunnisteet merkkijonon avain-arvopareina. Jokaisessa näppäimessä on enintään 128 merkkiä ja jokaisella arvolla enintään 256 merkkiä.
columns Array Lisämetatiedot niille sarakkeille, jotka tunnistat pyynnössä.
columns[].columnName Merkkijono Olemassa olevan sarakkeen nimi. Käytä tätä kenttää tunnistaaksesi sarakkeen, jonka haluat kuvata tai merkitä.
columns[].description Merkkijono Kolumnin kuvaus. Enintään 1 024 merkkiä.
columns[].tags Objekti Saraketunnisteet merkkijonon avain-arvopareina. Avain- ja arvorajat ovat samat kuin taulukkotunnisteissa.

Lue lisää metatietoja

Lähetä GET pyyntö saadaksesi taulukkotason ja sarakkeen metatietoja.

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

Onnistunut pyyntö palautuu 200 OK. Seuraava JSON näyttää vastausmuodon:

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

Vastauksesi arvot, sarakkeennimet ja kentät riippuvat kohdetaulukosta ja sen metatiedoista. Sopimus ei vaadi, että kaikki alat ovat läsnä.

Kirjoita lisämetatietoja

Lähetä POST pyyntö JSON-rungolle korvaamaan taulun lisämetatiedot.

Tärkeää

POST korvaa olemassa olevat lisämetatiedot; se ei ole osittainen päivitys. Sisällytä taulukon kuvaus, taulukkotunnisteet sekä sarakkeiden kuvaukset ja tagit, jotka haluat säilyttää jokaiseen pyyntöön. Esimerkiksi pyyntö, joka sisältää vain description taulukon kuvauksen ja poistaa olemassa olevat taulukkotunnisteet sekä kaikki sarakkeiden kuvaukset ja tagit.

Tämä esimerkki sisältää taulukon kuvauksen ja tunnisteet sekä kuvauksen ja tagin .customer_id Se tunnistaa sarakkeen käyttämällä 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

Pyynnön runko:

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

Onnistunut pyyntö palauttaa 200 OK lisämetatietovastauksen. Esimerkiksi:

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

Lähetä toinen GET pyyntö tarkistaaksesi metatiedot kirjoituksen jälkeen.

Säilytä olemassa oleva metadata

Valittujen kuvausten tai tunnisteiden muuttamiseksi ilman muiden metatietojen poistamista käytä read-modify-write -sekvenssiä:

  1. Lähetä GET pyyntö lukea nykyiset lisämetatiedot.
  2. Muuta kuvaukset tai tagit, jotka haluat päivittää palautetussa metadatassa. Säilytä muut kentät, tag-avaimet ja sarakemerkinnät, jotka haluat säilyttää.
  3. Lähetä täydelliset päivitetyt metatiedot POST pyynnössä.
  4. Lähetä toinen GET pyyntö varmistaaksesi tuloksen.

Koordinoi samanaikaiset metatietojen päivitykset, jotta uusi kirjoitus ei tapahdu sinun GET ja POST pyyntöjen välillä.

Metatietojen lukeminen ja kirjoittaminen Python:lla

Seuraava esimerkki autentikoidaan Microsoft Entra ID:llä, lukee ajantasaiset metatiedot, päivittää valitut kuvaukset ja tagit säilyttäen muut metatiedot ja lukee metatiedot uudelleen. Se ei kutsu formaattikohtaista luettelo-API:ta eikä pyydä tallennustietoja.

Varoitus

Tämän näytteen ajaminen kirjoittaa metatietoja. Käytä testitaulukkoa ja -saraketta sekä korvaa esimerkkikuvaukset ja tagit ennen kuin suoritat sen. Näyte säilyttää metatiedot alkuperäisestä lukemisesta, mutta se voi korvata toisen asiakkaan ennen kirjoitusta tekemät muutokset.

Asenna riippuvuudet:

python -m pip install azure-identity requests

Konfiguroi tuettu Azure Identity -todennusmenetelmä, kuten kirjautuminen paikallisesti Azure CLI:llä ennen näytteen suorittamista.

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

Argumentti json asettaa Content-Type: application/json pyynnön otsikon. Otos nostaa poikkeuksen epäonnistuneelle HTTP-vastaukselle sen sijaan, että sitä käsiteltäisiin onnistuneena metatietopäivityksenä.

Työskentely metatietojen kanssa OneLake-pikanäppäimillä

Sisäisessä OneLake-taulun pikakuvakkeessa käytä pikakuvakkeen työtilan ID:tä, kohde-ID:tä, skeeman nimeä ja taulun nimeä samassa lisämetatietoreitissä. Operaatiot toimivat kohdetaulun metatietojen kanssa, eivät erillisen pikakuvakkeen metatietojen kopion kanssa:

  • GET palauttaa kohdetaulun lisämetatiedot, mukaan lukien kuvaukset ja tunnisteet.
  • POST korvaa kohdetaulukon lisämetatiedot. Muutokset näkyvät, kun luet metatietoja joko pikakuvakkeen tai kohdetaulukon kautta.

Esimerkiksi, jos pikakuvake nimeltä sales_shortcut osoittaa , saleslue lähdetaulun metatiedot pikakuvakkeen kautta käyttämällä tätä pyyntöä:

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

Metatietojen päivittämiseksi pikakuvakkeen kautta lähetä POST pyyntö samalle URL-osoitteelle. Korvaava semantiikka pätee myös kohdetauluun: pelkkä kuvauspyyntö pikakuvakkeen kautta poistaa kohdetaulukon olemassa olevat tagit ja sarakkeen metatiedot. Käytä read-modify-write -sekvenssiä säilyttääksesi haluamasi metatiedot.

Pääsy vaatii käyttöoikeudet sekä pikapolun että kohdetaulun polun operaatioon. Passthrough-pikakuvakkeisiin identiteettisi tarvitsee molemmat käyttöoikeudet; pelkkä kohdetaulun käyttöoikeudet eivät riitä. Delegoiduissa pikakuvakkeissa kohdepääsy käyttää konfiguroitua yhteysidentiteettiä. Lisätietoja löytyy OneLake-pikakuvakeiden tietoturvasta.

Käsittele virheitä ja diagnosoi pyyntöjä

Jos pyyntö epäonnistui, tarkista HTTP-tila ja JSON-virhevastaus. Virhesopimus on muotoiltaan seuraava; koodin ja viestin paikkamerkit eivät ole erityisiä palveluvirhearvoja:

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

Objekti error voi sisältää myös a target ja taulukon details . Jokainen yksityiskohta sisältää ja codemessage, ja voi sisältää myös .target Sopimus ei luettele operaatiokohtaisia virhekoodeja tai tilakoodeja.

Diagnostiikkaa varten voit lähettää vapaaehtoisen x-ms-root-activity-id otsikon, joka sisältää GUID:n. Tallenna vastauksen x-ms-root-activity-id otsikko vianetsinnän yhteydessä. Älä kirjaa kantajatokenia.

Liittyvä sisältö

  • Viimeksi päivitetty