Compartir a través de

Enumerar miniaturas de un DriveItem

  • Artículo

Recupere una colección de recursos de ThumbnailSet de un recurso de DriveItem.

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.

Hay muchas maneras de trabajar con miniaturas en OneDrive. Aquí tiene las más comunes:

  • Enumerar las miniaturas disponibles para un elemento
  • Recuperar una sola miniatura para un elemento
  • Recuperar el contenido de miniaturas
  • Recuperar miniaturas para varios elementos en una sola solicitud
  • Recuperar los tamaños personalizados de miniaturas
  • Cargar una miniatura personalizada para un elemento
  • Determinar si existe una miniatura cargada personalizada

Permisos

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.

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Aplicación Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitud 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

Parámetros de consulta opcionales

Este método admite el $selectparámetro de consulta OData para personalizar la respuesta.

Respuesta

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.

Ejemplo

Aquí tiene un ejemplo de la solicitud que recupera las miniaturas disponibles de un elemento en el OneDrive del usuario actual.

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

Esta devuelve una matriz de thumbnailSets disponibles para el elemento. Cualquier elemento de una unidad puede tener cero o más miniaturas.

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.

Respuesta

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 miniatura

Recupere los metadatos de una sola miniatura y un tamaño solicitándolo directamente en una solicitud.

Solicitud HTTP

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

Parámetros de ruta de acceso

Nombre Tipo Descripción
item-id string El identificador único para el elemento al que se hace referencia.
thumb-id número El índice de la miniatura, normalmente de 0 a 4. Si existe una miniatura personalizada, su índice es 0.
size cadena El tamaño de la miniatura solicitada. Puede ser uno de los tamaños estándares enumerados a continuación o uno personalizado. 
HTTP/1.1 200 OK
Content-Type: application/json

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

Recuperar el contenido binario de miniaturas

Puede recuperar directamente el contenido de la miniatura solicitando la propiedad content de la miniatura.

Solicitud HTTP

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

Respuesta

El servicio responde con un redireccionamiento a la dirección URL de la miniatura.

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

Las direcciones URL de la miniatura son seguras en caché. La dirección URL cambiará, si el elemento cambia de manera que necesite una nueva miniatura para generarse.

Obtención de miniaturas al enumerar recursos DriveItem

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. Esto permite que su aplicación recupere miniaturas y elementos en una única solicitud, en lugar de emitir varias solicitudes.

Solicitud HTTP

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

Respuesta

Las respuestas del servicio con la lista de recursos DriveItem y sus miniaturas.

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ño

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:

Nombre Resolución Relación de aspecto Descripción
small borde más largo 96 Original Miniatura pequeña y muy comprimida recortada en una relación de aspecto cuadrada.
medium borde más largo 176 Original Miniatura recortada al tamaño estándar del elemento para la vista web de OneDrive.
large borde más largo 800 Original Miniatura con el borde más largo cambiado a un tamaño de 800 píxeles.
smallSquare 96x96 Recorte cuadrado Miniatura de cuadrado pequeño
mediumSquare 176x176 Recorte cuadrado Miniatura de cuadrado pequeño
largeSquare 800x800 Recorte cuadrado Miniatura de cuadrado grande

Solicitar tamaños personalizados de miniaturas

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. Por ejemplo, si su aplicación necesita miniaturas de tamaño 300x400, puede solicitar ese tamaño de esta forma:

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

Que responde solo con el tamaño de miniatura personalizado seleccionado:

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:

Ejemplos de identificadores personalizados

Identificador de miniatura Resolución Relación de aspecto Descripción
c300x400 Limitado por un cuadro de 300x400 Original Genera una miniatura que se adapta dentro de un cuadro de 300x400 píxeles, manteniendo la relación de aspecto
c300x400_Crop 300x400 Recortado 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.

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. 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.

Comentarios

Nota En OneDrive para la Empresa y en SharePoint:

El uso de estas llamadas para expandir la colección de miniaturas no funcionará:

  • 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.

Respuestas de error

Vea Respuestas de error para obtener más información sobre la manera en que se devuelven los errores.