列出 DriveItem 的缩略图
本文内容
命名空间: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
可选的查询参数
此方法支持 $select
OData 查询参数 来自定义响应。
此外,此方法支持通过追加查询参数来检索具有原始方向 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();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// 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();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->thumbnails()->get()->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Files
Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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()
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
这将返回项的可用 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}
const options = {
authProvider,
};
const client = Client.init(options);
let response = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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
const options = {
authProvider,
};
const client = Client.init(options);
let content = await client.api('/me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
本服务通过到缩略图 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" };
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// 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"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// 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"};
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let children = await client.api('/me/drive/items/{item-id}/children')
.expand('thumbnails')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?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();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Files
Get-MgDriveItemChild -DriveId $driveId -DriveItemId $driveItemId -ExpandProperty "thumbnails"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
本服务通过 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" };
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items thumbnails list --drive-id {drive-id} --drive-item-id {driveItem-id}
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// 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"};
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let thumbnails = await client.api('/me/drive/items/{item-id}/thumbnails?select=c300x400_crop')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?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();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Files
Get-MgDriveItemThumbnail -DriveId $driveId -DriveItemId $driveItemId -Property "c300x400_crop"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
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)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应只包含选定的自定义缩略图尺寸:
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 不支持缩略图。
错误响应
请参阅错误响应 ,详细了解错误返回方式。