Enumerar miniaturas de un DriveItem

Artículo
10/02/2023

Espacio de nombres: microsoft.graph

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

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global	Gobierno de EE. UU. L4	Us Government L5 (DOD)	China operada por 21Vianet
✅	✅	✅	✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso	Permisos con privilegios mínimos	Permisos con privilegios más altos
Delegado (cuenta profesional o educativa)	Files.Read	Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft)	Files.Read	Files.Read.All, Files.ReadWrite, 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.

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 anexando el parámetro de originalOrientation=true consulta. Actualmente, solo se admite en OneDrive Personal.

Encabezados de solicitud

Nombre	Descripción
Authorization	{token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.

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

En el ejemplo siguiente se muestra una solicitud que recupera las miniaturas disponibles para un elemento de OneDrive del usuario actual.

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();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

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}

Snippet not available

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 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": "https://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

Snippet not available

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

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


// 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" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items children list --drive-id {drive-id} --drive-item-id {driveItem-id} --expand "thumbnails"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.children.children_request_builder import ChildrenRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = ChildrenRequestBuilder.ChildrenRequestBuilderGetQueryParameters(
		expand = ["thumbnails"],
)

request_configuration = ChildrenRequestBuilder.ChildrenRequestBuilderGetRequestConfiguration(
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)

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


// 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" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.thumbnails.thumbnails_request_builder import ThumbnailsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = ThumbnailsRequestBuilder.ThumbnailsRequestBuilderGetQueryParameters(
		select = ["c300x400_crop"],
)

request_configuration = ThumbnailsRequestBuilder.ThumbnailsRequestBuilderGetRequestConfiguration(
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)

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.

Enumerar miniaturas de un DriveItem

Permissions

Solicitud HTTP

Parámetros de consulta opcionales

Encabezados de solicitud

Respuesta

Ejemplo

Respuesta

Obtener una única miniatura

Solicitud HTTP

Parámetros de ruta de acceso

Recuperar el contenido binario de miniaturas

Solicitud HTTP

Respuesta

Obtención de miniaturas al enumerar recursos DriveItem

Solicitud HTTP

Respuesta

Opciones de tamaño

Solicitar tamaños personalizados de miniaturas

Ejemplos de identificadores personalizados

Comentarios

Respuestas de error

Comentarios

Comentarios

Recursos adicionales