Вывод списка эскизов для объекта driveItem

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Получение коллекции ресурсов thumbnailSet для ресурса driveItem .

Не более ресурсов thumbnailSet может представлять объект driveItem. Каждый ресурс thumbnailSet может включать один или несколько объектов thumbnail — изображений, представляющих элемент. К примеру, ресурс thumbnailSet может включать такие распространенные объекты thumbnail, как small, medium и large.

Существует множество способов работы с эскизами в OneDrive. Ниже представлены наиболее распространенные из них.

  • Перечисление доступных эскизов элемента
  • Получение одного эскиза элемента
  • Получение содержимого эскиза
  • Получение эскизов нескольких элементов в одном запросе
  • Получение эскизов настраиваемых размеров
  • Отправка пользовательского эскиза элемента
  • Определение того, существует ли отправленный пользовательский эскиз

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) 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 Personal.

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию объектов ThumbnailSet в теле отклика.

Пример

В следующем примере показан запрос, который получает доступные эскизы для элемента в OneDrive текущего пользователя.

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

Он возвращает массив доступных наборов эскизов для элемента. У любого элемента в объекте drive может быть один или несколько эскизов (либо ни одного эскиза).

Примечание. С помощью параметра 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}

Параметры пути

Имя Тип Описание
item-id string Уникальный идентификатор элемента.
thumb-id number Индекс эскиза (как правило, 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..."
                   }
        }
      ]
    }
  ]
}

Значения размера

В этой таблице определены возможные размеры эскизов. Хотя вы можете указать в запросе произвольный размер эскиза, определенные значения встречаются намного чаще и позволяют быстрее получить результат.

Имя Разрешение Пропорции Описание
small 96 для большей стороны Исходные Небольшой эскиз с сильным сжатием, обрезанный до квадрата.
medium 176 для большей стороны Исходные Обрезан до стандартного размера элемента для веб-представления OneDrive.
large 800 для большей стороны Исходные Эскиз, длина большей стороны которого изменена на 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 для бизнеса и SharePoint:

Использование этих вызовов для расширения коллекции эскизов не работает:

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

Эскизы не поддерживаются в SharePoint Server 2016.

Ответы с ошибками

Дополнительные сведения о том, как возвращаются ошибки, см. в разделе Ответы на ошибки.