Modification de la forme d’une réponse à l’aide des paramètres de requête

Article
04/08/2023

L’API OneDrive fournit plusieurs paramètres de requête facultatifs qui peuvent être utilisés pour contrôler les données spécifiques renvoyées dans une réponse.

Cette rubrique traite des points suivants :

Sélection des propriétés
Développement des collections
Tri des collections

Sélection des propriétés

Vous pouvez utiliser le paramètre de chaîne de requête select pour fournir une liste délimitée par des virgules des propriétés à renvoyer sur les éléments.

Exemple

Cet exemple sélectionne uniquement les propriétés name et size à renvoyer lors de la récupération des enfants d’un élément.

GET /drive/root/children?select=name,size

En soumettant la requête avec la chaîne de requête select=name,size, les objets dans la réponse auront seulement les valeurs de propriétés qui ont été incluses. Lorsque vous utilisez l’instruction select, vous devez spécifier toutes les propriétés à renvoyer.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "13140a9sd9aba",
      "name": "Documents",
      "size": 1024
    },
    {
      "id": "123901909124a",
      "name": "Pictures",
      "size": 1012010210
    }
  ]
}

Développement des collections

Dans les demandes de l’API OneDrive, les collections enfants d’éléments référencés ne sont pas développées automatiquement. En effet, cela permet de réduire le trafic réseau et le temps nécessaire à la génération d’une réponse du service. Toutefois, dans certains cas, vous pouvez inclure ces résultats dans une réponse.

Vous pouvez utiliser le paramètre de chaîne de requête expand pour indiquer à l’API OneDrive de développer une collection enfant et d’inclure ces résultats.

Par exemple, pour récupérer les informations du lecteur racine et les éléments de niveau supérieur dans un lecteur, vous utilisez le paramètre expand, comme dans l’exemple ci-dessous. Cet exemple utilise également une instruction select pour renvoyer uniquement les propriétés id et name des éléments enfants.

GET /drive/root?expand=children(select=id,name)

La requête renvoie les éléments de la collection, avec la collection enfant développée.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12312312541",
  "name": "root",
  "size": 218753122201,
  "webUrl": "https://onedrive.live.com/?cid=0f040...",
  "folder": {
    "childCount": 4
  },
  "children": [
    {
      "id": "F04AA961744A809!48443",
      "name": "Applications",
    },
    {
      "id": "F04AA961744A809!92647",
      "name": "Attachments",
    },
    {
      "id": "F04AA961744A809!93269",
      "name": "Balsmiq Sketches",
    },
    {
      "id": "F04AA961744A809!65191",
      "name": "Camera imports",
    }
  ]
}

Tri des collections

Vous pouvez utiliser la chaîne de requête orderby pour contrôler l’ordre de tri des éléments renvoyés par l’API OneDrive. Pour une collection d’éléments, utilisez les champs suivants dans le paramètre orderby.

name
size
lastModifiedDateTime

Notez que dans OneDrive Entreprise et SharePoint Server 2016, la chaîne de requête orderby fonctionne uniquement avec name et url.

Pour trier les résultats dans l’ordre croissant ou décroissant, ajoutez asc ou desc au nom du champ, séparés par un espace, par exemple, ?orderby=name%20desc.

Par exemple, pour renvoyer le contenu de la racine d’un lecteur dans OneDrive, trié du plus grand au plus petit, utilisez la syntaxe suivante : /drive/items/root/children?orderby=size%20desc.

Paramètres de requête OData facultatifs

Voici un tableau des paramètres de requête OData facultatifs, que vous pouvez utiliser dans vos demandes à l’API OneDrive.

Nom	Valeur	État	Description
expand	chaîne	disponible	Liste de relations séparées par des virgules à développer et inclure dans la réponse. Par exemple, pour extraire les enfants d’un dossier, entrez `expand=children`.
select	chaîne	disponible	Liste de propriétés séparées par des virgules à inclure dans la réponse.
skipToken	chaîne	disponible	Jeton de pagination qui est utilisé pour obtenir l’ensemble de résultats suivant.
top	entier	disponible	Le nombre d’éléments à renvoyer dans un ensemble de résultats. L’API OneDrive peut avoir une limite matérielle qui vous empêche de demander plus d’éléments par réponse.
orderby	chaîne	disponible	Liste de propriétés séparées par des virgules qui sont utilisées pour trier l’ordre des éléments dans la collection de réponses. Fonctionne pour les champs `name`, `size` et `lastModifiedDateTime`.
filter	chaîne	non disponible	Chaîne de filtrage permettant de filtrer la réponse en fonction d’un ensemble de critères.

Remarque : Selon la norme OData, ces termes sont précédés par le signe $. L’API OneDrive prend en charge ces paramètres de requête avec ou sans le caractère spécial, mais vous devez utiliser le caractère $ de façon cohérente dans les arguments sur l’ensemble de la requête.

Partager via