Listar miniaturas para um DriveItem

Namespace: microsoft.graph

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

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

Serviço global	Governo dos EUA L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos 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 com privilégios mais elevados
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
Application	Files.Read.All	Files. ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Observação

O SharePoint Embedded requer a FileStorageContainer.Selected permissão para acessar o conteúdo do contêiner. Essa permissão é diferente das mencionadas anteriormente. Além das permissões do Microsoft Graph, seu aplicativo deve ter as permissões de tipo de contêiner necessárias para chamar essa API. Para obter mais informações, consulte Autenticação e autorização do SharePoint Embedded.

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 $select ao parâmetro de consulta OData para personalizar a resposta.

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

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

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.

Exemplos

Exemplo 1: recuperar miniaturas disponíveis para um item no OneDrive do usuário atual

Solicitação

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Thumbnails.GetAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
thumbnails, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Thumbnails().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ThumbnailSetCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").thumbnails().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->thumbnails()->get()->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').thumbnails.get()

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

Exemplo 2: obter uma única miniatura

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

Solicitação

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

Snippet not available

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

let response = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}')
	.get();

Snippet not available

Snippet not available

Snippet not available

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.

Resposta#

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

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

Exemplo 3: recuperar conteúdo binário em miniatura

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

Solicitação

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

Snippet not available

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

let content = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content')
	.get();

Snippet not available

Snippet not available

Snippet not available

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.

Exemplo 4: Obtendo 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

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Children.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "thumbnails" };
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.ItemItemsItemChildrenRequestBuilderGetQueryParameters{
	Expand: [] string {"thumbnails"},
}
configuration := &graphdrives.ItemItemsItemChildrenRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
children, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Children().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItemCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").children().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"thumbnails"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let children = await client.api('/me/drive/items/{item-id}/children')
	.expand('thumbnails')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Children\ChildrenRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ChildrenRequestBuilderGetRequestConfiguration();
$queryParameters = ChildrenRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["thumbnails"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->children()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemChild -DriveId $driveId -DriveItemId $driveItemId -ExpandProperty "thumbnails"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.children.children_request_builder import ChildrenRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ChildrenRequestBuilder.ChildrenRequestBuilderGetQueryParameters(
		expand = ["thumbnails"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').children.get(request_configuration = request_configuration)

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

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

Exemplo 5: solicitar tamanhos de miniaturas personalizados

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:

Solicitação

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Thumbnails.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "c300x400_crop" };
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

requestParameters := &graphdrives.ItemItemsItemThumbnailsRequestBuilderGetQueryParameters{
	Select: [] string {"c300x400_crop"},
}
configuration := &graphdrives.ItemItemsItemThumbnailsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
thumbnails, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Thumbnails().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ThumbnailSetCollectionResponse result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").thumbnails().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"c300x400_crop"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails?select=c300x400_crop')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Thumbnails\ThumbnailsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ThumbnailsRequestBuilderGetRequestConfiguration();
$queryParameters = ThumbnailsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["c300x400_crop"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->thumbnails()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId -Property "c300x400_crop"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.thumbnails.thumbnails_request_builder import ThumbnailsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ThumbnailsRequestBuilder.ThumbnailsRequestBuilderGetQueryParameters(
		select = ["c300x400_crop"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').thumbnails.get(request_configuration = request_configuration)

Resposta

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.

Comentários

Esta página foi útil?

Last updated on 2025-07-24

Listar miniaturas para um DriveItem

Permissões

Solicitação HTTP

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Resposta

Exemplos

Exemplo 1: recuperar miniaturas disponíveis para um item no OneDrive do usuário atual

Solicitação

Resposta

Exemplo 2: obter uma única miniatura

Solicitação

Parâmetros do caminho

Resposta#

Exemplo 3: recuperar conteúdo binário em miniatura

Solicitação

Resposta

Exemplo 4: Obtendo miniaturas ao listar DriveItems

Solicitação

Resposta

Exemplo 5: solicitar tamanhos de miniaturas personalizados

Solicitação

Resposta

Exemplos de identificadores personalizados

Comentários

Respostas de erros

Comentários

Recursos adicionais