Share via


Listar miniaturas para um driveItem

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Recupere uma coleção de recursos thumbnailSet para um recurso driveItem .

Zero ou mais recursos de miniaturaConjuntos podem representar um driveItem. 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á muitas 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

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.Read Files.Read.All, Files.ReadWrite, 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.

Além disso, esse método dá suporte à recuperação da miniatura com o valor EXIF de orientação original e sem a rotação aplicada acrescentando o originalOrientation=true parâmetro de consulta. Atualmente, ele só tem suporte no OneDrive Personal.

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

O exemplo a seguir mostra uma solicitação que recupera miniaturas disponíveis para um item no OneDrive do usuário atual.

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

Ele retorna uma matriz de conjuntos de miniaturas 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

O exemplo a seguir mostra a 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, o índice será 0.
size string O tamanho da miniatura solicitada. Ele pode ser 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": "https://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 será alterada, se o item for alterado de uma forma que exija que uma nova miniatura seja gerada.

Obtendo miniaturas ao listar driveItems

Se você estiver recuperando uma lista de recursos driveItem a serem exibidos, poderá usar o parâmetro de cadeia de caracteres de consulta $expand para incluir também as miniaturas desses recursos. Ele 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..."
                   }
        }
      ]
    }
  ]
}

Valores 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. Ele funciona redimensionando a imagem para preencher a caixa 300x400 e cortando o que for derramado fora da caixa.

Nota: A miniatura retornada pode não corresponder exatamente às dimensões de pixel que foram solicitadas, mas corresponde à proporção de aspecto. 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 funciona:

  • 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

Consulte Respostas de erro para obter mais informações sobre como os erros são retornados.