通过

列出 driveItem 的缩略图

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

检索 driveItem 资源的 thumbnailSet 资源的集合。

零个或多个 thumbnailSet 资源可以表示 driveItem。 每个 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

注意

SharePoint Embedded 需要 FileStorageContainer.Selected 权限才能访问容器的内容。 此权限不同于前面提到的权限。 除了Microsoft Graph 权限外，应用还必须具有调用此 API 所需的 容器类型权限 。 有关详细信息，请参阅 SharePoint Embedded 身份验证和授权。

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 个人版上受支持。

响应

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

示例

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

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

它返回项的可用 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}

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

响应

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

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

缩略图 URL 具有缓存安全性。 如果项目以需要生成新的缩略图的方式更改，则 URL 会更改。

列出 driveItems 时获取缩略图

如果要检索要显示的 driveItem 资源列表，则可以使用 $expand 查询字符串参数来同时包含这些资源的缩略图。 它使应用能够在单个请求中检索缩略图和项目，而不是发出多个请求。

HTTP 请求

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

响应

本服务通过 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..."
                   }
        }
      ]
    }
  ]
}

Size 的值

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

名称 分辨率 纵横比​​ 说明
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

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

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 不支持缩略图。

错误响应

有关 错误 返回方式的详细信息，请参阅错误响应。