Stocker et interroger les métadonnées du conteneur

S’applique à : Développeur

Utilisez les métadonnées lorsque votre application a besoin de champs structurés sur des fichiers dans un conteneur SharePoint Embedded. Les métadonnées sont stockées sous forme de colonnes sur un fileStorageContainer et de valeurs de champ sur les éléments du lecteur de conteneur. Votre application est responsable de la création et de la gestion du schéma de colonne pour chaque instance de conteneur. Pour obtenir la liste complète des propriétés de ressource de conteneur, consultez la section type de ressource fileStorageContainer.

Autorisations et appelants pris en charge

Appelez les API de métadonnées avec un jeton de porteur d’application uniquement ou délégué. À utiliser FileStorageContainer.Selected pour les appels d’application et délégués.

Les propriétaires et gestionnaires de conteneurs peuvent créer, mettre à jour et supprimer des colonnes. Les membres du conteneur peuvent lire et répertorier les colonnes.

Choisir des types de colonnes

SharePoint Embedded metadata prend en charge les propriétés de type de colonne suivantes : boolean, , choicecurrency, numberhyperlinkOrPicturedateTimepersonOrGroupet .text Il prend également en charge les paramètres de colonne tels que indexed, , isDeletableisSealed, namereadOnly, et type.

Les noms de colonne doivent respecter les règles SharePoint. N’utilisez pas de noms qui contiennent !, commencent par un chiffre ou un signe de ponctuation, qui contiennent des espaces, qui ressemblent à des références de cellule de feuille de calcul, qui représentent des valeurs vraies ou fausses localisées ou qui n’utilisent pas de noms réservés tels Authorque , Createdou Description.

Créer une colonne

Créez une colonne dans le conteneur avant d’écrire des valeurs de champ dans les fichiers.

POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
Content-Type: application/json

{
  "description": "test",
  "displayName": "Title",
  "enforceUniqueValues": false,
  "hidden": false,
  "indexed": false,
  "name": "Title",
  "text": {
    "allowMultipleLines": false,
    "appendChangesToExistingText": false,
    "linesForEditing": 0,
    "maxLength": 255
  }
}

La demande de création ne prend pas en charge type, et le texte maxLength doit être inférieur ou égal à 255.

Remarque

Depuis janvier 2026, les API de colonne de conteneur (répertorier, créer, mettre à jour, supprimer des colonnes) sont également en disponibilité générale sur le point de terminaison de Microsoft Graph v1.0 . Vous pouvez remplacer /beta/ par dans /v1.0/ la colonne demandes ci-dessous. Le point de terminaison bêta reste disponible.

Gérer les colonnes

Utilisez l’ID de colonne renvoyé par l’opération de création ou de liste.

GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}

Correctifs de propriétés pris en charge lorsque le schéma change. Vous pouvez mettre à jour n’importe quelle propriété d’une colonne à l’exception de la id propriété.

{
  "required": true,
  "hidden": false,
  "description": "This is my new column description"
}

Lire et écrire les métadonnées d’un fichier

Les valeurs de champ sont stockées dans les champs d’élément de liste de l’élément de lecteur. Lisez tous les champs ou sélectionnez ceux dont votre interface utilisateur a besoin.

GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color

Correctif des valeurs de champ pour mettre à jour les métadonnées. Permet null d’effacer une valeur de champ lorsque la colonne autorise des valeurs vides.

PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
Content-Type: application/json

{
  "Color": "Fuchsia",
  "Quantity": 934
}

{
  "Color": null
}

Interroger les fichiers par métadonnées

Utilisez les options de requête OData sur les colonnes personnalisées lorsque vous avez besoin d’un filtrage structuré ou d’un classement à l’intérieur d’un lecteur de conteneur.

GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields)

À utiliser $expand=listitem($expand=fields) lorsque le résultat nécessite des valeurs de champ dans la réponse. Créez des colonnes indexées pour les filtres à cardinalité élevée que votre application exécute fréquemment.

Pour effectuer une recherche en texte intégral dans les conteneurs et les métadonnées personnalisées, consultez Rechercher dans les conteneurs et les fichiers. Pour filtrer la récupération sémantique par métadonnées personnalisées indexées, consultez Filtrer la récupération par métadonnées personnalisées. Les deux expériences utilisent des propriétés gérées par SharePoint, telles que la OWSTEXT propriété générée pour une colonne de texte.

Utilisez OData $filter pour les requêtes structurées à l’intérieur d’un lecteur de conteneur. Utilisez la recherche pour les requêtes en texte libre dans de nombreux conteneurs ou utilisez l’API Retrieval pour retourner des extraits pour l’ancrage de l’IA.

Maintenir la cohérence du schéma

Créer les colonnes requises lors de la mise en service du conteneur. Stockez la version de schéma attendue dans les données de votre application et exécutez les migrations lorsque de nouvelles colonnes sont introduites. Évitez de supprimer des colonnes tant que vous ne savez pas quels flux de travail, requêtes, exportations ou expériences de recherche ne dépendent de leurs valeurs.

Étapes suivantes

  • Last updated on