Leia e escreva metadados adicionais de tabela (prévia)

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

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

Importante

A API adicional de metadados de tabela está em versão prévia pública. Os recursos e o comportamento podem mudar antes da disponibilidade geral.

Prerequisites

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

Ponto de extremidade e operações

Use a seguinte URL base:

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

Ambas as operações usam a mesma rota:

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata
Método Operation Resposta bem-sucedida
GET Leia metadados adicionais para uma tabela e suas colunas. 200 OK com uma resposta de metadados JSON.
POST Defina metadados adicionais para uma tabela e suas colunas. 200 OK com uma resposta de metadados JSON.

Use GUIDs para <WorkspaceID> e <ItemID>. Codifique em 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 https://storage.azure.com/ audiência. Para POST, também inclua Content-Type: application/json.

Descrições e tags suportadas

Use estes campos em uma solicitação POST:

Campo Tipo Descrição e limites
description String A descrição da tabela. Máximo de 1.024 caracteres.
tags Object Tags de tabela como pares chave-valor de string. Cada chave tem no máximo 128 caracteres, e cada valor tem no máximo 256 caracteres.
columns Array Metadados adicionais para as colunas que você identificar na solicitação.
columns[].columnName String O nome de uma coluna existente. Use este campo para identificar a coluna que você deseja descrever ou marcar.
columns[].description String A descrição da coluna. Máximo de 1.024 caracteres.
columns[].tags Object Etiquetas de coluna como pares chave-valor com chave e valor do tipo string. Os limites de chave e valor são os mesmos que para tags de tabela.

Leia metadados adicionais

Envie uma solicitação GET para obter metadados em nível de tabela e coluna.

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

Uma solicitação bem-sucedida retorna 200 OK. O JSON a seguir 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 alvo e seus metadados. O contrato não exige que todos os campos estejam presentes.

Escreva metadados adicionais

Envie uma POST solicitação com um corpo JSON para substituir os metadados adicionais da tabela.

Importante

POST substitui metadados adicionais existentes; não é uma atualização parcial. Inclua a descrição da tabela, as tags da tabela, e as descrições das colunas e tags que você deseja manter em cada solicitação. Por exemplo, uma solicitação que contém apenas description define a descrição da tabela e remove tags de tabela existentes e todas as descrições e tags das colunas.

Este exemplo define uma descrição da tabela e tags, além de uma descrição e uma tag para customer_id. Ele 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 da solicitação:

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

Uma solicitação bem-sucedida 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 tags selecionadas sem remover outros metadados, use uma sequência de leitura-modificação-escrita:

  1. Envie uma GET solicitação para ler os metadados adicionais atuais.
  2. Mude as descrições ou tags que você quer atualizar nos metadados retornados. Mantenha os outros campos, chaves de etiquetas e entradas de coluna que você quer manter.
  3. Envie os metadados completos e atualizados em uma solicitação POST.
  4. Envie outro GET pedido para confirmar o resultado.

Coordene atualizações simultâneas de metadados para que não ocorra outra gravação entre suas solicitações GET e POST.

Leia e escreva metadados com Python

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

Caution

Executar este exemplo grava metadados. Use uma tabela de teste e uma coluna, e substitua as descrições e tags de exemplo antes de executá-lo. A amostra preserva os metadados da leitura inicial, mas pode sobrescrever as alterações feitas por outro cliente antes da escrita.

Instale as dependências:

python -m pip install azure-identity requests

Configure um método de autenticação Azure Identity suportado, como fazer login localmente com CLI do Azure, antes de rodar o sample.

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 da solicitação. O exemplo gera uma exceção para uma resposta HTTP não bem-sucedida, em vez de tratá-la como uma atualização de metadados bem-sucedida.

Trabalhar com metadados por meio de atalhos OneLake

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

  • GET retorna os metadados adicionais da tabela de destino, incluindo suas descrições e tags.
  • POST substitui os metadados adicionais da tabela de destino. As mudanças ficam visíveis quando você lê os metadados tanto pelo atalho quanto pela 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 esta solicitação:

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 pelo atalho, envie uma POST solicitação para a mesma URL. A semântica de substituição também se aplica à tabela de destino: uma requisição apenas de descrição pelo atalho remove as tags e metadados de coluna existentes da tabela de destino. Use a sequência read-modify-write para reter os metadados que você deseja manter.

O acesso requer permissões para a operação tanto no caminho de atalho quanto no caminho da tabela de destino. Para atalhos de passthrough, sua identidade precisa de ambos os conjuntos de permissões; permissões de tabela de destino sozinhas não são suficientes. Para atalhos delegados, o acesso ao destino usa a identidade de conexão configurada. Para detalhes, veja segurança do atalho do OneLake.

Lidar com erros e diagnosticar solicitações

Para uma solicitação malsucedida, inspecione o status 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 também pode incluir um target e um details array. Cada detalhe contém um code e message, e pode incluir um target. O contrato não enumera códigos de erro ou códigos de status específicos da operação.

Para diagnósticos, você pode enviar um cabeçalho opcional x-ms-root-activity-id contendo um GUID. Grave o cabeçalho da x-ms-root-activity-id resposta ao tentar solucionar uma requisição. Não registre o token bearer.

Conteúdo relacionado

  • Última atualização em