Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 :
- Envoyez une
GETdemande pour lire les métadonnées supplémentaires actuelles. - 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.
- Envoyez les métadonnées complètes mises à jour dans une
POSTrequête. - Envoyez une autre
GETrequê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 :
-
GETrenvoie les métadonnées supplémentaires de la table cible, y compris ses descriptions et ses tags. -
POSTremplace 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.