Enumerar miniaturas de un DriveItemList thumbnails for a DriveItem

Espacio de nombres: microsoft.graphNamespace: microsoft.graph

Recupere una colección de recursos de ThumbnailSet de un recurso de DriveItem.Retrieve a collection of ThumbnailSet resources for a DriveItem resource.

Un DriveItem puede estar representado por cero o más recursos ThumbnailSet. Cada thumbnailSet puede tener uno o varios objetos en miniatura, que son imágenes que representan el elemento. Por ejemplo, un thumbnailSet puede incluir objetos en miniatura, los más comunes son small, medium o large.A DriveItem can be represented by zero or more ThumbnailSet resources. Each thumbnailSet can have one or more thumbnail objects, which are images that represent the item. For example, a thumbnailSet may include thumbnail objects, such as common ones including small, medium, or large.

Hay muchas maneras de trabajar con miniaturas en OneDrive. Aquí tiene las más comunes:There are many ways to work with thumbnails on OneDrive. Here are the most common ones:

  • Enumerar las miniaturas disponibles para un elementoEnumerate available thumbnails for an item
  • Recuperar una sola miniatura para un elementoRetrieve a single thumbnail for an item
  • Recuperar el contenido de miniaturasRetrieve thumbnail content
  • Recuperar miniaturas para varios elementos en una sola solicitudRetrieve thumbnails for multiple items in a single request
  • Recuperar los tamaños personalizados de miniaturasRetrieve custom thumbnail sizes
  • Cargar una miniatura personalizada para un elemento Upload a custom thumbnail for an item
  • Determinar si existe una miniatura cargada personalizadaDetermine if a custom uploaded thumbnail exists

PermisosPermissions

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permisoPermission type Permisos (de menos a más privilegiados)Permissions (from least to most privileged)
Delegado (cuenta profesional o educativa)Delegated (work or school account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft)Delegated (personal Microsoft account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
AplicaciónApplication Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitud HTTPHTTP request

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

Parámetros de consulta opcionalesOptional query parameters

Este método admite el parámetro de consulta OData $select para personalizar la respuesta.This method supports the $select OData puery parameter to customize the response.

Además, este método admite la recuperación de la miniatura con el valor EXIF de orientación original y sin la rotación aplicada al anexar el originalOrientation=true parámetro de consulta.Additionally, this method supports retrieving the thumbnail with the original orientation EXIF value and without the applied rotation by appending the originalOrientation=true query parameter. Actualmente, solo se admite en OneDrive personal.This is currently only supported on OneDrive Personal.

RespuestaResponse

Si se ejecuta correctamente, este método devuelve un código de respuesta 200 OK y la colección de objetos ThumbnailSet en el cuerpo de la respuesta.If successful, this method returns a 200 OK response code and collection of ThumbnailSet objects in the response body.

EjemploExample

Aquí tiene un ejemplo de la solicitud que recupera las miniaturas disponibles de un elemento en el OneDrive del usuario actual.Here is an example of the request which retrieves available thumbnails for an item in the current user's OneDrive.

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

Esta devuelve una matriz de thumbnailSets disponibles para el elemento.This returns an array of available thumbnailSets for the item. Cualquier elemento de una unidad puede tener cero o más miniaturas.Any item in a drive can have zero or more thumbnails.

Nota: Puede usar el parámetro de cadena de consulta select para controlar qué tamaños de miniatura se devuelven en ThumbnailSet. Por ejemplo, /thumbnails?select=medium recupera solo las miniaturas medianas.Note: You can use the select query string parameter to control which thumbnail sizes are returned in the ThumbnailSet. For example, /thumbnails?select=medium retrieves only the medium sized thumbnails.

RespuestaResponse

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

Obtener una única miniaturaGet a single thumbnail

Recupere los metadatos de una sola miniatura y un tamaño solicitándolo directamente en una solicitud.Retrieve the metadata for a single thumbnail and size by addressing it directly in a request.

Solicitud HTTPHTTP request

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

Parámetros de ruta de accesoPath parameters

NombreName TipoType DescripciónDescription
item-iditem-id stringstring El identificador único para el elemento al que se hace referencia.The unique identifier for the item referenced.
thumb-idthumb-id númeronumber El índice de la miniatura, normalmente de 0 a 4. Si existe una miniatura personalizada, su índice es 0.The index of the thumbnail, usually 0-4. If there is a custom thumbnail, its index is 0.
sizesize cadenastring El tamaño de la miniatura solicitada.The size of the thumbnail requested. Puede ser uno de los tamaños estándares enumerados a continuación o uno personalizado.This can be one of the standard sizes listed below or a custom size.
HTTP/1.1 200 OK
Content-Type: application/json

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

Recuperar el contenido binario de miniaturasRetrieve thumbnail binary content

Puede recuperar directamente el contenido de la miniatura solicitando la propiedad content de la miniatura.You can directly retrieve the content of the thumbnail by requesting the content property of the thumbnail.

Solicitud HTTPHTTP request

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

RespuestaResponse

El servicio responde con un redireccionamiento a la dirección URL de la miniatura.The service responds with a redirect to the thumbnail URL.

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

Las direcciones URL de la miniatura son seguras en caché.Thumbnail URLs are cache-safe. La dirección URL cambiará, si el elemento cambia de manera que necesite una nueva miniatura para generarse.The URL will change, if the item changes in a way that requires a new thumbnail to be generated.

Obtención de miniaturas al enumerar recursos DriveItemGetting thumbnails while listing DriveItems

Si está recuperando una lista de recursos DriveItem para mostrar, puede usar el parámetro de cadena de consulta $expand para que también incluya las miniaturas de esos recursos.If you are retrieving a list of DriveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. Esto permite que su aplicación recupere miniaturas y elementos en una única solicitud, en lugar de emitir varias solicitudes.This enables your app to retrieve thumbnails and items in a single request, instead of issuing many requests.

Solicitud HTTPHTTP request

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

RespuestaResponse

Las respuestas del servicio con la lista de recursos DriveItem y sus miniaturas.The service responses with the list of DriveItems and their thumbnails.

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

Opciones de tamañoSize options

Esta tabla define los tamaños posibles de las miniaturas. Puede solicitar cualquier tamaño de miniatura arbitrario, pero es probable que existan valores definidos y que se devuelva un valor rápidamente:This table defines the possible thumbnail sizes. While you can request any arbitrary thumbnail size, the defined values are likely to exist and return a value quickly:

NombreName ResoluciónResolution Relación de aspectoAspect Ratio DescripciónDescription
small borde más largo 9696 longest OriginalOriginal Miniatura pequeña y muy comprimida recortada en una relación de aspecto cuadrada.Small, highly compressed thumbnail cropped to a square aspect ratio.
medium borde más largo 176176 longest OriginalOriginal Miniatura recortada al tamaño estándar del elemento para la vista web de OneDrive.Cropped to the standard item size for the OneDrive web view.
large borde más largo 800800 longest OriginalOriginal Miniatura con el borde más largo cambiado a un tamaño de 800 píxeles.Thumbnail with the longest edge resized to 800 pixels.
smallSquare 96x9696x96 Recorte cuadradoSquare Crop Miniatura de cuadrado pequeñoSmall square thumbnail
mediumSquare 176x176176x176 Recorte cuadradoSquare Crop Miniatura de cuadrado pequeñoSmall square thumbnail
largeSquare 800x800800x800 Recorte cuadradoSquare Crop Miniatura de cuadrado grandeLarge square thumbnail

Solicitar tamaños personalizados de miniaturasRequesting custom thumbnail sizes

Además de los tamaños definidos, la aplicación puede solicitar un tamaño de miniatura personalizado especificando las dimensiones de la miniatura prefijada con c.In addition to the defined sizes, your app can request a custom thumbnail size by specifying the dimensions of the thumbnail prefixed with c. Por ejemplo, si su aplicación necesita miniaturas de tamaño 300x400, puede solicitar ese tamaño de esta forma:For example if your app needs thumbnails that are 300x400, it can request that size like this:

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

Que responde solo con el tamaño de miniatura personalizado seleccionado:Which responds with just the custom thumbnail size selected:

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

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

Puede especificar las siguientes opciones después del tamaño de la miniatura solicitado:You can specify the following options after the size of the thumbnail requested:

Ejemplos de identificadores personalizadosExamples of custom identifiers

Identificador de miniaturaThumbnail identifier ResoluciónResolution Relación de aspectoAspect ratio DescripciónDescription
c300x400c300x400 Limitado por un cuadro de 300x400Bounded by 300x400 box OriginalOriginal Genera una miniatura que se adapta dentro de un cuadro de 300x400 píxeles, manteniendo la relación de aspectoGenerate a thumbnail that fits inside a 300x400 pixel box, maintaining aspect ratio
c300x400_Cropc300x400_Crop 300x400300x400 RecortadoCropped Genera una miniatura que tiene 300x400 píxeles. Esto funciona cambiando el tamaño de la imagen para rellenar el cuadro de 300x400 y recortando lo que sobresalga de este.Generate a thumbnail that is 300x400 pixels. This works by resizing the image to fill the 300x400 box and cropping whatever spills outside the box.

Nota: La miniatura devuelta puede no coincidir exactamente con las dimensiones en píxeles que se solicitaron, pero coincidirá con la relación de aspecto.Note: The thumbnail returned may not exactly match the pixel dimensions that was requested, but will match the aspect ratio. En algunos casos, puede devolverse una miniatura más grande que la que se ha solicitado si la miniatura ya existe y se puede escalar fácilmente para ajustarse a la resolución solicitada.In some cases, a larger thumbnail may be returned than was requested, if the thumbnail already exists and can easily be scaled to match the requested resolution.

ComentariosRemarks

Nota En OneDrive para la Empresa y en SharePoint:Note In OneDrive for Business and SharePoint:

El uso de estas llamadas para expandir la colección de miniaturas no funcionará:Using these calls to expand the thumbnails collection will not work:

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

Las miniaturas no se admiten en SharePoint Server 2016.Thumbnails are not supported on SharePoint Server 2016.

Respuestas de errorError responses

Vea Respuestas de error para obtener más información sobre la manera en que se devuelven los errores.See Error Responses for more info about how errors are returned.