ADN Open CIS
Сообщество программистов Autodesk в СНГ

20/07/2015

Возможности API. Сервис для просмотра Viewing Service (Продолжение)

Первая часть

API для работы с элементами (Items API)

HEAD Items

При запросе заголовка API возвращает тот же самый набор, что и при вызове GET запроса. Заголовок может быть полезен для получения размера содержимого (Content-Length) перед получением потока данных.

HEAD /viewingservice/v1/items/{urn}

Пример запроса

Код: [Выделить]
  1. HEAD  /viewingservice/v1/items/urn%3Aadsk.viewing%3Afs.file%3AsZS5kd2Y%3D%2Foutput%2F1%2F0.svf HTTP/1.1

Пример успешного ответа:

Код: [Выделить]
  1. 200 with the same set of headers of GET this item

Параметры:

  • urn – обязательный. URN запрашиваемого элемента. Валидным является только URN сервиса для просмотра в виде urn:adsk.viewing:fs.file:url-safe-base64-encoded-seed-urn/rest/of/the/path

Заголовки запроса:

  • Range – необязательный. Согласно стандарту RFC 2616 заголовок Range задает ограничение возвращаемых данных. Например, Range:0-63 возвратит только первые 64 байта. Если Range не задан, то содержимое будет возвращено целиком.

Статусы:

  • 200 – OK. Объект найден. Информация по нему возвращена.
  • 400 – не верный запрос. Например, формат URN неправильный или параметр Range задан неверно
  • 404 – не найден. По заданному URN объект не найден
  • 500 – Внутренняя ошибка сервера. На сервере произошла непредвиденная ошибка.

 

GET Items

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

GET /viewingservice/v1/items/{urn}

Пример запроса:

Код: [Выделить]
  1. GET  /viewingservice/v1/items/urn%3Aadsk.viewing%3Afs.file%3AdXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2Y%3D%2Foutput%2F1%2F0.svf HTTP/1.1

Пример возвращаемого результата:

Код: [Выделить]
  1. 200 с содержимым в теле ответа.

Статусы:

  • 200 – OK. Объект найден. Информация по нему возвращена.
  • 400 – не верный запрос. Например, формат URN неправильный или параметр Range задан неверно
  • 404 – не найден. По заданному URN объект не найден
  • 500 – Внутренняя ошибка сервера. На сервере произошла непредвиденная ошибка.

API для работы с миниатюрами (Thumbnails API)

Получение миниатюр

Thumbnails API позволяет получить миниатюрные изображения в PNG формате.

GET /viewingservice/v1/thumbnails/{urn}?guid=$GUID$ & width=$WIDTH$ & height=$HEIGHT$ (& type=$TYPE$)

Примеры запросов:

Код: [Выделить]
  1. GET  /viewingservice/v1/thumbnails/dXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2

Код: [Выделить]
  1. GET  /viewingservice/v1/thumbnails/dXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2Y=?width=150&height=150 HTTP/1.1

Код: [Выделить]
  1. GET  /viewingservice/v1/thumbnails/dXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2Y=?type="medium" HTTP/1.1

Код: [Выделить]
  1. GET  /viewingservice/v1/thumbnails/dXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2Y=?guid=067e6162-3b6f-4ae2-a171-2470b63dff12 HTTP/1.1

Код: [Выделить]
  1. GET  /viewingservice/v1/thumbnails/dXJuOmFkc2suczM6pY2UvYXBpL3NhbXBsZS5kd2Y=?guid=067e6162-3b6f-4ae2-a171-2470b63dff12&width=230&height=230 HTTP/1.1

Пример возвращаемого результата:

Код: [Выделить]
  1. 200 с содержимым в теле ответа.

Параметры:

  • urn – обязательный. URN запрашиваемого элемента. Валидным является только URN сервиса для просмотра в виде urn:adsk.viewing:fs.file:url-safe-base64-encoded-seed-urn/rest/of/the/path
  • guid – не обязательный. Идентификатор подмножества видимых объектов.
  • widht – не обязательный. Ширина миниатюры
  • height – не обязательный. Высота миниатюры.
  • type – не обязательный. Тип запрашиваемой миниатюры. Может быть одним из следующих значений: small, medium, large. Параметры высоты и ширины будут при этом игнорироваться.

Заголовки запроса:

  • Range – необязательный. Согласно стандарту RFC 2616 заголовок Range задает ограничение возвращаемых данных. Например, Range:0-63 возвратит только первые 64 байта. Если Range не задан, то содержимое будет возвращено целиком.

Статусы:

  • 200 – OK. Объект найден. Миниатюра возвращена
  • 202 – Принято. Генерация миниатюры в процессе.
  • 204 – Нет содержимого. Миниатюра по каким-то причинам не было сгенерирована.
  • 400 – не верный запрос. Например, формат URN неправильный.
  • 404 – объект для просмотра не был создан
  • 500 – Внутренняя ошибка сервера. На сервере произошла непредвиденная ошибка.

 

API для работы со средством просмотра (Viewers API)

GET Viewer

Данное API возвращает основные компоненты для просмотра модели. Стоит отметить, что для вызова методов этого API не требуется аутентификация.

GET /viewingservice/v1/viewers/{file}?v={file_version}

Примеры запросов:

Код: [Выделить]
  1. GET    /viewingservice/v1/viewers/index.html HTTP/1.1

Код: [Выделить]
  1. GET    /viewingservice/v1/viewers/style.css  HTTP/1.1

Параметры:

  • file– обязательный. Компонент средства для просмотра, который необходимо получить. Может принимать следующие значения:
    • index.html – является готовой страничкой со средством просмотра. Может непосредственно встраиваться в вашу страницу.
    • style.css – каскадная таблица стилей. Может быть использована в случае, если клиент желает использовать стили средства для просмотра на своей пользовательской странице.
    • Viewer3D.min.js – является ядром средства для просмотра моделей. Используется в случае, если пользователь хочет кастомизировать функциональность средства для просмотра.
    • v – не обязательный. Версия компонентов средства для просмотра. Поддерживаются маски, например, v1.0.1, v1.0.*, v1.*.*
      Если не задан, то будет использована последняя версия. Если задана, конкретная версия, то будет использована она. Если задана маска, то будет использована последняя версия, удовлетворяющая маске.

Статусы:

  • 303 – Смотреть другое. Указанный файл необходимо искать на другом сервере.
  • 400 – не верный запрос. Например, неверно задан параметр
  • 404 – указанный файл или версия не найдена.
  • 500 – Внутренняя ошибка сервера. На сервере произошла непредвиденная ошибка.

 

Supported API

API предназначено для предоставление следующей информации:

  • Поддерживаемые расширения файлов
  • Расширения для направления наложений
  • Информация о регулярных выражениях

GET /viewingservice/v1/supported

Пример запроса:

Код: [Выделить]
  1. GET   /viewingservice/v1/supported HTTP/1.1

Пример ответа:

Код: [Выделить]
  1. HTTP/1.1 200 OK
  2.     {
  3.     "extensions": [
  4.         "ipt",
  5.         "neu",
  6.         "stla",
  7.         "stl",
  8.         "xlsx",
  9.         "jt",
  10.         "jpg",
  11.         "skp",
  12.         "prt",
  13.         "dwf",
  14.         "xls",
  15.         "png",
  16.         "sldasm",
  17.         "step"
  18.     ],
  19.     "channelMapping": {
  20.         "ipt": "viewing-inventor",
  21.         "neu": "viewing-atf-lmv",
  22.         "stla": "viewing-atf-lmv",
  23.         "stl": "viewing-atf-lmv",
  24.         "xlsx": "extraction-tika",
  25.         "jt": "viewing-atf-lmv",
  26.         "jpg": "extraction-tika",
  27.         "skp": "viewing-atf-lmv",
  28.         "prt": "viewing-atf-lmv",
  29.         "dwf": "viewing-dwf-lmv",
  30.         "xls": "extraction-tika",
  31.         "png": "extraction-tika",
  32.         "sldasm": "viewing-atf-lmv",
  33.         "step": "viewing-atf-lmv",
  34.         "axm": "viewing-axm",
  35.         "dwg": "viewing-dwg-lmv",
  36.         "zip": "viewing-assimp",
  37.         "model": "viewing-atf-lmv",
  38.         "sim": "viewing-sim-lmv",
  39.         "stp": "viewing-atf-lmv",
  40.         "ste": "viewing-atf-lmv"
  41.     },
  42.     "regExp": {
  43.         "prt\\.\\d+{{html}}quot;: "viewing-atf-lmv",
  44.         "neu\\.\\d+{{html}}quot;: "viewing-atf-lmv",
  45.         "asm\\.\\d+{{html}}quot;: "viewing-atf-lmv"
  46.     }
  47.     }

Заголовки запроса:

  • If-Modified-Since – не обязательный. Будет возвращен только тот список поддерживаемых форматов, которые были добавлены после указанной даты.

Заголовки ответа:

  • Last-Modified – дата последнего измения

Статусы:

  • 200 – ОК. Успешный результат.
  • 304 – Нет изменений. Запрашиваемые данные не менялись с момента даты, указанной в заголовке Last-Modified.
  • 500 – Внутренняя ошибка сервера. На сервере произошла непредвиденная ошибка.

Общие коды ошибок REST

Статус ошибки HTTP

Название

Комментарии

400

BAD REQUEST – не верный запрос

Запрос в неверном формате

401

UNAUTHORIZED – неавторизованный запрос

Попытка доступа к содержимому без авторизации. Например, не передан токен.

403

FORBIDDEN – Доступ запрещен

Доступ к указанному ресурсу запрещен с текущей авторизацией

404

NOT FOUND – Не найдно

Запрашиваемый метод не найден. Или не найден запрашиваемый ресурс.

405

METHOD NOT ALLOWED – Метод не разрешен

Данный метод не разрешено выполнять с переданным URN

409

CONFLICT - Конфликт

Запрос не может быть выполнен из-за конфликтного обращения к ресурсу. Такое возможно, например, когда два клиента пытаются изменить ресурс

429

TOO MANY REQUESTS – Слишком много запросов

Отправлено слишком много запросов за короткое время

500

INTERNAL SERVER ERROR – Внутренняя ошибка сервера

На стороне сервера внутренние проблемы

502

BAD GATEWAY – Нет доступа к серверу

Проблемы с соединением

504

GATEWAY TIMEOUT – Истекло время ожидания при обращении к серверу

Проблемы с соединением

 

Источник: https://developer.autodesk.com/api/view-and-data-api/#items-api

Автор перевода: Виктор Чекалин

Обсуждение: http://adn-cis.org/forum/index.php?topic=2868

Опубликовано 20.07.2015
Отредактировано 20.07.2015 в 11:35:57