Listar miniaturas para um DriveItem

  • Artigo

Recupere uma coleção de recursos ThumbnailSet para um recurso DriveItem.

Um DriveItem pode ser representado por zero ou mais recursos ThumbnailSet. Cada thumbnailSet pode ter um ou mais objetos thumbnail, que são imagens que representam o item. Por exemplo, um thumbnailSet podem incluir objetos thumbnail, como objetos comuns que incluem small, medium ou large.

Há várias maneiras de trabalhar com miniaturas no OneDrive. Veja a seguir as mais comuns:

  • Enumerar miniaturas disponíveis para um item
  • Recuperar uma única miniatura para um item
  • Recuperar o conteúdo da miniatura
  • Recuperar miniaturas de vários itens em uma única solicitação
  • Recuperar tamanhos personalizados de miniaturas
  • Carregar uma miniatura personalizada para um item
  • Determinar se uma miniatura personalizada carregada existe

Permissões

Uma das permissões a seguir é necessária para chamar essa API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Aplicativo Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitação 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 opcionais

Esse método dá suporte ao $selectparâmetro de consulta OData para personalizar a resposta.

Resposta

Se for bem-sucedido, esse método retornará um código de resposta 200 OK e uma coleção de objetos ThumbnailSet no corpo da resposta.

Exemplo

Veja um exemplo da solicitação que recupera as miniaturas disponíveis de um item no OneDrive atual do usuário.

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

Isto retorna uma matriz de thumbnailSets disponíveis para o item. Qualquer item em uma unidade pode ter zero ou mais miniaturas.

Observação: Você pode usar o parâmetro da cadeia de caracteres de consulta select para controlar quais tamanhos de miniatura são retornados no ThumbnailSet. Por exemplo, /thumbnails?select=medium recupera somente miniaturas de tamanho médio.

Resposta

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

Obter uma única miniatura

Recupere os metadados de uma única miniatura e tamanho tratando-os diretamente em uma solicitação.

Solicitação HTTP

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

Parâmetros do caminho

Nome Tipo Descrição
item-id string O identificador exclusivo do item referenciado.
thumb-id number O índice da miniatura, geralmente de 0 a 4. Se houver uma miniatura personalizada, seu índice será 0.
size string O tamanho da miniatura solicitada. Pode ter um dos tamanhos padrão listados abaixo, ou um tamanho personalizado. 
HTTP/1.1 200 OK
Content-Type: application/json

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

Recuperar o conteúdo binário da miniatura

Você pode recuperar diretamente o conteúdo da miniatura solicitando a propriedade content dessa miniatura.

Solicitação HTTP

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

Resposta

O serviço responde com um redirecionamento para a URL da miniatura.

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

URLs de miniaturas são seguras em cache. A URL mudará se o item for alterado de uma maneira que exigir que uma nova miniatura seja gerada.

Obter miniaturas ao listar DriveItems

Se você estiver recuperando uma lista de recursos DriveItem para exibição, use o parâmetro de cadeia de consulta $expand para incluir as miniaturas para esses recursos. Isso permite que seu aplicativo recupere miniaturas e itens em uma única solicitação, em vez de emitir muitas solicitações.

Solicitação HTTP

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

Resposta

As respostas do serviço com a lista de DriveItems e suas 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..."
                   }
        }
      ]
    }
  ]
}

Opções de tamanho

Essa tabela define os possíveis tamanhos de miniaturas. Embora você possa solicitar qualquer tamanho de miniatura arbitrário, os valores definidos provavelmente existem e retornam um valor rapidamente:

Nome Resolução Taxa de proporção Descrição
small 96 mais longa Original Miniatura pequena e altamente compactada, recortada em uma taxa de proporção quadrada.
medium 176 mais longa Original Recortada no tamanho do item padrão para o modo de exibição de Web do OneDrive.
large 800 mais longa Original Miniatura com a borda mais longa redimensionada para 800 pixels.
smallSquare 96x96 Corte quadrado Miniatura quadrada pequena
mediumSquare 176x176 Corte quadrado Miniatura quadrada pequena
largeSquare 800x800 Corte quadrado Miniatura quadrada grande

Solicitar tamanhos personalizados de miniaturas

Além dos tamanhos definidos, seu aplicativo pode solicitar um tamanho personalizado de miniatura, especificando as dimensões da miniatura prefixadas com c. Por exemplo, se o seu aplicativo precisar de miniaturas de 300 x 400, é possível solicitar esse tamanho desta forma:

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

Que responde com o tamanho de miniatura personalizado selecionado:

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

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

Você pode especificar as seguintes opções após o tamanho de miniatura solicitado:

Exemplos de identificadores personalizados

Identificador de miniatura Resolução Taxa de proporção Descrição
c300x400 Limitado por uma caixa de 300 x 400 Original Gere uma miniatura que se ajuste em uma caixa de 300 x 400 pixels, mantendo a taxa de proporção
c300x400_Crop 300x400 Recortada Gere uma miniatura de 300 x 400 pixels. Para isso, é preciso redimensionar a imagem para caber na caixa de 300 x 400 e recortar o que ficar fora da caixa.

Observação: talvez a miniatura retornada não corresponda exatamente às dimensões de pixel solicitadas, mas corresponderá com a taxa de proporção. Em alguns casos, uma miniatura maior do que a solicitada pode retornar, se a miniatura já existir, e pode ser facilmente dimensionada para coincidir com a resolução solicitada.

Comentários

Observação No OneDrive for Business e no SharePoint:

O uso dessas chamadas para expandir a coleção de miniaturas não funcionará:

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

Não há suporte para miniaturas no SharePoint Server 2016.

Respostas de erros

Confira mais informações sobre como os erros são retornados em Respostas de Erros.