Leia e escreva metadados adicionais da tabela (pré-visualização)

Utilize a API de metadados adicionais de tabela do OneLake para ler e escrever descrições e etiquetas de chave-valor para uma tabela e as suas colunas. Esta API utiliza uma rota REST comum em vez das rotas compatíveis com o Iceberg REST Catalog ou Unity Catalog.

Por exemplo, adicione uma descrição que explique o propósito comercial de uma tabela, identifique a tabela com a sua equipa proprietária e descreva como interpretar uma coluna. Estas operações funcionam com metadados descritivos, não com linhas de tabela. Para recuperar linhas, use a API de leitura de tabelas OneLake.

Prerequisites

• Complete os pré-requisitos da API de tabelas partilhadas e os passos de autenticação.
• Identifique o ID do espaço de trabalho, o ID do item, o nome do esquema e o nome da tabela para a sua tabela alvo.
• Identifique as colunas existentes que pretende descrever ou etiquetar.
• Use uma identidade com as permissões necessárias para ler ou escrever metadados para a tabela de destino.

Os exemplos usam uma tabela nomeada sales no dbo esquema e uma coluna existente chamada customer_id. Substitui esses nomes pelos nomes da tua tabela.

Ponto final e operações

Utilize o seguinte URL base:

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

Ambas as operações utilizam a mesma rota:

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

Utilize GUIDs para <WorkspaceID> e <ItemID>. Codifique por URL os nomes do esquema e das tabelas como segmentos de caminho individuais. Inclua um Authorization: Bearer <Token> cabeçalho com um token de acesso Microsoft Entra ID para a audiência https://storage.azure.com/. Para POST, inclua também Content-Type: application/json.

Descrições e etiquetas suportadas

Utilize estes campos num pedido POST:

Leia metadados adicionais

Envie um GET pedido para obter metadados ao nível da tabela e da coluna.

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

Um pedido bem-sucedido retorna 200 OK. O JSON seguinte mostra o formato de resposta:

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

Os valores, nomes das colunas e campos na sua resposta dependem da tabela de destino e dos seus metadados. O contrato não exige que todos os campos estejam presentes.

Escrever metadados adicionais

Envie um POST pedido com um corpo JSON para substituir os metadados adicionais da tabela.

Este exemplo define uma descrição de tabela e etiquetas, além de uma descrição e etiqueta para customer_id. Identifica a coluna 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

Corpo do pedido:

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

Um pedido bem-sucedido retorna 200 OK com uma resposta adicional de metadados. Por exemplo:

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

Envie outra GET solicitação para verificar os metadados após a escrita.

Preservar metadados existentes

Para alterar descrições ou etiquetas selecionadas sem remover outros metadados, use uma sequência de leitura-modificação-escrita:

1. Envie um GET pedido para ler os metadados adicionais atuais.
2. Altera as descrições ou etiquetas que pretendes atualizar nos metadados devolvidos. Mantém os outros campos, as chaves de etiquetas e as entradas das colunas que queres manter.
3. Envie os metadados completos atualizados num POST pedido.
4. Envie outro GET pedido para confirmar o resultado.

Coordena atualizações de metadados simultâneas para que não ocorra outra escrita entre as tuas requisições GET e POST.

Leia e escreva metadados com Python

O exemplo seguinte autentica com o Microsoft Entra ID, lê os metadados atuais, atualiza descrições e etiquetas selecionadas enquanto preserva outros metadados, e lê novamente os metadados. Não chama uma API de catálogo específica de formato nem solicita credenciais de armazenamento.

Instale os pacotes de dependências:

python -m pip install azure-identity requests

Configure um método de autenticação Azure Identity suportado, como iniciar sessão localmente com CLI do Azure, antes de executar o exemplo.

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

O json argumento define o Content-Type: application/json cabeçalho do pedido. O exemplo levanta uma exceção para uma resposta HTTP falhada, em vez de a tratar como uma atualização de metadados bem-sucedida.

Trabalhar com metadados através de atalhos OneLake

Para um atalho interno de tabela OneLake, use o ID do espaço de trabalho, o ID do item, o nome do esquema e o nome da tabela do atalho na mesma rota adicional de metadados. As operações funcionam com os metadados da tabela de destino, não com uma cópia separada dos metadados para o atalho:

• GET devolve os metadados adicionais da tabela de destino, incluindo as suas descrições e etiquetas.
• POST substitui os metadados adicionais da tabela alvo. As alterações são visíveis quando lês metadados através do atalho ou da tabela de destino.

Por exemplo, se um atalho chamado sales_shortcut aponta para sales, leia os metadados da tabela de origem através do atalho usando este pedido:

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

Para atualizar os metadados através do atalho, envie um POST pedido HTTP para o mesmo URL. A semântica de substituição também se aplica à tabela de destino: um pedido apenas de descrição através do atalho remove as etiquetas e metadados de coluna existentes da tabela de destino. Utilize a sequência de leitura-modificação-escrita para reter os metadados que pretende manter.

O acesso requer permissões para a operação tanto no caminho de atalho como no caminho da tabela de destino. Para atalhos passthrough, a sua identidade precisa de ambos os conjuntos de permissões; permissões de tabela alvo por si só não são suficientes. Para atalhos delegados, o acesso ao destino utiliza a identidade de ligação configurada. Para mais detalhes, consulte OneLake shortcut security.

Tratar erros e diagnosticar solicitações

Para um pedido não bem-sucedido, inspecione o estado HTTP e a resposta de erro JSON. O contrato de erro tem a seguinte forma; os marcadores de código e mensagem não são valores específicos de erro de serviço:

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

O error objeto pode também incluir um target e um details array. Cada detalhe contém um code e um message, e pode incluir um target. O contrato não enumera códigos de erro ou códigos de estado específicos da operação.

Para diagnósticos, pode enviar um cabeçalho opcional x-ms-root-activity-id contendo um GUID. Grave o cabeçalho de resposta x-ms-root-activity-id quando diagnosticar problemas num pedido. Não registe o token bearer.

Conteúdo relacionado

• Visão geral das APIs de tabelas OneLake.
• API de metadados OneLake Iceberg.
• OneLake Delta Metadata API.
• Atalhos do OneLake.
• Leia os dados das tabelas OneLake.