Dresser une liste des miniatures d’un objet « DriveItem »

  • Article

Récupérez une collection de ressources ThumbnailSet pour une ressource DriveItem.

Un objet « DriveItem » peut être représenté par au moins une ressource ThumbnailSet. Chaque élément thumbnailSet peut posséder un ou plusieurs objets thumbnail, qui sont des images représentant l’élément. Par exemple, un élément thumbnailSet peut également inclure des objets thumbnail, notamment les plus courants, y compris small, medium ou large.

Il existe plusieurs manières de travailler avec des miniatures sur OneDrive. Voici les plus courantes :

  • Énumérer les miniatures disponibles pour un élément
  • Récupérer une seule miniature pour un élément
  • Extraire le contenu des miniatures
  • Récupérer les miniatures de plusieurs éléments dans une seule requête
  • Récupérer des tailles de miniatures personnalisées
  • Charger la miniature personnalisée d’un élément
  • Déterminer s’il existe une miniature chargée personnalisée

Autorisations

L’une des autorisations suivantes est requise pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Déléguée (compte Microsoft personnel) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Application Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Requête HTTP

GET /drives/{drive-id}/items/{item-id}/thumbnails
GET /groups/{group-id}/drive/items/{item-id}/thumbnails
GET /me/drive/items/{item-id}/thumbnails
GET /sites/{site-id}/drive/items/{item-id}/thumbnails
GET /users/{user-id}/drive/items/{item-id}/thumbnails

Paramètres facultatifs de la requête

Cette méthode prend en charge le $selectparamètre de requête OData pour personnaliser la réponse.

Réponse

En cas de réussite, cette méthode renvoie un code de réponse 200 OK et une collection d’objets ThumbnailSet dans le corps de la réponse.

Exemple

Voici un exemple de la demande qui récupère les miniatures disponibles d’un élément dans l’instance OneDrive de l’utilisateur actuel.

GET /me/drive/items/{item-id}/thumbnails

Renvoie un tableau des objets ThumbnailSet disponibles pour l’élément. Tous les éléments d’un lecteur peuvent avoir zéro, une ou plusieurs miniatures.

Remarque : vous pouvez utiliser le paramètre de chaîne de requête select pour contrôler la taille des miniatures renvoyées dans l’objet ThumbnailSet. Par exemple, /thumbnails?select=medium récupère uniquement les miniatures de taille moyenne.

Réponse

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

{
  "value": [
    {
      "id": "0",
      "small": { "height": 64, "width": 96, "url": "https://sn3302files..."},
      "medium": { "height": 117, "width": 176, "url": "https://sn3302files..."},
      "large": { "height": 533, "width": 800, "url": "https://sn3302files..."}
    }
  ]
}

Récupérer une seule miniature

Vous pouvez récupérer les métadonnées d’une seule miniature et la taille en envoyant une demande.

Requête HTTP

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}

Paramètres du chemin d’accès

Nom Type Description
item-id chaîne Identificateur unique de l’élément référencé.
thumb-id number Index de la miniature, généralement 0-4. S’il existe une miniature personnalisée, son index est 0.
size chaîne Taille de la miniature demandée. Il peut s’agir de l’une des tailles standard affichées ci-dessous ou d’une taille personnalisée. 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "width": 100,
  "height": 100,
  "url": "http://onedrive.com/asd123a/asdjlkasjdkasdjlk.jpg"
}

Récupérer le contenu binaire d’une miniature

Vous pouvez récupérer directement le contenu de la miniature en demandant la propriété content de la miniature.

Requête HTTP

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content

Réponse

Le service répond avec une redirection vers l’URL de la miniature.

HTTP/1.1 302 Found
Location: https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi

Les URL des miniatures sont des URL de cache sécurisées. L’URL change si l’élément est modifié d’une manière qui nécessite la génération d’une nouvelle miniature.

Obtention de miniatures pendant l’énumération des ressources DriveItems

Si vous récupérez une liste de ressources DriveItem à afficher, vous pouvez utiliser le paramètre de chaîne de requête $expand pour également inclure les miniatures de ces ressources. Ainsi, votre application peut récupérer les miniatures et les éléments en une seule requête, au lieu d’en émettre plusieurs.

Requête HTTP

GET /me/drive/items/{item-id}/children?$expand=thumbnails

Réponse

Réponses du service avec la liste des ressources DriveItem et leurs miniatures.

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

{
  "value": [
    {
      "id": "182331E8-2788-4932-B52A-A6550577043F",
      "name": "my photo.jpg",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    },
    {
      "id": "2D223953-A56B-4D9B-ADF3-13E7820673A2",
      "name": "presentation.pptx",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    }
  ]
}

Options de taille

Ce tableau définit les tailles de miniatures possibles. Bien que vous puissiez demander une taille de miniature arbitraire, les valeurs définies sont plus susceptibles d’exister réellement de renvoyer rapidement une valeur :

Nom Solution Proportions Description
small 96 plus long Original Miniature de petite taille, fortement compressée, rognée à des proportions carrées.
medium 176 plus long Original Rognée à la taille d’élément standard pour l’affichage web OneDrive.
large 800 plus long Original Miniature dont le bord le plus long est redimensionné à 800 pixels.
smallSquare 96x96 Rognage carré Petite miniature carrée
mediumSquare 176x176 Rognage carré Petite miniature carrée
largeSquare 800x800 Rognage carré Grande miniature carrée

Demande des tailles de miniatures personnalisées

En plus des tailles définies, votre application peut demander une taille de miniature personnalisée en spécifiant ses dimensions, précédées de c. Par exemple, si votre application a besoin de miniatures au format 300 x 400, vous pouvez demander cette taille de la manière suivante :

GET /me/drive/items/{item-id}/thumbnails?select=c300x400_Crop

Qui répond avec la taille de miniature personnalisée sélectionnée :

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

{
  "value": [
    {
      "id": "0",
      "c300x400_Crop": { "height": 300, "width": 400, "url": "https://sn3302files.onedrive.com/123"},
    }
  ]
}

Vous pouvez spécifier les options suivantes après la taille de miniature demandée :

Exemples d’identificateurs personnalisés

Identificateur de miniature Résolution Proportions Description
c300x400 Délimité par une zone de 300 x 400 Original Générer une miniature qui s’adapte à l’intérieur d’une zone de 300 x 400 pixels, en conservant les proportions
c300x400_Crop 300x400 Rognée Générer une miniature de 300 x 400 pixels. Redimensionne l’image pour remplir la zone de 300 x 400 et rogne tout ce qui dépasse de la zone.

Remarque : la miniature renvoyée peut avoir une résolution différente de celle demandée, tout en respectant les proportions. Dans certains cas, une plus grande miniature peut être renvoyée si la miniature existe déjà et peut être facilement adaptée pour obtenir la résolution demandée.

Remarques

Remarque : dans OneDrive Entreprise et SharePoint :

L’utilisation des appels suivants pour développer la collection de miniatures ne fonctionnera pas :

  • GET /drive/root:/{item-path}?expand=children(expand=thumbnails)
  • GET /drive/items/{item-id}/children?expand=thumbnails

Les miniatures ne sont pas prises en charge dans SharePoint Server 2016.

Réponses d’erreur

Pour plus d’informations sur la façon dont les erreurs sont renvoyées, voir Réponses d’erreur.