列出 DriveItem 的缩略图

2024-07-04

命名空间：microsoft.graph

检索 DriveItem 资源的 ThumbnailSet 资源集合。

DriveItem 可以由零个或多个 ThumbnailSet 资源表示。每个 thumbnailSet 都可以有一个或多个 thumbnail 对象，此类对象是表示项目的图像。例如，thumbnailSet 可包括 thumbnail 对象，例如包括 small、medium 或 large 等常见对象。

可以通过多种方式在 OneDrive 上对缩略图进行操作。以下是一些最常见的操作：

枚举项目的可用缩略图
检索项目的单个缩略图
检索缩略图的内容
在单个请求中检索多个项目的缩略图
检索自定义缩略图的大小
上载项目的自定义缩略图
确定是否存在自定义的上传缩略图

此 API 可用于以下国家级云部署。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Files.Read	Files.Read.All、Files.ReadWrite、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户）	Files.Read	Files.Read.All、Files.ReadWrite、Files.ReadWrite.All
应用程序	Files.Read.All	Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All

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

可选的查询参数

此方法支持 $selectOData 查询参数来自定义响应。

此外，此方法支持通过追加查询参数来检索具有原始方向 EXIF 值且不应用旋转的 originalOrientation=true 缩略图。目前仅 OneDrive 个人版支持此操作。

请求标头

名称	说明
Authorization	持有者 {token}。必填。详细了解身份验证和授权。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 ThumbnailSet 对象集合。

示例

以下示例显示了一个请求，该请求检索当前用户的 OneDrive 中某个项的可用缩略图。

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



mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}



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

这将返回项的可用 thumbnailSet 的数组。驱动器中的任何项都可以有零个或多个缩略图。

注意：可以使用 select 查询字符串参数，控制在 ThumbnailSet 中返回的缩略图尺寸。例如，/thumbnails?select=medium 仅检索中等大小的缩略图。

响应

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

获取单个缩略图

通过在请求中直接解决来检索单个缩略图和大小的元数据。

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

Path 参数

名称	类型	说明
item-id	string	引用的项目的唯一标识符。
thumb-id	数字	缩略图的索引，通常介于 0 到 4 之间。如果没有自定义缩略图，索引为 0。
size	string	请求获取的缩略图的尺寸。可取值为下面列出的标准大小之一或自定义大小。

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

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

检索缩略图的二进制内容

可以通过请求缩略图的 content 属性直接检索缩略图的内容。

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

响应

本服务通过到缩略图 URL 的重定向进行响应。

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

缩略图 URL 具有缓存安全性。如果在项发生更改后需要生成新的缩略图，URL 将会更改。

获取缩略图的同时列出 DriveItem

如果检索要显示的 DriveItem 资源的列表，可以使用 $expand 查询字符串参数，以便同时包含这些资源的缩略图。这使你的应用可以通过一个请求同时检索缩略图和项，而不是发出多个请求。

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



mgc drives items children list --drive-id {drive-id} --drive-item-id {driveItem-id} --expand "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)

响应

本服务通过 DriveItem 及其缩略图的列表进行响应。

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

大小选项

下表定义了可能的缩略图大小。虽然可以请求任意的缩略图大小，但可能存在定义的有并迅速返回值：

名称	分辨率	纵横比	说明
`small`	96 longest	Original	小型的高压缩缩略图，裁剪为正方形纵横比。
`medium`	176 longest	Original	裁剪为 OneDrive Web 视图的标准项目大小。
`large`	800 longest	Original	最长边重设为 800 像素的缩略图。
`smallSquare`	96x96	方形裁剪	小方形缩略图
`mediumSquare`	176x176	方形裁剪	小方形缩略图
`largeSquare`	800x800	方形裁剪	大方形缩略图

请求自定义缩略图的大小

除了定义尺寸外，应用还可以指定前缀为 c 的缩略图尺寸，从而请求获取自定义缩略图尺寸。例如，如果你的应用需要 300x400 的缩略图，可以按如下所示请求获取此大小：

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



mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}



// 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)

响应只包含选定的自定义缩略图尺寸：

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

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

可以在请求获取的缩略图尺寸后指定以下选项：

自定义标识符示例

缩略图标识符	分辨率	纵横比	说明
c300x400	300x400 像素框	原始大小	生成适应在 300x400 像素框中显示的缩略图，纵横比不变
c300x400_crop	300x400	已裁剪	生成 300x400 像素缩略图。具体方式为，重设图像大小以填充 300x400 框，并裁剪超出框外的内容。

注意：返回的缩略图可能与请求的像素尺寸不完全匹配，但与纵横比匹配。在某些情况下，如果缩略图已经存在并且可以轻松缩放来匹配请求的分辨率，则可能会返回比请求的大小更大的缩略图。

备注

注意在 OneDrive for Business 和 SharePoint 中：

使用这些调用展开缩略图集合不适用于：

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

SharePoint Server 2016 不支持缩略图。

错误响应

请参阅错误响应，详细了解错误返回方式。

通过

列出 DriveItem 的缩略图

权限

HTTP 请求

可选的查询参数

请求标头

响应

示例

响应

获取单个缩略图

HTTP 请求

Path 参数

检索缩略图的二进制内容

HTTP 请求

响应

获取缩略图的同时列出 DriveItem

HTTP 请求

响应

大小选项

请求自定义缩略图的大小

自定义标识符示例

备注

错误响应

反馈

其他资源