Список эскизов для ресурса DriveItem
Получение коллекции ресурсов ThumbnailSet для ресурса DriveItem.
Ресурс DriveItem представляют ресурсы ThumbnailSet, количество которых может быть нуль и более.
Каждый ресурс thumbnailSet может включать один или несколько объектов thumbnail — изображений, представляющих элемент.
К примеру, ресурс thumbnailSet может включать такие распространенные объекты thumbnail, как small
, medium
и large
.
Работать с эскизами в OneDrive можно множеством способов. Ниже представлены наиболее распространенные из них.
- Перечисление доступных эскизов элемента
- Получение одного эскиза элемента
- Получение содержимого эскиза
- Получение эскизов нескольких элементов в одном запросе
- Получение эскизов настраиваемых размеров
- Отправка пользовательского эскиза элемента
- Определение того, существует ли отправленный пользовательский эскиз
Разрешения
Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.
Тип разрешения | Разрешения (в порядке повышения привилегий) |
---|---|
Делегированные (рабочая или учебная учетная запись) | Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
Делегированные (личная учетная запись Майкрософт) | Files.Read, Files.ReadWrite, Files.Read.All, 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 для настройки ответа.
Отклик
В случае успеха этот метод возвращает код отклика 200 OK
и коллекцию объектов ThumbnailSet в теле отклика.
Пример
Ниже представлен пример запроса на получение доступных эскизов элемента в хранилище OneDrive текущего пользователя.
GET /me/drive/items/{item-id}/thumbnails
Этот запрос возвращает массив доступных объектов thumbnailSet для элемента. У любого элемента в объекте 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": "http://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-адрес.
Получение эскизов при перечислении ресурсов DriveItem
При получении списка отображаемых ресурсов 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.
Отклики с ошибками
Дополнительные сведения о возвращении ошибок см. в статье Ответы с ошибками.