Список эскизов для ресурса DriveItemList thumbnails for a DriveItem

Получение коллекции ресурсов ThumbnailSet для ресурса DriveItem.Retrieve a collection of ThumbnailSet resources for a DriveItem resource.

Ресурс DriveItem представляют ресурсы ThumbnailSet, количество которых может быть нуль и более. Каждый ресурс thumbnailSet может включать один или несколько объектов thumbnail — изображений, представляющих элемент. К примеру, ресурс thumbnailSet может включать такие распространенные объекты thumbnail, как small, medium и large.A DriveItem can be represented by zero or more ThumbnailSet resources. Each thumbnailSet can have one or more thumbnail objects, which are images that represent the item. For example, a thumbnailSet may include thumbnail objects, such as common ones including small, medium, or large.

Работать с эскизами в OneDrive можно множеством способов. Ниже представлены наиболее распространенные из них.There are many ways to work with thumbnails on OneDrive. Here are the most common ones:

  • Перечисление доступных эскизов элементаEnumerate available thumbnails for an item
  • Получение одного эскиза элементаRetrieve a single thumbnail for an item
  • Получение содержимого эскизаRetrieve thumbnail content
  • Получение эскизов нескольких элементов в одном запросеRetrieve thumbnails for multiple items in a single request
  • Получение эскизов настраиваемых размеровRetrieve custom thumbnail sizes
  • Отправка пользовательского эскиза элементаUpload a custom thumbnail for an item
  • Определение того, существует ли отправленный пользовательский эскизDetermine if a custom uploaded thumbnail exists

РазрешенияPermissions

Для вызова этого API требуется одно из указанных ниже разрешений. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Тип разрешенияPermission type Разрешения (в порядке повышения привилегий)Permissions (from least to most privileged)
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)Delegated (personal Microsoft account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Для приложенийApplication Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP-запросHTTP request

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

Необязательные параметры запросовOptional query parameters

Этот метод поддерживает параметр запросов OData $select для настройки отклика.This method supports the $select OData puery parameter to customize the response.

ОткликResponse

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию объектов ThumbnailSet в теле отклика.If successful, this method returns a 200 OK response code and collection of ThumbnailSet objects in the response body.

ПримерExample

Ниже представлен пример запроса на получение доступных эскизов элемента в хранилище OneDrive текущего пользователя.Here is an example of the request which retrieves available thumbnails for an item in the current user's OneDrive.

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

Этот запрос возвращает массив доступных объектов thumbnailSet для элемента.This returns an array of available thumbnailSets for the item. У любого элемента в объекте drive может быть один или несколько эскизов (либо ни одного эскиза).Any item in a drive can have zero or more thumbnails.

Примечание. С помощью параметра select строки запроса вы можете указывать размеры эскизов, возвращаемых в объекте ThumbnailSet.Note: You can use the select query string parameter to control which thumbnail sizes are returned in the ThumbnailSet. Например, запрос /thumbnails?select=medium получает только эскизы среднего размера.For example, /thumbnails?select=medium retrieves only the medium sized thumbnails.

ОткликResponse

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

Получение одного эскизаGet a single thumbnail

Получение метаданных для одного эскиза и размера с помощью прямого запроса.Retrieve the metadata for a single thumbnail and size by addressing it directly in a request.

HTTP-запросHTTP request

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

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

ИмяName ТипType ОписаниеDescription
item-iditem-id stringstring Уникальный идентификатор элемента.The unique identifier for the item referenced.
thumb-idthumb-id numbernumber Индекс эскиза (как правило, 0–4).The index of the thumbnail, usually 0-4. Если присутствует пользовательский эскиз, для него задается индекс 0.If there is a custom thumbnail, its index is 0.
sizesize stringstring Размер запрашиваемого эскиза.The size of the thumbnail requested. Это должен быть один из стандартных размеров, указанных ниже, либо пользовательский размер.This can be one of the standard sizes listed below or a custom size.
HTTP/1.1 200 OK
Content-Type: application/json

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

Получение двоичного содержимого эскизаRetrieve thumbnail binary content

Вы можете получить содержимое эскиза напрямую, запросив свойство content этого эскиза.You can directly retrieve the content of the thumbnail by requesting the content property of the thumbnail.

HTTP-запросHTTP request

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content

ОткликResponse

В ответ служба выполняет перенаправление на URL-адрес эскиза.The service responds with a redirect to the thumbnail URL.

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

URL-адреса эскизов не кэшируются.Thumbnail URLs are cache-safe. Если в результате изменения элемента потребуется создать новый эскиз, изменится его URL-адрес.The URL will change, if the item changes in a way that requires a new thumbnail to be generated.

Получение эскизов при перечислении ресурсов DriveItemGetting thumbnails while listing DriveItems

При получении списка отображаемых ресурсов DriveItem можно использовать параметр строки запроса $expand, чтобы также включить эскизы этих ресурсов.If you are retrieving a list of DriveItem resources to display, you can use the $expand query string parameter to also include the thumbnails for those resources. Благодаря этому приложение может получить эскизы и элементы в одном запросе.This enables your app to retrieve thumbnails and items in a single request, instead of issuing many requests.

HTTP-запросHTTP request

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

ОткликResponse

Служба возвращает список ресурсов DriveItem и их эскизов.The service responses with the list of DriveItems and their thumbnails.

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 options

В этой таблице определены возможные размеры эскизов. Хотя вы можете указать в запросе произвольный размер эскиза, определенные значения встречаются намного чаще и позволяют быстрее получить результат.This table defines the possible thumbnail sizes. While you can request any arbitrary thumbnail size, the defined values are likely to exist and return a value quickly:

ИмяName РазрешениеResolution ПропорцииAspect Ratio ОписаниеDescription
small 96 для большей стороны96 longest ИсходныеOriginal Небольшой эскиз с сильным сжатием, обрезанный до квадрата.Small, highly compressed thumbnail cropped to a square aspect ratio.
medium 176 для большей стороны176 longest ИсходныеOriginal Обрезан до стандартного размера элемента для веб-представления OneDrive.Cropped to the standard item size for the OneDrive web view.
large 800 для большей стороны800 longest ИсходныеOriginal Эскиз, длина большей стороны которого изменена на 800 пикселей.Thumbnail with the longest edge resized to 800 pixels.
smallSquare 96x9696x96 Квадратная обрезкаSquare Crop Небольшой квадратный эскизSmall square thumbnail
mediumSquare 176x176176x176 Квадратная обрезкаSquare Crop Небольшой квадратный эскизSmall square thumbnail
largeSquare 800x800800x800 Квадратная обрезкаSquare Crop Большой квадратный эскизLarge square thumbnail

Запрос эскизов настраиваемых размеровRequesting custom thumbnail sizes

Помимо определенных размеров, приложение может запрашивать эскизы настраиваемых размеров, указав ширину и высоту с префиксом c.In addition to the defined sizes, your app can request a custom thumbnail size by specifying the dimensions of the thumbnail prefixed with c. Например, если вашему приложению нужны эскизы размером 300x400, оно может запросить размер следующим образом:For example if your app needs thumbnails that are 300x400, it can request that size like this:

GET /me/drive/items/{item-id}/thumbnails?select=c300x400_Crop

В ответ вы получите только эскиз выбранного размера:Which responds with just the custom thumbnail size selected:

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

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

Запросив размер эскиза, вы можете указать следующие параметры:You can specify the following options after the size of the thumbnail requested:

Примеры пользовательских идентификаторовExamples of custom identifiers

Идентификатор эскизаThumbnail identifier РазрешениеResolution ПропорцииAspect ratio ОписаниеDescription
c300x400c300x400 Заключен в прямоугольник размером 300x400Bounded by 300x400 box ИсходныеOriginal Создается эскиз, который помещается в прямоугольник размером 300x400 пикселей с сохранением пропорций.Generate a thumbnail that fits inside a 300x400 pixel box, maintaining aspect ratio
c300x400_Cropc300x400_Crop 300x400300x400 ОбрезанныйCropped Создается эскиз размером 300x400.Generate a thumbnail that is 300x400 pixels. Сначала размер изображения меняется так, чтобы оно помещалось в прямоугольник размером 300x400, а затем обрезается все, что выходит за пределы прямоугольника.This works by resizing the image to fill the 300x400 box and cropping whatever spills outside the box.

Примечание. Размер возвращаемого эскиза в пикселях может не полностью совпадать с запрашиваемым, но его пропорции будут соответствовать запросу.Note: The thumbnail returned may not exactly match the pixel dimensions that was requested, but will match the aspect ratio. В некоторых случаях возвращаются эскизы большего размера, если эскиз уже существует и легко масштабируется до запрашиваемого разрешения.In some cases, a larger thumbnail may be returned than was requested, if the thumbnail already exists and can easily be scaled to match the requested resolution.

ЗамечанияRemarks

Примечание. В OneDrive для бизнеса и SharePoint:Note In OneDrive for Business and SharePoint:

С помощью таких вызовов невозможно дополнить коллекцию эскизов:Using these calls to expand the thumbnails collection will not work:

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

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

Отклики с ошибкамиError responses

Дополнительные сведения о том, как возвращаются ошибки, см. в статье Ошибки.See Error Responses for more info about how errors are returned.