Czytaj i zapisuj dodatkowe metadane tabeli (podgląd)

Użyj dodatkowego API metadanych tabel OneLake do odczytu i zapisu opisów oraz tagów klucz-wartość dla tabeli i jej kolumn. To API wykorzystuje wspólną trasę REST zamiast tras zgodnych z Iceberg REST Catalog lub Unity Catalog.

Na przykład dodaj opis wyjaśniający cel biznesowy tabeli, oznacz tabelę zespołem odpowiedzialnym i opisz, jak interpretować kolumnę. Operacje te działają na metadanych opisowych, a nie na wierszach tabeli. Aby pobrać wiersze, użyj API do czytania tabel OneLake.

Important

Dodatkowe API metadanych tabel jest dostępne w podglądzie publicznym. Funkcje i zachowanie mogą ulec zmianie przed ogólną dostępnością.

Prerequisites

  • Wypełnij wymagania API i kroki uwierzytelniania dotyczące wspólnej tabeli.
  • Zidentyfikuj identyfikator przestrzeni roboczej, identyfikator elementu, nazwę schematu oraz nazwę tabeli docelowej.
  • Zidentyfikuj istniejące kolumny, które chcesz opisać lub oznaczyć.
  • Użyj tożsamości z uprawnieniami wymaganymi do odczytu lub zapisu metadanych dla docelowej tabeli.

Przykłady wykorzystują tabelę nazwaną sales w schemie dbo oraz istniejącą kolumnę o nazwie customer_id. Zamień te nazwy na nazwy dla twojej tabeli.

Endpoint i operacje

Użyj poniższego bazowego adresu URL:

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

Obie operacje korzystają z tej samej trasy:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata
Method Operation Odpowiedź pomyślna
GET Przeczytaj dodatkowe metadane dotyczące tabeli i jej kolumn. 200 OK z odpowiedzią zawierającą metadane JSON.
POST Ustaw dodatkowe metadane dla tabeli i jej kolumn. 200 OK z odpowiedzią zawierającą metadane JSON.

Używaj GUIDów dla <WorkspaceID> i <ItemID>. Poddaj kodowaniu URL nazwę schematu i nazwę tabeli jako pojedyncze segmenty ścieżki. Dołącz nagłówek Authorization: Bearer <Token> z tokenem dostępu Microsoft Entra ID dla odbiorcy https://storage.azure.com/. Dla POST, również uwzględnij Content-Type: application/json.

Obsługiwane opisy i tagi

Użyj tych pól w żądaniu POST :

Field Typ Opis i ograniczenia
description String Opis tabeli. Maksymalnie 1024 znaki.
tags Obiekt Tagi tabeli jako pary klucz-wartość jako ciągi znaków. Każdy klucz ma maksymalnie 128 znaków, a każda wartość to maksymalnie 256 znaków.
columns Array Dodatkowe metadane dla kolumn, które zidentyfikowałeś w żądaniu.
columns[].columnName String Nazwa istniejącej kolumny. Użyj tego pola, aby zidentyfikować kolumnę, którą chcesz opisać lub oznaczyć.
columns[].description String Opis kolumny. Maksymalnie 1024 znaki.
columns[].tags Obiekt Tagi kolumnowe jako pary klucz-wartość ciągu znaków. Limity klucza i wartości są takie same jak w przypadku tagów tabeli.

Przeczytaj dodatkowe metadane

Wyślij żądanie GET, aby uzyskać metadane na poziomie tabeli i kolumn.

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

Pomyślne żądanie zwraca 200 OK. Poniższy JSON pokazuje format odpowiedzi:

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

Wartości, nazwy kolumn i pola w odpowiedzi zależą od docelowej tabeli i jej metadanych. Umowa nie wymaga, aby obecne były wszystkie pola.

Wpisz dodatkowe metadane

Wyślij żądanie POST z ciałem JSON, aby zastąpić dodatkowe metadane tabeli.

Important

POST zastępuje istniejące dodatkowe metadane; nie jest to częściowa aktualizacja. Dołącz opis tabeli, tagi tabel oraz opisy kolumn i tagi, które chcesz zachować w każdym żądaniu. Na przykład żądanie, które zawiera tylko description, ustawia opis tabeli i usuwa istniejące tagi tabeli oraz wszystkie opisy i tagi kolumn.

Ten przykład ustawia opis tabeli i tagi, plus opis i tag dla customer_id. Identyfikuje kolumnę, używając 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

Treść żądania:

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

Pomyślne żądanie zwraca 200 OK wraz z dodatkową odpowiedzią metadanych. Przykład:

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

Wyślij kolejne GET żądanie, aby sprawdzić metadane po zapisie.

Zachowaj istniejące metadane

Aby zmienić wybrane opisy lub tagi bez usuwania innych metadanych, użyj sekwencji czytaj-modyfikuj-zapisuj:

  1. Wyślij żądanie GET odczytu aktualnych dodatkowych metadanych.
  2. Zmień opisy lub tagi, które chcesz zaktualizować w zwróconych metadanych. Zachowaj pozostałe pola, klucze tagów i wpisy kolumnowe, które chcesz zachować.
  3. Wyślij kompletne, zaktualizowane metadane w żądaniu POST.
  4. Wyślij kolejne GET żądanie, aby potwierdzić wynik.

Koordynuj jednoczesne aktualizacje metadanych, aby nie doszło do kolejnego zapisu między twoimi GET a POST żądaniami.

Czytaj i zapisuj metadane w Pythonie

Poniższy przykład uwierzytelnia się za pomocą Microsoft Entra ID, odczytuje aktualne metadane, aktualizuje wybrane opisy i tagi przy zachowaniu innych metadanych oraz ponownie odczytuje metadane. Nie wywołuje API katalogu specyficznego dla formatu ani nie żąda poświadczeń dostępu do pamięci masowej.

Caution

Uruchomienie tego przykładu zapisuje metadane. Użyj tabeli testowej i kolumny, a przed uruchomieniem zamień przykładowe opisy i tagi. Próbka zachowuje metadane z początkowego odczytu, ale może nadpisać zmiany wprowadzone przez innego klienta, zanim nastąpi zapis.

Zainstaluj zależności:

python -m pip install azure-identity requests

Skonfiguruj obsługiwaną metodę uwierzytelniania Azure Identity, na przykład logowanie lokalnie za pomocą Azure CLI, przed uruchomieniem próbki.

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

Argument json ustawia nagłówek Content-Type: application/json żądania. Próbka zgłasza wyjątek dla nieudanej odpowiedzi HTTP, zamiast traktować ją jako udaną aktualizację metadanych.

Praca z metadanymi za pomocą skrótów OneLake

Dla wewnętrznego skrótu tabeli OneLake użyj identyfikatora obszaru roboczego skrótu, identyfikatora elementu, nazwy schematu i nazwy tabeli w tej samej dodatkowej ścieżce metadanych. Operacje działają na metadanych tabeli docelowej, a nie na osobnej kopii metadanych dla skrótu:

  • GET zwraca dodatkowe metadane tabeli docelowej, w tym jej opisy i tagi.
  • POST zastępuje dodatkowe metadane tabeli docelowej. Zmiany są widoczne, gdy czytasz metadane przez skrót lub docelową tabelę.

Na przykład, jeśli skrót o nazwie sales_shortcut wskazuje na sales, przeczytaj metadane tabeli źródłowej przez skrót, używając tego żądania:

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

Aby zaktualizować metadane za pomocą skrótu, wyślij żądanie POST na ten sam adres URL. Semantyka zastępowania dotyczy także tabeli docelowej: żądanie tylko opisu za pomocą skrótu usuwa istniejące tagi i metadane kolumn tabeli docelowej. Użyj sekwencji czytaj-modyfikuj-zapisuj, aby zachować metadane, które chcesz zachować.

Dostęp wymaga uprawnień do operacji zarówno na ścieżce skrótu, jak i na ścieżce docelowej tabeli. W przypadku skrótów passthrough twoja tożsamość wymaga obu zestawów uprawnień; same uprawnienia do tabeli docelowej nie wystarczą. Dla skrótów delegowanych dostęp docelowy korzysta z skonfigurowanej tożsamości połączenia. Aby uzyskać szczegółowe informacje, zobacz zabezpieczenia skrótów OneLake.

Obsługa błędów i diagnozowanie żądań

W przypadku nieudanego żądania sprawdź status HTTP oraz odpowiedź błędu JSON. Kontrakt błędu ma następujący kształt; kod i symbole zastępcze komunikatu nie są konkretnymi wartościami błędu usługi:

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

Obiekt error może również zawierać tablicę target i tablicę details. Każdy szczegół zawiera code i message oraz może zawierać target. Umowa nie zawiera specyficznych dla operacji kodów błędów ani kodów statusu.

Do diagnostyki możesz wysłać opcjonalny x-ms-root-activity-id nagłówek zawierający GUID. Zapisz nagłówek odpowiedzi x-ms-root-activity-id, podczas rozwiązywania problemów z żądaniem. Nie zapisuj tokenu bearer.