Lee y escribe metadatos adicionales de la tabla (vista previa)

Utiliza la API de metadatos adicionales de tabla de OneLake para leer y escribir descripciones y etiquetas clave-valor para una tabla y sus columnas. Esta API utiliza una ruta REST común en lugar de la ruta de Iceberg REST Catalog o de las rutas compatibles con Unity Catalog.

Por ejemplo, añadir una descripción que explique el propósito empresarial de una tabla, etiquetar la tabla con su equipo propietario y explicar cómo interpretar una columna. Estas operaciones funcionan con metadatos descriptivos, no con filas de tabla. Para recuperar filas, utiliza la API de lectura de tablas de OneLake.

Importante

La API adicional de metadatos de tablas está en vista previa pública. Las características y el comportamiento pueden cambiar antes de la disponibilidad general.

Prerequisites

  • Completar los requisitos previos de la API de tablas compartidas y los pasos de autenticación.
  • Identifica el ID del espacio de trabajo, el ID del elemento, el nombre del esquema y el nombre de la tabla de tu tabla objetivo.
  • Identifica las columnas existentes que quieres describir o etiquetar.
  • Utiliza una identidad con los permisos necesarios para leer o escribir metadatos para la tabla objetivo.

Los ejemplos utilizan una tabla nombrada sales en el dbo esquema y una columna existente llamada customer_id. Sustituye estos nombres por los de tu tabla.

Endpoint y operaciones

Utiliza la siguiente URL base:

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

Ambas operaciones utilizan la misma ruta:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata
Método Operation Respuesta exitosa
GET Lee metadatos adicionales para una tabla y sus columnas. 200 OK con una respuesta de metadatos JSON.
POST Establece metadatos adicionales para una tabla y sus columnas. 200 OK con una respuesta de metadatos JSON.

Usa GUIDs para <WorkspaceID> y <ItemID>. Codifique los nombres de esquema y tabla en direcciones URL como segmentos de ruta individuales. Incluye un Authorization: Bearer <Token> encabezado con un token de acceso Microsoft Entra ID para la https://storage.azure.com/ audiencia. Para POST, también incluye Content-Type: application/json.

Descripciones y etiquetas soportadas

Utiliza estos campos en una POST solicitud:

Field Type Descripción y límites
description String La descripción de la tabla. Máximo de 1024 caracteres.
tags Objeto Las etiquetas de tabla son pares clave-valor en forma de cadena. Cada clave tiene un máximo de 128 caracteres, y cada valor tiene un máximo de 256 caracteres.
columns Array Metadatos adicionales para las columnas que identifiques en la solicitud.
columns[].columnName String Nombre de una columna existente. Utiliza este campo para identificar la columna que quieres describir o etiquetar.
columns[].description String La descripción de la columna. Máximo de 1024 caracteres.
columns[].tags Objeto Etiquetas de columna como pares clave-valor de cadena. Los límites de clave y valor son los mismos que para las etiquetas de tabla.

Lea metadatos adicionales

Envía una petición GET para obtener metadatos a nivel de tabla y de columna.

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

Una solicitud exitosa devuelve 200 OK. El siguiente JSON muestra el formato de respuesta:

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

Los valores, nombres de columnas y campos en tu respuesta dependen de la tabla objetivo y sus metadatos. El contrato no exige que todos los campos estén presentes.

Escribe metadatos adicionales

Envía una POST solicitud con un cuerpo JSON para reemplazar los metadatos adicionales de la tabla.

Importante

POST reemplaza los metadatos adicionales existentes; no es una actualización parcial. Incluye la descripción de la tabla, las etiquetas de la tabla y las descripciones y las etiquetas de las columnas que quieras mantener en cada petición. Por ejemplo, una solicitud que contiene solo description establece la descripción de la tabla y elimina las etiquetas existentes de la tabla y todas las descripciones y etiquetas de columnas.

Este ejemplo establece una descripción de tabla y etiquetas, además de una descripción y etiqueta para customer_id. Identifica la columna usando 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

Cuerpo de la solicitud:

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

Una solicitud exitosa devuelve 200 OK con una respuesta adicional de metadatos. Por ejemplo:

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

Envía otra GET petición para comprobar los metadatos después de la escritura.

Conservar los metadatos existentes

Para cambiar descripciones o etiquetas seleccionadas sin eliminar otros metadatos, utiliza una secuencia de lectura-modifica-escritura:

  1. Envía una GET solicitud para leer los metadatos adicionales actuales.
  2. Cambia las descripciones o etiquetas que quieres actualizar en los metadatos devueltos. Conserva los otros campos, claves de etiquetas y entradas de columna que quieras conservar.
  3. Envía los metadatos completos y actualizados en una solicitud POST.
  4. Envía otra GET solicitud para confirmar el resultado.

Coordina actualizaciones concurrentes de metadatos para que no ocurra otra escritura entre tus solicitudes GET y POST.

Lee y escribe metadatos con Python

El siguiente ejemplo autentica con Microsoft Entra ID, lee los metadatos actuales, actualiza descripciones y etiquetas seleccionadas mientras se conservan otros metadatos, y vuelve a leer los metadatos. No llama a una API de catálogo específica de formato ni solicita credenciales de almacenamiento.

Caution

Al ejecutar esta muestra, se escriben metadatos. Usa una tabla de pruebas y una columna, y sustituye las descripciones y etiquetas de ejemplo antes de ejecutarlo. La muestra conserva los metadatos de su lectura inicial, pero puede sobrescribir los cambios realizados por otro cliente antes de escribir.

Instale las dependencias:

python -m pip install azure-identity requests

Configura un método de autenticación de identidad de Azure compatible, como iniciar sesión localmente con CLI de Azure, antes de ejecutar la muestra.

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

El argumento json establece la cabecera Content-Type: application/json de la solicitud. La muestra genera una excepción por una respuesta HTTP fallida en lugar de tratarla como una actualización de metadatos exitosa.

Trabajar con metadatos a través de accesos directos de OneLake

Para un atajo interno de una tabla OneLake, utiliza el ID del espacio de trabajo, el ID del elemento, el nombre del esquema y el nombre de la tabla del acceso directo en la misma ruta adicional de metadatos. Las operaciones trabajan con los metadatos de la tabla objetivo, no con una copia separada de los metadatos para el acceso directo:

  • GET devuelve los metadatos adicionales de la tabla objetivo, incluyendo sus descripciones y etiquetas.
  • POST reemplaza los metadatos adicionales de la tabla de destino. Los cambios son visibles cuando lees los metadatos a través del atajo o de la tabla objetivo.

Por ejemplo, si un acceso directo llamado sales_shortcut apunta a sales, lee los metadatos de la tabla fuente a través del atajo usando esta petición:

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

Para actualizar los metadatos a través del acceso directo, envía una POST solicitud a la misma URL. La semántica de reemplazo también se aplica a la tabla objetivo: una petición solo descriptiva mediante el método abreviado elimina las etiquetas existentes y los metadatos de columna de la tabla objetivo. Utiliza la secuencia de lectura-modifica-escritura para conservar los metadatos que quieras conservar.

El acceso requiere permisos para la operación tanto en la ruta de acceso directo como en la ruta de la tabla objetivo. Para accesos directos passthrough, tu identidad necesita ambos conjuntos de permisos; los permisos de la tabla de destino por sí solos no son suficientes. Para atajos delegados, el acceso destino utiliza la identidad de conexión configurada. Para más detalles, consulta OneLake Shortcut Security.

Gestionar errores y diagnosticar solicitudes

Para una solicitud fallida, inspecciona el estado HTTP y la respuesta de error JSON. El contrato de error tiene la siguiente forma; los marcadores de posición de código y mensaje no son valores específicos de error de servicio:

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

El objeto error también puede incluir un target y una matriz details. Cada detalle contiene un code y un message, y puede incluir un target. El contrato no enumera códigos de error ni códigos de estado específicos de la operación.

Para diagnósticos, puedes enviar un encabezado opcional x-ms-root-activity-id que contenga un GUID. Registra el x-ms-root-activity-id encabezado de respuesta cuando resuelvas una solicitud. No registres el token bearer.