Lire et écrire des métadonnées de tableau supplémentaires (aperçu)

Utilisez l’API de métadonnées de table additionnelle OneLake pour lire et écrire des descriptions et des balises clé-valeur pour une table et ses colonnes. Cette API utilise une route REST commune plutôt que les routes compatibles avec le catalogue REST Iceberg ou avec Unity Catalog.

Par exemple, ajoutez une description qui explique l’objectif commercial d’une table, identifiez la table avec son équipe propriétaire, et expliquez comment interpréter une colonne. Ces opérations fonctionnent avec des métadonnées descriptives, et non avec des lignes de tableaux. Pour récupérer des lignes, utilisez l’API de lecture de table OneLake.

Important

L’API de métadonnées de table supplémentaire est disponible en aperçu public. Les fonctionnalités et le comportement peuvent changer avant la disponibilité générale.

Prerequisites

  • Complétez les prérequis de l’API à table partagée et les étapes d’authentification.
  • Identifiez l’ID de l’espace de travail, l’ID de l’élément, le nom du schéma et le nom de la table pour votre table cible.
  • Identifiez les colonnes existantes que vous souhaitez décrire ou taguer.
  • Utilisez une identité avec les autorisations requises pour lire ou écrire les métadonnées de la table cible.

Les exemples utilisent une table nommée sales dans le dbo schéma et une colonne existante nommée customer_id. Remplacez ces noms par ceux de votre table.

Point de terminaison et opérations

Utilisez l’URL de base suivante :

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

Les deux opérations empruntent le même itinéraire :

/common/v1/<WorkspaceID>/<ItemID>/schemas/<SchemaName>/tables/<TableName>/additionalMetadata
Méthode Opération Réponse réussie
GET Lisez des métadonnées supplémentaires pour un tableau et ses colonnes. 200 OK avec une réponse de métadonnées JSON.
POST Définissez des métadonnées supplémentaires pour une table et ses colonnes. 200 OK avec une réponse JSON contenant des métadonnées.

Utilisez des GUIDs pour <WorkspaceID> et <ItemID>. Encodez en URL les noms de schéma et de table en segments de chemin individuels. Incluez un Authorization: Bearer <Token> en-tête avec un jeton d’accès Microsoft Entra ID pour l’audience https://storage.azure.com/. Pour POST, incluez Content-Type: application/jsonégalement .

Descriptions et tags supportés

Utilisez ces champs dans une POST requête :

Champ Type Description et limites
description Chaîne La description du tableau. 1 024 caractères maximum.
tags Objet Les balises de table sont des paires clé-valeur sous forme de chaînes. Chaque clé a un maximum de 128 caractères, et chaque valeur a un maximum de 256 caractères.
columns Array Des métadonnées supplémentaires pour les colonnes que vous identifiez dans la requête.
columns[].columnName Chaîne Nom d’une colonne existante. Utilisez ce champ pour identifier la colonne que vous souhaitez décrire ou taguer.
columns[].description Chaîne La description de la colonne. 1 024 caractères maximum.
columns[].tags Objet Les balises de colonne sont des paires clé-valeur sous forme de chaînes. Les limites de clé et de valeur sont les mêmes que pour les tags de table.

Lire des métadonnées supplémentaires

Envoyez une GET requête pour obtenir des métadonnées au niveau de la table et au niveau de la colonne.

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

Une requête réussie retourne 200 OK. Le JSON suivant montre le format de réponse :

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

Les valeurs, les noms de colonnes et les champs dans votre réponse dépendent de la table cible et de ses métadonnées. Le contrat n’exige pas que tous les champs soient présents.

Ajouter des métadonnées supplémentaires

Envoyez une POST requête avec un corps JSON pour remplacer les métadonnées supplémentaires de la table.

Important

POST remplace les métadonnées supplémentaires existantes ; ce n’est pas une mise à jour partielle. Incluez la description du tableau, les tags de tableau, ainsi que les descriptions des colonnes et tags que vous souhaitez conserver dans chaque requête. Par exemple, une requête qui ne contient que description définit la description de la table et supprime les balises de table existantes ainsi que toutes les descriptions et balises de colonnes.

Cet exemple établit une description de table et des balises, ainsi qu’une description et une balise pour customer_id. Il identifie la colonne en utilisant 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

Corps de la requête :

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

Une requête réussie renvoie 200 OK avec une réponse de métadonnées supplémentaire. Par exemple:

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

Envoyez une autre GET requête pour vérifier les métadonnées après l’écriture.

Préserver les métadonnées existantes

Pour modifier certaines descriptions ou tags sans supprimer d’autres métadonnées, utilisez une séquence lecture-modification-écriture :

  1. Envoyez une GET demande pour lire les métadonnées supplémentaires actuelles.
  2. Changez les descriptions ou tags que vous souhaitez mettre à jour dans les métadonnées retournées. Conservez les autres champs, les clés de balise et les entrées de colonne que vous souhaitez conserver.
  3. Envoyez les métadonnées complètes mises à jour dans une POST requête.
  4. Envoyez une autre GET requête pour confirmer le résultat.

Coordonnez les mises à jour simultanées des métadonnées afin qu’aucune autre écriture n’ait lieu entre vos requêtes GET et POST.

Lire et écrire des métadonnées avec Python

L’exemple suivant s’authentifie auprès de Microsoft Entra ID, lit les métadonnées actuelles, met à jour les descriptions et tags sélectionnés tout en préservant les autres métadonnées, puis relit les métadonnées. Il n’appelle pas d’API de catalogue spécifique au format ni ne demande d’identifiants d’accès au stockage.

Caution

L’exécution de cet exemple permet d’écrire des métadonnées. Utilisez une table de test et une colonne, puis remplacez les descriptions et tags d’exemple avant de l’exécuter. L’exemple conserve les métadonnées de sa lecture initiale, mais peut écraser les modifications apportées par un autre client avant l’écriture.

Installez les dépendances :

python -m pip install azure-identity requests

Configurez une méthode d’authentification Azure Identity prise en charge, comme la connexion locale avec Azure CLI, avant d’exécuter l’échantillon.

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

L’argument json définit l’en-tête Content-Type: application/json de la requête. L’exemple soulève une exception pour une réponse HTTP infructueuse plutôt que de la traiter comme une mise à jour réussie des métadonnées.

Travailler avec les métadonnées via les raccourcis OneLake

Pour un raccourci interne de table OneLake, utilisez l’ID de l’espace de travail, l’identifiant de l’élément, le nom du schéma et le nom de la table dans la même route supplémentaire de métadonnées. Les opérations fonctionnent avec les métadonnées de la table cible, et non avec une copie séparée des métadonnées pour le raccourci :

  • GET renvoie les métadonnées supplémentaires de la table cible, y compris ses descriptions et ses tags.
  • POST remplace les métadonnées supplémentaires de la table cible. Les changements sont visibles lorsque vous lisez les métadonnées via le raccourci ou le tableau de destination.

Par exemple, si un raccourci nommé sales_shortcut pointe vers sales, lisez les métadonnées de la table source via le raccourci en utilisant cette requête :

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

Pour mettre à jour les métadonnées via le raccourci, envoyez une POST requête à la même URL. La sémantique de remplacement s’applique également à la table cible : une requête uniquement descriptive via le raccourci supprime les balises et les métadonnées de colonne existantes de la table cible. Utilisez la séquence lecture-modification-écriture pour conserver les métadonnées que vous souhaitez conserver.

L’accès nécessite des permissions pour l’opération à la fois sur le chemin de raccourci et sur le chemin de la table cible. Pour les raccourcis de passthrough, votre identité nécessite les deux ensembles de permissions ; les permissions de la table cible seules ne suffisent pas. Pour les raccourcis délégués, l’accès cible utilise l’identité de connexion configurée. Pour plus de détails, voir sécurité des raccourcis OneLake.

Gérer les erreurs et diagnostiquer les requêtes

Pour une requête infructueuse, inspectez le statut HTTP et la réponse d’erreur JSON. Le contrat d’erreur a la forme suivante ; les paramètres fictifs de code et de message ne sont pas des valeurs d’erreur de service spécifiques :

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

L’objet error peut également inclure un tableau target et details. Chaque détail contient un code et un message, et peut inclure un target. Le contrat n’énumère pas les codes d’erreur ou codes d’état spécifiques à l’opération.

Pour les diagnostics, vous pouvez envoyer un en-tête optionnel x-ms-root-activity-id contenant un GUID. Enregistrez l’en-tête x-ms-root-activity-id de réponse lorsque vous dépannez une requête. Ne notez pas le jeton Bearer.