На файловом хостинге есть описание как работать с ReST API.
Даже не знаю с какой стороны к этим API подойти, если кто-то сталкивался с этим подскажите пожалуйста как составлять запросы и как можно получить данные от запроса.
Даже не знаю с какой стороны к этим API подойти, если кто-то сталкивался с этим подскажите пожалуйста как составлять запросы и как можно получить данные от запроса.
Поддерживаемое API
Хранилище полностью поддерживает OpenStack Swift API и дополнительно Amazon S3 API.
Аутентификация
Для выполнения аутентификации нужно отправить GET запрос на url https://auth.selcdn.ru/ и передать следующие обязательные заголовки X-Auth-User и X-Auth-Key.
Где:
X-Auth-User - ваш номер договора (логин в общую панель управления http://support.selectel.ru/)
X-Auth-Key - пароль для данной услуги (он отличается от пароля для общей панели управления)
Эту информация вы можете получить на странице Хранилище - Файлы - Настройка доступа.
При успешной аутентификации будет получен HTTP ответ 204 (No Content) с заголовками X-Storage-Url и X-Auth-Token содержащие данные необходимые для выполнения всех остальных операций с хранилищем:
X-Storage-Url - базовый адрес для выполнения операций с хранилищем
X-Auth-Token - идентификатор авторизации (действителен 24 часа с момента первой аутентификации)
X-Expire-Auth-Token - точное время действия идентификатора авторизации в секундах
В случае ошибки аутентификации будет получен HTTP ответ 403 (Forbidden).
Пример:
$ curl -i https://auth.selcdn.ru/ \
-H "X-Auth-User:user" \
-H "X-Auth-Key
assword"
# вывод curl сокращен в целях удобочитаемости
> HTTP/1.1 204 No Content
> X-Expire-Auth-Token: 86029
> X-Storage-Url: https://xxx.selcdn.ru/
> X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12
Дополнительно поддерживается аутентификация по протоколу v2.0 (keystone api). Поддерживается только необходимый минимум этого протокола, поэтому некоторые расширенные возможности keystone могут не работать.
Пример аутентификации по v2.0 keystone:
$ curl -i -X POST https://auth.selcdn.ru/tokens \
-H 'Content-type: application/json' \
-d '{"auth": {"passwordCredentials": {"username": "user", "password": "password"}}}'
В качестве Tenant ID и Access Key следует указывать имя пользователя или дополнительного пользователя в Хранилище, в качестве Secret Key - пароль пользователя, Region - Common.
Операции с хранилищем
Во всех запросах к хранилищу должен передаваться заголовок X-Auth-Token, полученный при аутентификации, иначе будет получен отказ доступа. Исключение, скачивание файла из публичного контейнера.
Информация по хранилищу
HEAD запрос на адрес X-Storage-Url.
В заголовках ответа будет получена следующая информация:
X-Account-Bytes-Used - суммарный объём хранения данных в хранилище (в байтах)
X-Account-Container-Count - количество контейнеров
X-Account-Object-Count - суммарное количество хранимых объектов
X-Transfered-Bytes - скачено байт из хранилища (за всё время)
X-Received-Bytes - закачено байт в хранилище (за всё время)
Пример:
$ curl -I https://xxx.selcdn.ru/ \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
> X-Account-Object-Count: 5563
> X-Account-Bytes-Used: 6427888648
> X-Account-Container-Count: 27
> X-Received-Bytes: 110278989542
> X-Transfered-Bytes: 224961419192
Список контейнеров
GET запрос на адрес X-Storage-Url.
Дополнительные необязательные параметры запроса:
limit - число, ограничивает количество объектов в результате (по умолчанию 10000)
marker - строка, результат будет содержать объекты по значению больше указанного маркера (полезно использовать для постраничной навигации и при большом количестве контейнеров)
format - json или xml, результат будет выдан в указанном формате
За один запрос можно получить информацию максимум о 10000 контейнерах, если контейнеров больше, нужно использовать дополнительные запросы с параметром marker.
Примеры:
# получить листинг контейнеров с явным указание формата
$ curl -i https://xxx.selcdn.ru/\?format\=json \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> x-account-object-count: 5563
> x-account-bytes-used: 6427888648
> x-account-container-count: 27
> Content-Type: application/json; charset=utf-8
> Content-Length: 3033
> X-Received-Bytes: 110278989542
> X-Transfered-Bytes: 224978196408
>
> /* информация по контейнерам */
> [
> {
> /* место занимаемое содержимым контейнера */
> "bytes": 81292837,
> /* число объектов в контейнере */
> "count": 17,
> /* имя контейнера */
> "name": "container 1",
> /* всего закачанных в контейнер байт */
> "rx_bytes": 17936289,
> /* всего скачанных из контейнера байт */
> "tx_bytes": 11088956,
> /* тип контейнера */
> "type": "private"
> },
> {
> "bytes": 124355568,
> "count": 86,
> "name": "container 2",
> "rx_bytes": 296955064,
> "tx_bytes": 79205328,
> "type": "public"
> },
> ...
> ]
Создание контейнера
PUT запрос на адрес X-Storage-Url/container_name.
Имя контейнера должно быть меньше 256 символов и не содержать завершающего слеша '/' в конце.
HTTP ответы:
201 (Created) - при успешном создании
202 (Accepted) - если контейнер уже существует
К контейнеру можно привязать произвольные мета-данные через передачу заголовков с префиксом X-Container-Meta-.
Так же можно указать специальные заголовки, которые меняют функциональные свойства контейнера:
X-Container-Meta-Type - тип контейнера (public, private, gallery)
дополнительные заголовки кэшировани и CORS
Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: public" \
-H "X-Container-Meta-Some: some_specific_meta_data"
> HTTP/1.1 201 Created
Информация по контейнеру
HEAD запрос на адрес X-Storage-Url/container_name.
В заголовках ответа будет получена следующая информация:
X-Container-Object-Count - количество объектов в контейнере
X-Container-Bytes-Used - суммарный размер объектов в контейнере
X-Transfered-Bytes - скачено байт из контейнера
X-Received-Bytes - передано байт в контейнер
X-Container-Meta-Type - тип контейнера (public или private)
X-Container-Meta-Domains - привязанные домены к контейнеру
X-Container-Meta-* - заголовки с произвольной пользовательской информацией
Пример:
$ curl -I https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
> x-container-object-count: 0
> x-container-bytes-used: 0
> x-container-meta-type: public
> x-container-meta-some: some_specific_meta_data
> X-Container-Domains:
> X-Transfered-Bytes: 0
> X-Received-Bytes: 0
Изменение мета-данных контейнера
POST запрос на адрес X-Storage-Url/container_name и указать заголовки с префиксом X-Container-Meta- которые нужно установить или поменять.
HTTP ответы:
204 (No Content) - изменение выполнено
404 (Not Found) - указанный контейнер не существует
Пример:
# смена типа контейнера на личный и установка других метаданных
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: private" \
-H "X-Container-Meta-Some: any text"
> HTTP/1.1 204 No Content
Удаление контейнера
DELETE запрос на адрес X-Storage-Url/container_name.
Удаляемый контейнер должен быть пуст, иначе операция не будет выполнена.
HTTP ответы:
204 (No Content) - при успешном удалении
404 (Not Found) - указанный контейнер не существует
409 (Conflict) - ошибка удаления, контейнер не пустой
Пример:
$ curl -i -
ELETE https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
Галерея изображений
Контейнер можно преобразовать в галерею для удобного публичного представления в веб-браузере загруженных в нем фотографий и других изображений.
Создание галереи происходит путем установки типа контейнера gallery:
$ curl -i -XPUT https://xxx.selcdn.ru/gallery \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: gallery"
По умолчанию, галерея является публичной и доступ (только просмотр) к ней может получить любой. Но, дополнительно, можно установить пароль, по которому будет ограничен доступ. Для этого в запросе нужно передать заголовок X-Container-Meta-Gallery-Secret со значением sha1-хеша пароля. Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/gallery \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: gallery"
-H "X-Container-Meta-Gallery-Secret: 91dfd9ddb4198affc5c194cd8ce6d338fde470e2" # sha1-хеш пароля mypassword
Список файлов в контейнере
GET запрос на адрес X-Storage-Url/container_name.
Дополнительные необязательные параметры запроса:
limit - число, ограничивает количество объектов в результате (по умолчанию 10000)
marker - строка, результат будет содержать объекты по значению больше указанного маркера (полезно использовать для постраничной навигации и для большого количества файлов)
prefix - строка, вернуть объекты имена которых начинаются с указанного префикса
path - строка, вернуть объекты в указанной папке (виртуальные папки)
delimiter - символ, вернуть объекты до указанного разделителя в их имени
format - json или xml, результат будет выдан в указанном формате
За один запрос можно получить информацию максимум о 10000 файлах в контейнере, если в контейнере содержится больше файлов то нужно использовать дополнительные запросы с параметром marker.
Пример:
$ curl -i https://xxx.selcdn.ru/new_container/\?format\=json \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> x-container-meta-web-listings: on
> x-container-object-count: 4
> x-container-meta-access-control-request-method: HEAD, GET
> x-container-meta-web-listings-css: /my_style.css
> x-container-bytes-used: 1092
> x-container-meta-web-404-redirect: /trex_404.html
> x-container-meta-type: public
> x-container-meta-web-index: /my_index.html
> Content-Type: application/json; charset=utf-8
> Content-Length: 724
>
> /* информация о файлах */
> [
> {
> /* размер файла: */
> "bytes": 31,
> /* тип файла: */
> "content_type": "text/html",
> /* сколько раз данный файл был скачан: */
> "downloaded": 4,
> /* md5 хеш: */
> "hash": "b302ffc3b75770453e96c1348e30eb93",
> /* время загрузки файла: */
> "last_modified": "2013-05-27T14:42:04.669760",
> /* имя файла: */
> "name": "my_index.html"
> },
> {
> "bytes": 1024,
> "content_type": "application/octet-stream",
> "downloaded": 0,
> "hash": "0f343b0931126a20f133d67c2b018a3b",
> "last_modified": "2013-05-27T13:16:49.007590",
> "name": "new_object"
> },
> ...
> ]
Скачивание файла
GET запрос на адрес X-Storage-Url/container_name/path_to_file.
Указание заголовка X-Auth-Token необходимо только если файл находиться внутри личного (приватного) контейнера.
Путь к файлу может содержать символ '/' как виртуальную папку.
Хранилище поддерживает условные запросы в соответствии с RFC 2616, вы можете указывать следующие заголовки:
If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
Пример:
$ curl -O https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
Счётчик скачиваний файла
Получить информацию о количестве скачиваний для файла можно выполнив авторизованный HEAD или GET запрос на файл. Информация будет получена в виде дополнительного заголовка X-Object-Downloads в ответе.
Счётчик скачиваний может обновляться с задержкой до нескольких минут. При операциях изменения объекта (удаление, перемещение, загрузка заново) значение счётчика обнуляется.
Пример:
$ curl -I https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> X-Object-Downloads: 17
> last-modified: Mon, 27 May 2013 12:27:11 GMT
> etag: 0f343b0931126a20f133d67c2b018a3b
> Content-Length: 1024
> Content-Type: application/octet-stream
Загрузка файла
PUT запрос X-Storage-Url/container_name/path_to_file.
Файл может быть загружен только в контейнер, который должен существовать к моменту загрузки файла. Полное имя файла (включая виртуальные папки) не должно превышать 1024 байт после URL квотирования. Размер одного загружаемого файла не должен превышать 5 ГБ.
Загрузка может быть осуществлена целиком либо http-чанками. При загрузке целиком в заголовках должен быть указан размер файла в заголовке Content-Lenght. При загрузке чанками должен быть указан соответствующий заголовок Transfer-Encoding: chunked.
К файлу может быть прикреплены произвольные мета-данные через указание заголовков с префиксом X-Object-Meta-. Суммарный размер заголовков не должен превышать 4 КБ.
При загрузке файла можно указать специальный заголовок ETag содержащий контрольную сумму MD5. После загрузки файла будет проведена проверка сохранённых данных по контрольным суммам, это позволяет убедиться что данные сохранены верно.
Так же можно указать заголовок Content-Type для задания типа файла. Заголовок Content-Disposition влияет на то как браузер будет обрабатывать получение файла из Хранилища.
Хранилище поддерживает автоматически удаляемые файлы. Для создание таких файлов нужно передать один из следующих заголовков:
X-Delete-At - время когда нужно удалить файл, указывается целое число в unix timestamp
X-Delete-After - через какое время удалить файл, указывается в секундах
При успешной загрузке файла будет получен HTTP ответ 201 (Created) с заголовками Content-Lenght, Content-Type и Etag. В случае если при загрузке был указан заголовок ETag и проверка загруженных данных будет неудачна, то в ответ будет получен HTTP статус 422 (Unprocessable Entity).
Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Delete-After: 25200" \
-T "./example.gz"
> HTTP/1.1 100 Continue
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> Last-Modified: Mon, 27 May 2013 12:24:37 GMT
Распаковка архивов
Хранилище поддерживает возможность автоматической распаковки загружаемого архива. Поддерживаются следующие форматы архивов: tar, tar.gz, tar.bz2.
Для распаковки нужно при загрузке архива указать параметр запроса extract-archive=format, где за место format указать формат архива.
Пример загрузки архива с его распаковкой в хранилище:
# файлы будут распакованы в контейнер new_container
$ curl -i -X PUT 'https://xxx.selcdn.ru/new_container/?extract-archive=tar.bz2' \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-T "photos.tar.bz2"
В качестве пути для распаковки можно указывать контейнер, папку в контейнере или корень аккаунта. В последнем случае для папок первого уровня из архива будут созданы соответствующие контейнеры в хранилище.
После выполнения операции будет отдан ответ 200 с отчетом о результате распаковки. Поддерживается получение отчета в структурированном формате, для этого нужно при запросе указать заголовок Accept с одним из значений: text/plain, application/json, application/xml или text/xml.
Пример отчета в json формате:
{"Response Status": "201 Created",
"Response Body": "", "Errors": [], "Number Files Created": 1237}
Из отчета можно получить информацию о количестве распакованных файлов и список возникших ошибок при распаковки.
Установка мета-данных файла
POST запрос на адрес X-Storage-Url/container_name/path_to_file и указать заголовки с префиксом X-Object-Meta- которые нужно установить или поменять.
Внимание: установка мета-данных стирает все установленные ранее мета-данные для указанного файла и заменяет их на указанные в запросе.
HTTP ответы:
204 (No Content) - изменение выполнено
404 (Not Found) - указанный контейнер не существует
Пример:
$ curl -i -XPOST https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Object-Meta-Another: another"
> HTTP/1.1 202 Accepted
Копирование файлов в контейнерах
Можно копировать и перемещать файлы в пределах хранилища без повторной их загрузки. Операцию можно осуществить с помощью PUT или COPY запроса.
PUT запрос на X-Storage-Url/container_name/new_path_to_file с обязательным заголовком X-Copy-From содержащим путь к исходному файлу относительно корня хранилища (например, /container2/file3) и заголовком Content-Lenght равным нулю (0).
COPY запрос на X-Storage-Url/container_name/orig_path_to_file и заголовком Destination содержащим путь куда нужно копировать файл.
Для обоих запросов контейнер в который производиться копирование должен существовать.
При копировании также копируется и мета-данные о файле. Если в запросе указать заголовки с префиксом X-Object-Meta-, то для скопированного объекта будет установлены или перезаписаны (если они были в исходном файле) указанные мета-данные.
Пример:
# первый способ
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/first_copy \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Length: 0" \
-H "X-Copy-From: /new_container/new_object"
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> X-Copied-From: new_container/new_object
> X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
> Last-Modified: Tue, 28 May 2013 06:27:11 GMT
# второй способ
$ curl -i -XCOPY https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Destination: /new_container/second_copy"
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> X-Copied-From: new_container/new_object
> X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
> Last-Modified: Tue, 28 May 2013 06:30:51 GMT
Удаление файла
DELETE запрос на адрес X-Storage-Url/container_name/path_to_file.
HTTP ответы:
204 (No Content) - при успешном удалении
404 (Not Found) - если файла не существует
Пример:
$ curl -i -ELETE https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
Управление заголовками для файлов
Хранилище позволяет указывать специальные заголовки которые влияют на процесс получения файла из Хранилища. В частности, позволяют управлять кэшированием данных на стороне клиента и промежуточных прокси серверах, а так же задавать заголовки для обработки кросс-доменных запросов (CORS).
Поддерживаемые заголовки:
Cache-Control
Expires
Origin
Access-Control-Allow-Origin
Access-Control-Max-Age
Access-Control-Allow-Methods
Access-Control-Allow-Credentials
Access-Control-Expose-Headers
Access-Control-Request-Headers
Access-Control-Request-Method
Content-Disposition (только для конечного файла)
Strict-Transport-Security (только на уровне контейнера)
Вы можете установить значения по умолчанию для поддерживаемых заголовков на уровне контейнера. Для этого для контейнера нужно установить соответствующие мета-данные X-Container-Meta-<header>, где <header> заменить на нужный заголовок. После задания этих значений для всех отдаваемых данных (методом GET) из контейнера будет устанавливаться соответствующие заголовки.
Так же вы можете установить или переопределить значения по умолчанию для конктерного файла в хранилище, заданием соответствующих мета-данных.
Пример:
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Access-Control-Request-Method: HEAD, GET" \
-H "X-Container-Meta-Cache-Control: public" \
-H "X-Container-Meta-Strict-Transport-Security: max-age=31536000; includeSubDomains"
> HTTP/1.1 204 No Content
Ссылки на файл (symlink)
Ссылки позволяют предоставлять доступ к файлам в хранилище используя альтернативное имя. В частности, это даёт возможность открывать публичный доступ к файлам из личного контейнера, а так же доступ между пользователями на одном аккаунте.
Вы можете создать специальный объект-ссылку которая будет будет указывать на другой объект в хранилище (только на файл) и настроить ряд дополнительных параметров (ограничить время действия, задать пароль).
Создание ссылки: PUT запрос на адрес X-Storage-Url/container_name/link_name с указанием ряда заголовков.
Заголовки:
Content-Type - определяет тип ссылки, возможные значения:
x-storage/symlink - обычная ссылка
x-storage/onetime-symlink - одноразовая ссылка
x-storage/symlink+secure - обычная запароленная ссылка
x-storage/onetime-symlink+secure - одноразовая запароленная ссылка
X-Object-Meta-Location - цель ссылки, относительный заквотированный путь к объекту в хранилище (пример: /container/path/to%20file).
Content-Length: 0 - тело запроса обязательно должно быть пустым
X-Object-Meta-Delete-At - время до которого ссылка будет действительна (unix timestamp), необязательно заголовок.
X-Object-Meta-Link-Key - хеш ключа доступа к запароленной ссылке. Вычисление хеша: sha1(password + X-Object-Meta-Location).
Content-Disposition - перекрывает соответствующий заголовок объекта, на который указывает ссылка.
При обращение к объекту-ссылке (методом GET) в ответ будет получен объект на который она указывает. HEAD-запрос возвращает информацию о ссылке.
Для доступа к запароленной ссылке нужно в GET запросе указать параметр _sslk со значением пароля.
Объект-ссылка (но не цель ссылки) автоматически удаляется при истечение срока действия или при первом успешном скачивании для одноразовых ссылок.
Пример:
$ curl -i -XPUT http://xxx.selcdn.ru/new_container/new_link \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Type: x-storage/symlink" \
-H "X-Object-Meta-Location: /new_container/new_object" \
-H "X-Object-Meta-Link-Key: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c"\
-H "Content-Length: 0"
> HTTP/1.1 201 Created
> etag: d41d8cd98f00b204e9800998ecf8427e
> Last-Modified: Mon, 27 May 2013 13:34:34 GMT
Генерация ссылок для скачивания файлов
С помощью функции генерации ссылок можно создавать специальные ссылки для скачивания файлов, в том числе и из личных контейнеров. Срок действия ссылок ограничен.
В отличии от symlink, ссылки создаются без выполнения запросов к API. После создания ссылки невозможно отменить или удалить; они доступны в течении всего срока действия.
Чтобы генерировать ссылки, нужно предварительно установить секретный ключ. Для этого нужно задать метаданные X-Account-Meta-Temp-URL-Key для аккаунта. Пример:
$ curl -i -XPOST http://xxx.selcdn.ru/ \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Account-Meta-Temp-URL-Key: secret_word"
> HTTP/1.1 204 No Content
В примере задается секретный ключ secret_word. Его нужно запомнить (в дальнейшем все ссылки будут генерироваться с его помощью) и защитить от постороннего доступа (доступ к файлам может получить любой пользователь, знающий секретный ключ).
Алгоритм генерации ссылки для языка python:
import hmac
from hashlib import sha1
from time import time
# данные для генерации ссылки
method = "GET" # метод доступа (всегда GET)
expires = int(time()) + 60 # ссылка действительная 60 секунд
path = "/container/dir/file" # путь к файлу в хранилище, всегда с указанием контейнера
link_secret_key = "secret_word" # секретный ключ
# генерация ключа доступа
hmac_body = '%s\n%s\n%s' % (method, expires, path)
sig = hmac.new(link_secret_key, hmac_body, sha1).heigest() # ключ доступа
Полученный в результате ключ нужно будет указать в ссылке. Ссылка может выглядеть, например, так:
http://xxx.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
где xxx.selcdn.ru базовый домен, значение temp_url_sig - ключ доступа, temp_url_expires - время до которого ссылка действительна (unixtime).
Вместо базового домена можно указывать привязанный в контейнеру домен. В таком случае указывать имя контейнера в ссылке не нужно, например:
http://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
Дополнительно поддерживается управление заголовком Content-Disposition для отдаваемых по ссылке данных. Для этого нужно добавить параметр запроса filename с нужным значением. Пример:
http://xxx.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc
Секретный ключ при необходимости можно изменить, но в таком случае все сгенерированные ранее ссылки перестанут действовать.
Ссылки на загрузку файлов (sendmefile)
Ссылки на загрузку файлов - это специальная возможность позволяющая настроить загрузку файлов в Хранилище без авторизации. Она полезна когда вы хотите попросить кого-нибудь передать вам файлы, или для организации общего хранилища и даже для настройки резервного копирования. Ссылка на загрузку может быть использована для открытия в браузере и для работы с различными программами и утилитами, например, curl.
Сама ссылка создается как обычный файл в Хранилище для которого задаются специальные метаданные.
Поддерживается несколько типов ссылок, которые настраиваются указанием заголовка Content-Type:
x-storage/sendmefile - обычная ссылка на загрузку файлов
x-storage/sendmefile+inplace - загрузка только одного файла по указанному имени (имя ссылки является именем под которым будет сохранен загружаемый файл)
x-storage/sendmefile+timepostfix - загрузка файлов с добавлением времени загрузки в имема файлов (с учетом расширения файлов)
x-storage/sendmefile+autopostfix - загрузка файлов с добавлением уникального идентификатора в имема файлов (с учетом расширения файлов)
x-storage/sendmefile+folderday - загрузка файлов в папку с именем состоящим из даты загрузки (год и день)
x-storage/sendmefile+folderhour - загрузка файлов в папку с именем состоящим из даты и часа загрузки
x-storage/sendmefile+folderuniq - загрузка файлов в папку с уникальным именем
Ссылки поддерживают ряд необязательных настроек:
X-Object-Meta-Sendmefile-Disable-Web (yes|no) - отключение веб-интерфейса загрузки файлов (веб-интерфейс включен по умолчанию)
X-Object-Meta-Sendmefile-Max-Size - максимальный размер загружаемого файла в байтах, не допускаются значения больше 5 Гб
X-Object-Meta-Sendmefile-Allow-Overwrite (yes|no) - разрешить перезапись файла если он уже есть в Хранилище (по умолчанию перезапись запрещена)
X-Object-Meta-Sendmefile-Default-Expire - время хранения загруженного файла по умолчанию, в секундах, может быть переопределено во время загрузки, не допускаются значения меньше часа
X-Object-Meta-Sendmefile-Expire - время хранения загруженного файла, в секундах, не допускаются значения меньше часа
X-Object-Meta-Sendmefile-Delete-At - точное время когда загруженные файлы будут удалены, формат unixtime
X-Object-Meta-Sendmefile-Ignore-Filename (yes|no) - игнорировать изначальное имя загружаемого файла (полезно в сочетании с некоторыми типами ссылок)
X-Object-Meta-Sendmefile-Secret - пароль на загрузку файлов, формат sha1-хеш пароля
Для веб-интерфейса загрузки предусмотрена возможность задания пояснительного текста. Установка пояснительного текста осуществляется отправкой тела запроса, длина текста ограничена 4096 символами.
Пример запроса создания ссылки на загрузку:
$ curl -i -XPUT https://xxx.selcdn.ru/container/upload \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Type: x-storage/sendmefile" \
-H "X-Object-Meta-Sendmefile-Max-Size: 52428800" \
-H "X-Object-Meta-Sendmefile-Expire: 14400" \
-H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8" \
-d "Пояснительный текст для страницы загрузки"
Загрузка файла по ссылке осуществляется PUT-запросом на адрес ссылки. Дополнительно можно указывать следующие заголовки для запроса:
X-Filename - название для файла под которым он будет загружен (Хранилище может изменить название в зависимости от типа ссылки на загрузку)
X-Sendmefile-Session-Id - число, идентификатор сессии загрузки
X-Sendmefile-TZ-Offset - коррекция времени, полезно для некоторых типов ссылок. Формат: число в минутах (пример, +240) или строка вида "hhmm[+|-]HHMM", где HH - смещение часов, MM - смещение минут (пример, hhmm-0400).
При успешной загрузке возвращается код ответа 201 Created и дополнительный заголовок X-Uploaded-As содержащий название файла под которым он был сохранен.
Если был установлен пароль на загрузку, то в запросе нужно передать параметр _ssuk=password, где password заданный пароль (не sha1-хеш).
Пример загрузки файла по ссылке:
# получение локального смещения времени (не обязательно)
$ d=`date +%z`
$ offset="hhmm"${d:0:1}$(( ${d:0:3} * 60 + ${d:3} ))
# загрузка файла
$ curl https://xxx.selcdn.ru/container/upload?_ssuk=password -i -X PUT \
-H "X-Filename: my_file.txt" \
-H "X-Sendmefile-TZ-Offset: ${offset}" \
-T path_to_file/my_file.txt
Передача пароля через параметр запроса _ssuk требует указание его в исходном виде. Чтобы этого избежать предусмотрен второй способ загрузки с безопасной подписью. Для этого нужно при загружке файла указать заголовок X-Sendmefile-Secret-Sig со специально сформированной значением в формате "expires.hmac_hash", где:
expires - время, до которого подпись действительна (unix timestamp); рекомендуется указывать время действия на 5-15 минут
hmac_hash - hmac-sha1 хеш по ключу sha1-хеша пароля от данные вида "user-agent\nexpires", где user-agent - первые 300 символов значения заголовка User-Agent запроса на загрузка файла; expires - см. выше; \n - символ перевода строки.
Пример формирования подписи на языке python:
import hmac
from hashlib import sha1
import time
secret = "password"
user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0)"
expires = int(time.time()) + 60 * 5 # действителен в течение 5 минут
data = "{user_agent}\n{expires}".format(
user_agent=user_agent, expires=expires)
hash_secret = hmac.new(sha1(secret).heigest(), data, sha1)
# подпись, значение для заголовка X-Sendmefile-Secret-Sig
sig = "{expires}.{hash}".format(
expires=expires, hash=hash_secret.heigest()
)
Пример загрузки файла по запароленной ссылке с безопасной подписью:
$ curl https://xxx.selcdn.ru/container/upload?_ssuk=password -i -X PUT \
-H "X-Filename: my_file.txt" \
-H "X-Sendmefile-Secret-Sig: 1378910237.b795d3c13d91b4629a100d04c2b72ea81c12f233" \
-T path_to_file/my_file.txt
Для всех загруженных файлов устанавливается дополнительная информация в метаданные:
X-Object-Meta-Origin-Filename - изначальное название файла
X-Object-Meta-Uploaded-From-IP - ip-адрес с которого была произведена загрузка
X-Object-Meta-Sendmefile-Session-Id - идентификатор сессии загрузки
Поддерживается возможность удаления "своих" загруженных файлов, осуществляется отправкой DELETE запроса на файл с обязательным указание заголовка X-Sendmefile-Session-Id. Удаление происходит при соблюдении следующих условий: значение X-Sendmefile-Session-Id совпадает со значением метаданных X-Object-Meta-Sendmefile-Session-Id файла, запрос загрузки и удаления пришел с одного ip-адреса и прошло не более 10 минут с момента загрузки. При успешном удалении файла возвращается код ответа 204. Пример запроса на удаление:
$ curl https://xxx.selcdn.ru/container/my_file.txt -i -X DELETE \
-H "X-Sendmefile-Session-Id: 111222"
Специальные страницы
Настройки задаются на уровне контейнера и действует на все запросы внутрь контейнера. Поведение работает и для привязанных к контейнеру доменов.
Индексные страницы
При анонимном GET-запросе на имя контейнера или папки внутри него, будет отдан специальный файл указанный в метаданных контейнера.
Настройка осуществляется отправкой PUT-запроса(создание) или POST-запроса(изменение) на контейнер с указанием заголовка X-Container-Meta-Web-Index. В значении заголовка нужно указать файл внутри контейнера без указания имени самого контейнера. Можно использовать режим указания строгого пути к файлу или относительного поиска. Значение должно быть заквотированно (url encode).
Примеры:
Web-Index Запрос Отданный файл
/index.html
GET /container/
GET /container/dir1/
/container/index.html
index.html GET /container/ /container/index.html
GET /container/dir1/dir2/
/container/dir1/dir2/index.html
или (если файла нет)
/container/index.html
Пример:
# создаем индексный файл
$ echo "<html>custom_index_file</html>" > my_index.html
# закачиваем его в хранилище
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/my_index.html \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-T "./my_index.html"
> HTTP/1.1 100 Continue
> HTTP/1.1 201 Created
> etag: b302ffc3b75770453e96c1348e30eb93
> Last-Modified: Mon, 27 May 2013 14:42:04 GMT
# устанавливаем значение Web-Index для контейнера
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Web-Index: /my_index.html"
> HTTP/1.1 204 No Content
# при анонимном запросе получаем содержимое указанного файла
$ curl -i https://xxx.selcdn.ru/new_container/
> HTTP/1.1 200 OK
> last-modified: Mon, 27 May 2013 14:27:57 GMT
> etag: b302ffc3b75770453e96c1348e30eb93
> accept-ranges: bytes
> Content-Length: 31
> Content-Type: text/html
> access-control-request-method: HEAD, GET
>
> <html>custom_index_file</html>
Перенаправление при ошибке 404
При анонимном GET-запросе, если запрашиваемого файла нет в Хранилище, то будет отдано перенаправление (с кодом 307) на указанный в метаданных контейнера адрес.
Настройка осуществляется отправкой PUT или POST запроса на контейнер с указанием заголовка X-Container-Meta-Web-404-Redirect. В значении можно указывать файл внутри контейнера или внешнюю ссылку.
Примеры:
Web-404-Redirect Запрос Перенаправление на
/404.html
GET /container/nofile
GET /container/dir1/nofile
/container/404.html
404.html GET /container/nofile /container/404.html
GET /container/dir1/dir2/nofile
/container/dir1/dir2/404.html
или (если файла нет)
/container/dir1/404.html
или
/container/404.html
http://test.test
GET /container/nofile
GET /container/dir1/nofile
http://test.test
Для передачи информации о изначально запрашиваемом файле можно использовать специальные шаблонные параметры:
{container} - имя контейнера
{path} - путь к файлу относительно контейнера
{qs} - параметры запроса (без начального символа "?")
Пример:
# устанавливаем значение Web-404-Redirect для контейнера
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}"
> HTTP/1.1 204 No Content
# при анонимном запросе на не существующий объект получаем редирект на указанный файл
$ curl -i https://xxx.selcdn.ru/new_container/non_exist_object
> HTTP/1.1 307 Temporary Redirect
> Location: http://xxx.selcdn.ru/404.html?file=non_exist_object
Страница при ошибке 404
При анонимном GET-запросе заместо ошибки 404 будет отдано содержимое указанного файла.
Настройка осуществляется отправкой PUT или POST запроса на контейнер с указанием заголовка X-Container-Meta-Web-404-Page. В значении можно указывать путь к файл внутри контейнера, поддерживается указание как относительного пути так и абсолютного.
По умолчанию, при отдаче страницы ошибки код ответа будет 404. Можно явно указать код ответа используя следующий формат:
<path>?<code>
, где path - путь к файлу, code - код от
Хранилище полностью поддерживает OpenStack Swift API и дополнительно Amazon S3 API.
Аутентификация
Для выполнения аутентификации нужно отправить GET запрос на url https://auth.selcdn.ru/ и передать следующие обязательные заголовки X-Auth-User и X-Auth-Key.
Где:
X-Auth-User - ваш номер договора (логин в общую панель управления http://support.selectel.ru/)
X-Auth-Key - пароль для данной услуги (он отличается от пароля для общей панели управления)
Эту информация вы можете получить на странице Хранилище - Файлы - Настройка доступа.
При успешной аутентификации будет получен HTTP ответ 204 (No Content) с заголовками X-Storage-Url и X-Auth-Token содержащие данные необходимые для выполнения всех остальных операций с хранилищем:
X-Storage-Url - базовый адрес для выполнения операций с хранилищем
X-Auth-Token - идентификатор авторизации (действителен 24 часа с момента первой аутентификации)
X-Expire-Auth-Token - точное время действия идентификатора авторизации в секундах
В случае ошибки аутентификации будет получен HTTP ответ 403 (Forbidden).
Пример:
$ curl -i https://auth.selcdn.ru/ \
-H "X-Auth-User:user" \
-H "X-Auth-Key
assword"# вывод curl сокращен в целях удобочитаемости
> HTTP/1.1 204 No Content
> X-Expire-Auth-Token: 86029
> X-Storage-Url: https://xxx.selcdn.ru/
> X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12
Дополнительно поддерживается аутентификация по протоколу v2.0 (keystone api). Поддерживается только необходимый минимум этого протокола, поэтому некоторые расширенные возможности keystone могут не работать.
Пример аутентификации по v2.0 keystone:
$ curl -i -X POST https://auth.selcdn.ru/tokens \
-H 'Content-type: application/json' \
-d '{"auth": {"passwordCredentials": {"username": "user", "password": "password"}}}'
В качестве Tenant ID и Access Key следует указывать имя пользователя или дополнительного пользователя в Хранилище, в качестве Secret Key - пароль пользователя, Region - Common.
Операции с хранилищем
Во всех запросах к хранилищу должен передаваться заголовок X-Auth-Token, полученный при аутентификации, иначе будет получен отказ доступа. Исключение, скачивание файла из публичного контейнера.
Информация по хранилищу
HEAD запрос на адрес X-Storage-Url.
В заголовках ответа будет получена следующая информация:
X-Account-Bytes-Used - суммарный объём хранения данных в хранилище (в байтах)
X-Account-Container-Count - количество контейнеров
X-Account-Object-Count - суммарное количество хранимых объектов
X-Transfered-Bytes - скачено байт из хранилища (за всё время)
X-Received-Bytes - закачено байт в хранилище (за всё время)
Пример:
$ curl -I https://xxx.selcdn.ru/ \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
> X-Account-Object-Count: 5563
> X-Account-Bytes-Used: 6427888648
> X-Account-Container-Count: 27
> X-Received-Bytes: 110278989542
> X-Transfered-Bytes: 224961419192
Список контейнеров
GET запрос на адрес X-Storage-Url.
Дополнительные необязательные параметры запроса:
limit - число, ограничивает количество объектов в результате (по умолчанию 10000)
marker - строка, результат будет содержать объекты по значению больше указанного маркера (полезно использовать для постраничной навигации и при большом количестве контейнеров)
format - json или xml, результат будет выдан в указанном формате
За один запрос можно получить информацию максимум о 10000 контейнерах, если контейнеров больше, нужно использовать дополнительные запросы с параметром marker.
Примеры:
# получить листинг контейнеров с явным указание формата
$ curl -i https://xxx.selcdn.ru/\?format\=json \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> x-account-object-count: 5563
> x-account-bytes-used: 6427888648
> x-account-container-count: 27
> Content-Type: application/json; charset=utf-8
> Content-Length: 3033
> X-Received-Bytes: 110278989542
> X-Transfered-Bytes: 224978196408
>
> /* информация по контейнерам */
> [
> {
> /* место занимаемое содержимым контейнера */
> "bytes": 81292837,
> /* число объектов в контейнере */
> "count": 17,
> /* имя контейнера */
> "name": "container 1",
> /* всего закачанных в контейнер байт */
> "rx_bytes": 17936289,
> /* всего скачанных из контейнера байт */
> "tx_bytes": 11088956,
> /* тип контейнера */
> "type": "private"
> },
> {
> "bytes": 124355568,
> "count": 86,
> "name": "container 2",
> "rx_bytes": 296955064,
> "tx_bytes": 79205328,
> "type": "public"
> },
> ...
> ]
Создание контейнера
PUT запрос на адрес X-Storage-Url/container_name.
Имя контейнера должно быть меньше 256 символов и не содержать завершающего слеша '/' в конце.
HTTP ответы:
201 (Created) - при успешном создании
202 (Accepted) - если контейнер уже существует
К контейнеру можно привязать произвольные мета-данные через передачу заголовков с префиксом X-Container-Meta-.
Так же можно указать специальные заголовки, которые меняют функциональные свойства контейнера:
X-Container-Meta-Type - тип контейнера (public, private, gallery)
дополнительные заголовки кэшировани и CORS
Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: public" \
-H "X-Container-Meta-Some: some_specific_meta_data"
> HTTP/1.1 201 Created
Информация по контейнеру
HEAD запрос на адрес X-Storage-Url/container_name.
В заголовках ответа будет получена следующая информация:
X-Container-Object-Count - количество объектов в контейнере
X-Container-Bytes-Used - суммарный размер объектов в контейнере
X-Transfered-Bytes - скачено байт из контейнера
X-Received-Bytes - передано байт в контейнер
X-Container-Meta-Type - тип контейнера (public или private)
X-Container-Meta-Domains - привязанные домены к контейнеру
X-Container-Meta-* - заголовки с произвольной пользовательской информацией
Пример:
$ curl -I https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
> x-container-object-count: 0
> x-container-bytes-used: 0
> x-container-meta-type: public
> x-container-meta-some: some_specific_meta_data
> X-Container-Domains:
> X-Transfered-Bytes: 0
> X-Received-Bytes: 0
Изменение мета-данных контейнера
POST запрос на адрес X-Storage-Url/container_name и указать заголовки с префиксом X-Container-Meta- которые нужно установить или поменять.
HTTP ответы:
204 (No Content) - изменение выполнено
404 (Not Found) - указанный контейнер не существует
Пример:
# смена типа контейнера на личный и установка других метаданных
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: private" \
-H "X-Container-Meta-Some: any text"
> HTTP/1.1 204 No Content
Удаление контейнера
DELETE запрос на адрес X-Storage-Url/container_name.
Удаляемый контейнер должен быть пуст, иначе операция не будет выполнена.
HTTP ответы:
204 (No Content) - при успешном удалении
404 (Not Found) - указанный контейнер не существует
409 (Conflict) - ошибка удаления, контейнер не пустой
Пример:
$ curl -i -
ELETE https://xxx.selcdn.ru/new_container \-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
Галерея изображений
Контейнер можно преобразовать в галерею для удобного публичного представления в веб-браузере загруженных в нем фотографий и других изображений.
Создание галереи происходит путем установки типа контейнера gallery:
$ curl -i -XPUT https://xxx.selcdn.ru/gallery \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: gallery"
По умолчанию, галерея является публичной и доступ (только просмотр) к ней может получить любой. Но, дополнительно, можно установить пароль, по которому будет ограничен доступ. Для этого в запросе нужно передать заголовок X-Container-Meta-Gallery-Secret со значением sha1-хеша пароля. Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/gallery \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Type: gallery"
-H "X-Container-Meta-Gallery-Secret: 91dfd9ddb4198affc5c194cd8ce6d338fde470e2" # sha1-хеш пароля mypassword
Список файлов в контейнере
GET запрос на адрес X-Storage-Url/container_name.
Дополнительные необязательные параметры запроса:
limit - число, ограничивает количество объектов в результате (по умолчанию 10000)
marker - строка, результат будет содержать объекты по значению больше указанного маркера (полезно использовать для постраничной навигации и для большого количества файлов)
prefix - строка, вернуть объекты имена которых начинаются с указанного префикса
path - строка, вернуть объекты в указанной папке (виртуальные папки)
delimiter - символ, вернуть объекты до указанного разделителя в их имени
format - json или xml, результат будет выдан в указанном формате
За один запрос можно получить информацию максимум о 10000 файлах в контейнере, если в контейнере содержится больше файлов то нужно использовать дополнительные запросы с параметром marker.
Пример:
$ curl -i https://xxx.selcdn.ru/new_container/\?format\=json \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> x-container-meta-web-listings: on
> x-container-object-count: 4
> x-container-meta-access-control-request-method: HEAD, GET
> x-container-meta-web-listings-css: /my_style.css
> x-container-bytes-used: 1092
> x-container-meta-web-404-redirect: /trex_404.html
> x-container-meta-type: public
> x-container-meta-web-index: /my_index.html
> Content-Type: application/json; charset=utf-8
> Content-Length: 724
>
> /* информация о файлах */
> [
> {
> /* размер файла: */
> "bytes": 31,
> /* тип файла: */
> "content_type": "text/html",
> /* сколько раз данный файл был скачан: */
> "downloaded": 4,
> /* md5 хеш: */
> "hash": "b302ffc3b75770453e96c1348e30eb93",
> /* время загрузки файла: */
> "last_modified": "2013-05-27T14:42:04.669760",
> /* имя файла: */
> "name": "my_index.html"
> },
> {
> "bytes": 1024,
> "content_type": "application/octet-stream",
> "downloaded": 0,
> "hash": "0f343b0931126a20f133d67c2b018a3b",
> "last_modified": "2013-05-27T13:16:49.007590",
> "name": "new_object"
> },
> ...
> ]
Скачивание файла
GET запрос на адрес X-Storage-Url/container_name/path_to_file.
Указание заголовка X-Auth-Token необходимо только если файл находиться внутри личного (приватного) контейнера.
Путь к файлу может содержать символ '/' как виртуальную папку.
Хранилище поддерживает условные запросы в соответствии с RFC 2616, вы можете указывать следующие заголовки:
If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since
Пример:
$ curl -O https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
Счётчик скачиваний файла
Получить информацию о количестве скачиваний для файла можно выполнив авторизованный HEAD или GET запрос на файл. Информация будет получена в виде дополнительного заголовка X-Object-Downloads в ответе.
Счётчик скачиваний может обновляться с задержкой до нескольких минут. При операциях изменения объекта (удаление, перемещение, загрузка заново) значение счётчика обнуляется.
Пример:
$ curl -I https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 200 OK
> X-Object-Downloads: 17
> last-modified: Mon, 27 May 2013 12:27:11 GMT
> etag: 0f343b0931126a20f133d67c2b018a3b
> Content-Length: 1024
> Content-Type: application/octet-stream
Загрузка файла
PUT запрос X-Storage-Url/container_name/path_to_file.
Файл может быть загружен только в контейнер, который должен существовать к моменту загрузки файла. Полное имя файла (включая виртуальные папки) не должно превышать 1024 байт после URL квотирования. Размер одного загружаемого файла не должен превышать 5 ГБ.
Загрузка может быть осуществлена целиком либо http-чанками. При загрузке целиком в заголовках должен быть указан размер файла в заголовке Content-Lenght. При загрузке чанками должен быть указан соответствующий заголовок Transfer-Encoding: chunked.
К файлу может быть прикреплены произвольные мета-данные через указание заголовков с префиксом X-Object-Meta-. Суммарный размер заголовков не должен превышать 4 КБ.
При загрузке файла можно указать специальный заголовок ETag содержащий контрольную сумму MD5. После загрузки файла будет проведена проверка сохранённых данных по контрольным суммам, это позволяет убедиться что данные сохранены верно.
Так же можно указать заголовок Content-Type для задания типа файла. Заголовок Content-Disposition влияет на то как браузер будет обрабатывать получение файла из Хранилища.
Хранилище поддерживает автоматически удаляемые файлы. Для создание таких файлов нужно передать один из следующих заголовков:
X-Delete-At - время когда нужно удалить файл, указывается целое число в unix timestamp
X-Delete-After - через какое время удалить файл, указывается в секундах
При успешной загрузке файла будет получен HTTP ответ 201 (Created) с заголовками Content-Lenght, Content-Type и Etag. В случае если при загрузке был указан заголовок ETag и проверка загруженных данных будет неудачна, то в ответ будет получен HTTP статус 422 (Unprocessable Entity).
Пример:
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Delete-After: 25200" \
-T "./example.gz"
> HTTP/1.1 100 Continue
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> Last-Modified: Mon, 27 May 2013 12:24:37 GMT
Распаковка архивов
Хранилище поддерживает возможность автоматической распаковки загружаемого архива. Поддерживаются следующие форматы архивов: tar, tar.gz, tar.bz2.
Для распаковки нужно при загрузке архива указать параметр запроса extract-archive=format, где за место format указать формат архива.
Пример загрузки архива с его распаковкой в хранилище:
# файлы будут распакованы в контейнер new_container
$ curl -i -X PUT 'https://xxx.selcdn.ru/new_container/?extract-archive=tar.bz2' \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-T "photos.tar.bz2"
В качестве пути для распаковки можно указывать контейнер, папку в контейнере или корень аккаунта. В последнем случае для папок первого уровня из архива будут созданы соответствующие контейнеры в хранилище.
После выполнения операции будет отдан ответ 200 с отчетом о результате распаковки. Поддерживается получение отчета в структурированном формате, для этого нужно при запросе указать заголовок Accept с одним из значений: text/plain, application/json, application/xml или text/xml.
Пример отчета в json формате:
{"Response Status": "201 Created",
"Response Body": "", "Errors": [], "Number Files Created": 1237}
Из отчета можно получить информацию о количестве распакованных файлов и список возникших ошибок при распаковки.
Установка мета-данных файла
POST запрос на адрес X-Storage-Url/container_name/path_to_file и указать заголовки с префиксом X-Object-Meta- которые нужно установить или поменять.
Внимание: установка мета-данных стирает все установленные ранее мета-данные для указанного файла и заменяет их на указанные в запросе.
HTTP ответы:
204 (No Content) - изменение выполнено
404 (Not Found) - указанный контейнер не существует
Пример:
$ curl -i -XPOST https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Object-Meta-Another: another"
> HTTP/1.1 202 Accepted
Копирование файлов в контейнерах
Можно копировать и перемещать файлы в пределах хранилища без повторной их загрузки. Операцию можно осуществить с помощью PUT или COPY запроса.
PUT запрос на X-Storage-Url/container_name/new_path_to_file с обязательным заголовком X-Copy-From содержащим путь к исходному файлу относительно корня хранилища (например, /container2/file3) и заголовком Content-Lenght равным нулю (0).
COPY запрос на X-Storage-Url/container_name/orig_path_to_file и заголовком Destination содержащим путь куда нужно копировать файл.
Для обоих запросов контейнер в который производиться копирование должен существовать.
При копировании также копируется и мета-данные о файле. Если в запросе указать заголовки с префиксом X-Object-Meta-, то для скопированного объекта будет установлены или перезаписаны (если они были в исходном файле) указанные мета-данные.
Пример:
# первый способ
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/first_copy \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Length: 0" \
-H "X-Copy-From: /new_container/new_object"
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> X-Copied-From: new_container/new_object
> X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
> Last-Modified: Tue, 28 May 2013 06:27:11 GMT
# второй способ
$ curl -i -XCOPY https://xxx.selcdn.ru/new_container/new_object \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Destination: /new_container/second_copy"
> HTTP/1.1 201 Created
> etag: 0f343b0931126a20f133d67c2b018a3b
> X-Copied-From: new_container/new_object
> X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
> Last-Modified: Tue, 28 May 2013 06:30:51 GMT
Удаление файла
DELETE запрос на адрес X-Storage-Url/container_name/path_to_file.
HTTP ответы:
204 (No Content) - при успешном удалении
404 (Not Found) - если файла не существует
Пример:
$ curl -i -
ELETE https://xxx.selcdn.ru/new_container/new_object \-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"
> HTTP/1.1 204 No Content
Управление заголовками для файлов
Хранилище позволяет указывать специальные заголовки которые влияют на процесс получения файла из Хранилища. В частности, позволяют управлять кэшированием данных на стороне клиента и промежуточных прокси серверах, а так же задавать заголовки для обработки кросс-доменных запросов (CORS).
Поддерживаемые заголовки:
Cache-Control
Expires
Origin
Access-Control-Allow-Origin
Access-Control-Max-Age
Access-Control-Allow-Methods
Access-Control-Allow-Credentials
Access-Control-Expose-Headers
Access-Control-Request-Headers
Access-Control-Request-Method
Content-Disposition (только для конечного файла)
Strict-Transport-Security (только на уровне контейнера)
Вы можете установить значения по умолчанию для поддерживаемых заголовков на уровне контейнера. Для этого для контейнера нужно установить соответствующие мета-данные X-Container-Meta-<header>, где <header> заменить на нужный заголовок. После задания этих значений для всех отдаваемых данных (методом GET) из контейнера будет устанавливаться соответствующие заголовки.
Так же вы можете установить или переопределить значения по умолчанию для конктерного файла в хранилище, заданием соответствующих мета-данных.
Пример:
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Access-Control-Request-Method: HEAD, GET" \
-H "X-Container-Meta-Cache-Control: public" \
-H "X-Container-Meta-Strict-Transport-Security: max-age=31536000; includeSubDomains"
> HTTP/1.1 204 No Content
Ссылки на файл (symlink)
Ссылки позволяют предоставлять доступ к файлам в хранилище используя альтернативное имя. В частности, это даёт возможность открывать публичный доступ к файлам из личного контейнера, а так же доступ между пользователями на одном аккаунте.
Вы можете создать специальный объект-ссылку которая будет будет указывать на другой объект в хранилище (только на файл) и настроить ряд дополнительных параметров (ограничить время действия, задать пароль).
Создание ссылки: PUT запрос на адрес X-Storage-Url/container_name/link_name с указанием ряда заголовков.
Заголовки:
Content-Type - определяет тип ссылки, возможные значения:
x-storage/symlink - обычная ссылка
x-storage/onetime-symlink - одноразовая ссылка
x-storage/symlink+secure - обычная запароленная ссылка
x-storage/onetime-symlink+secure - одноразовая запароленная ссылка
X-Object-Meta-Location - цель ссылки, относительный заквотированный путь к объекту в хранилище (пример: /container/path/to%20file).
Content-Length: 0 - тело запроса обязательно должно быть пустым
X-Object-Meta-Delete-At - время до которого ссылка будет действительна (unix timestamp), необязательно заголовок.
X-Object-Meta-Link-Key - хеш ключа доступа к запароленной ссылке. Вычисление хеша: sha1(password + X-Object-Meta-Location).
Content-Disposition - перекрывает соответствующий заголовок объекта, на который указывает ссылка.
При обращение к объекту-ссылке (методом GET) в ответ будет получен объект на который она указывает. HEAD-запрос возвращает информацию о ссылке.
Для доступа к запароленной ссылке нужно в GET запросе указать параметр _sslk со значением пароля.
Объект-ссылка (но не цель ссылки) автоматически удаляется при истечение срока действия или при первом успешном скачивании для одноразовых ссылок.
Пример:
$ curl -i -XPUT http://xxx.selcdn.ru/new_container/new_link \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Type: x-storage/symlink" \
-H "X-Object-Meta-Location: /new_container/new_object" \
-H "X-Object-Meta-Link-Key: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c"\
-H "Content-Length: 0"
> HTTP/1.1 201 Created
> etag: d41d8cd98f00b204e9800998ecf8427e
> Last-Modified: Mon, 27 May 2013 13:34:34 GMT
Генерация ссылок для скачивания файлов
С помощью функции генерации ссылок можно создавать специальные ссылки для скачивания файлов, в том числе и из личных контейнеров. Срок действия ссылок ограничен.
В отличии от symlink, ссылки создаются без выполнения запросов к API. После создания ссылки невозможно отменить или удалить; они доступны в течении всего срока действия.
Чтобы генерировать ссылки, нужно предварительно установить секретный ключ. Для этого нужно задать метаданные X-Account-Meta-Temp-URL-Key для аккаунта. Пример:
$ curl -i -XPOST http://xxx.selcdn.ru/ \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Account-Meta-Temp-URL-Key: secret_word"
> HTTP/1.1 204 No Content
В примере задается секретный ключ secret_word. Его нужно запомнить (в дальнейшем все ссылки будут генерироваться с его помощью) и защитить от постороннего доступа (доступ к файлам может получить любой пользователь, знающий секретный ключ).
Алгоритм генерации ссылки для языка python:
import hmac
from hashlib import sha1
from time import time
# данные для генерации ссылки
method = "GET" # метод доступа (всегда GET)
expires = int(time()) + 60 # ссылка действительная 60 секунд
path = "/container/dir/file" # путь к файлу в хранилище, всегда с указанием контейнера
link_secret_key = "secret_word" # секретный ключ
# генерация ключа доступа
hmac_body = '%s\n%s\n%s' % (method, expires, path)
sig = hmac.new(link_secret_key, hmac_body, sha1).he
igest() # ключ доступаПолученный в результате ключ нужно будет указать в ссылке. Ссылка может выглядеть, например, так:
http://xxx.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
где xxx.selcdn.ru базовый домен, значение temp_url_sig - ключ доступа, temp_url_expires - время до которого ссылка действительна (unixtime).
Вместо базового домена можно указывать привязанный в контейнеру домен. В таком случае указывать имя контейнера в ссылке не нужно, например:
http://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
Дополнительно поддерживается управление заголовком Content-Disposition для отдаваемых по ссылке данных. Для этого нужно добавить параметр запроса filename с нужным значением. Пример:
http://xxx.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc
Секретный ключ при необходимости можно изменить, но в таком случае все сгенерированные ранее ссылки перестанут действовать.
Ссылки на загрузку файлов (sendmefile)
Ссылки на загрузку файлов - это специальная возможность позволяющая настроить загрузку файлов в Хранилище без авторизации. Она полезна когда вы хотите попросить кого-нибудь передать вам файлы, или для организации общего хранилища и даже для настройки резервного копирования. Ссылка на загрузку может быть использована для открытия в браузере и для работы с различными программами и утилитами, например, curl.
Сама ссылка создается как обычный файл в Хранилище для которого задаются специальные метаданные.
Поддерживается несколько типов ссылок, которые настраиваются указанием заголовка Content-Type:
x-storage/sendmefile - обычная ссылка на загрузку файлов
x-storage/sendmefile+inplace - загрузка только одного файла по указанному имени (имя ссылки является именем под которым будет сохранен загружаемый файл)
x-storage/sendmefile+timepostfix - загрузка файлов с добавлением времени загрузки в имема файлов (с учетом расширения файлов)
x-storage/sendmefile+autopostfix - загрузка файлов с добавлением уникального идентификатора в имема файлов (с учетом расширения файлов)
x-storage/sendmefile+folderday - загрузка файлов в папку с именем состоящим из даты загрузки (год и день)
x-storage/sendmefile+folderhour - загрузка файлов в папку с именем состоящим из даты и часа загрузки
x-storage/sendmefile+folderuniq - загрузка файлов в папку с уникальным именем
Ссылки поддерживают ряд необязательных настроек:
X-Object-Meta-Sendmefile-Disable-Web (yes|no) - отключение веб-интерфейса загрузки файлов (веб-интерфейс включен по умолчанию)
X-Object-Meta-Sendmefile-Max-Size - максимальный размер загружаемого файла в байтах, не допускаются значения больше 5 Гб
X-Object-Meta-Sendmefile-Allow-Overwrite (yes|no) - разрешить перезапись файла если он уже есть в Хранилище (по умолчанию перезапись запрещена)
X-Object-Meta-Sendmefile-Default-Expire - время хранения загруженного файла по умолчанию, в секундах, может быть переопределено во время загрузки, не допускаются значения меньше часа
X-Object-Meta-Sendmefile-Expire - время хранения загруженного файла, в секундах, не допускаются значения меньше часа
X-Object-Meta-Sendmefile-Delete-At - точное время когда загруженные файлы будут удалены, формат unixtime
X-Object-Meta-Sendmefile-Ignore-Filename (yes|no) - игнорировать изначальное имя загружаемого файла (полезно в сочетании с некоторыми типами ссылок)
X-Object-Meta-Sendmefile-Secret - пароль на загрузку файлов, формат sha1-хеш пароля
Для веб-интерфейса загрузки предусмотрена возможность задания пояснительного текста. Установка пояснительного текста осуществляется отправкой тела запроса, длина текста ограничена 4096 символами.
Пример запроса создания ссылки на загрузку:
$ curl -i -XPUT https://xxx.selcdn.ru/container/upload \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "Content-Type: x-storage/sendmefile" \
-H "X-Object-Meta-Sendmefile-Max-Size: 52428800" \
-H "X-Object-Meta-Sendmefile-Expire: 14400" \
-H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8" \
-d "Пояснительный текст для страницы загрузки"
Загрузка файла по ссылке осуществляется PUT-запросом на адрес ссылки. Дополнительно можно указывать следующие заголовки для запроса:
X-Filename - название для файла под которым он будет загружен (Хранилище может изменить название в зависимости от типа ссылки на загрузку)
X-Sendmefile-Session-Id - число, идентификатор сессии загрузки
X-Sendmefile-TZ-Offset - коррекция времени, полезно для некоторых типов ссылок. Формат: число в минутах (пример, +240) или строка вида "hhmm[+|-]HHMM", где HH - смещение часов, MM - смещение минут (пример, hhmm-0400).
При успешной загрузке возвращается код ответа 201 Created и дополнительный заголовок X-Uploaded-As содержащий название файла под которым он был сохранен.
Если был установлен пароль на загрузку, то в запросе нужно передать параметр _ssuk=password, где password заданный пароль (не sha1-хеш).
Пример загрузки файла по ссылке:
# получение локального смещения времени (не обязательно)
$ d=`date +%z`
$ offset="hhmm"${d:0:1}$(( ${d:0:3} * 60 + ${d:3} ))
# загрузка файла
$ curl https://xxx.selcdn.ru/container/upload?_ssuk=password -i -X PUT \
-H "X-Filename: my_file.txt" \
-H "X-Sendmefile-TZ-Offset: ${offset}" \
-T path_to_file/my_file.txt
Передача пароля через параметр запроса _ssuk требует указание его в исходном виде. Чтобы этого избежать предусмотрен второй способ загрузки с безопасной подписью. Для этого нужно при загружке файла указать заголовок X-Sendmefile-Secret-Sig со специально сформированной значением в формате "expires.hmac_hash", где:
expires - время, до которого подпись действительна (unix timestamp); рекомендуется указывать время действия на 5-15 минут
hmac_hash - hmac-sha1 хеш по ключу sha1-хеша пароля от данные вида "user-agent\nexpires", где user-agent - первые 300 символов значения заголовка User-Agent запроса на загрузка файла; expires - см. выше; \n - символ перевода строки.
Пример формирования подписи на языке python:
import hmac
from hashlib import sha1
import time
secret = "password"
user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:23.0)"
expires = int(time.time()) + 60 * 5 # действителен в течение 5 минут
data = "{user_agent}\n{expires}".format(
user_agent=user_agent, expires=expires)
hash_secret = hmac.new(sha1(secret).he
igest(), data, sha1)# подпись, значение для заголовка X-Sendmefile-Secret-Sig
sig = "{expires}.{hash}".format(
expires=expires, hash=hash_secret.he
igest())
Пример загрузки файла по запароленной ссылке с безопасной подписью:
$ curl https://xxx.selcdn.ru/container/upload?_ssuk=password -i -X PUT \
-H "X-Filename: my_file.txt" \
-H "X-Sendmefile-Secret-Sig: 1378910237.b795d3c13d91b4629a100d04c2b72ea81c12f233" \
-T path_to_file/my_file.txt
Для всех загруженных файлов устанавливается дополнительная информация в метаданные:
X-Object-Meta-Origin-Filename - изначальное название файла
X-Object-Meta-Uploaded-From-IP - ip-адрес с которого была произведена загрузка
X-Object-Meta-Sendmefile-Session-Id - идентификатор сессии загрузки
Поддерживается возможность удаления "своих" загруженных файлов, осуществляется отправкой DELETE запроса на файл с обязательным указание заголовка X-Sendmefile-Session-Id. Удаление происходит при соблюдении следующих условий: значение X-Sendmefile-Session-Id совпадает со значением метаданных X-Object-Meta-Sendmefile-Session-Id файла, запрос загрузки и удаления пришел с одного ip-адреса и прошло не более 10 минут с момента загрузки. При успешном удалении файла возвращается код ответа 204. Пример запроса на удаление:
$ curl https://xxx.selcdn.ru/container/my_file.txt -i -X DELETE \
-H "X-Sendmefile-Session-Id: 111222"
Специальные страницы
Настройки задаются на уровне контейнера и действует на все запросы внутрь контейнера. Поведение работает и для привязанных к контейнеру доменов.
Индексные страницы
При анонимном GET-запросе на имя контейнера или папки внутри него, будет отдан специальный файл указанный в метаданных контейнера.
Настройка осуществляется отправкой PUT-запроса(создание) или POST-запроса(изменение) на контейнер с указанием заголовка X-Container-Meta-Web-Index. В значении заголовка нужно указать файл внутри контейнера без указания имени самого контейнера. Можно использовать режим указания строгого пути к файлу или относительного поиска. Значение должно быть заквотированно (url encode).
Примеры:
Web-Index Запрос Отданный файл
/index.html
GET /container/
GET /container/dir1/
/container/index.html
index.html GET /container/ /container/index.html
GET /container/dir1/dir2/
/container/dir1/dir2/index.html
или (если файла нет)
/container/index.html
Пример:
# создаем индексный файл
$ echo "<html>custom_index_file</html>" > my_index.html
# закачиваем его в хранилище
$ curl -i -XPUT https://xxx.selcdn.ru/new_container/my_index.html \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-T "./my_index.html"
> HTTP/1.1 100 Continue
> HTTP/1.1 201 Created
> etag: b302ffc3b75770453e96c1348e30eb93
> Last-Modified: Mon, 27 May 2013 14:42:04 GMT
# устанавливаем значение Web-Index для контейнера
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Web-Index: /my_index.html"
> HTTP/1.1 204 No Content
# при анонимном запросе получаем содержимое указанного файла
$ curl -i https://xxx.selcdn.ru/new_container/
> HTTP/1.1 200 OK
> last-modified: Mon, 27 May 2013 14:27:57 GMT
> etag: b302ffc3b75770453e96c1348e30eb93
> accept-ranges: bytes
> Content-Length: 31
> Content-Type: text/html
> access-control-request-method: HEAD, GET
>
> <html>custom_index_file</html>
Перенаправление при ошибке 404
При анонимном GET-запросе, если запрашиваемого файла нет в Хранилище, то будет отдано перенаправление (с кодом 307) на указанный в метаданных контейнера адрес.
Настройка осуществляется отправкой PUT или POST запроса на контейнер с указанием заголовка X-Container-Meta-Web-404-Redirect. В значении можно указывать файл внутри контейнера или внешнюю ссылку.
Примеры:
Web-404-Redirect Запрос Перенаправление на
/404.html
GET /container/nofile
GET /container/dir1/nofile
/container/404.html
404.html GET /container/nofile /container/404.html
GET /container/dir1/dir2/nofile
/container/dir1/dir2/404.html
или (если файла нет)
/container/dir1/404.html
или
/container/404.html
http://test.test
GET /container/nofile
GET /container/dir1/nofile
http://test.test
Для передачи информации о изначально запрашиваемом файле можно использовать специальные шаблонные параметры:
{container} - имя контейнера
{path} - путь к файлу относительно контейнера
{qs} - параметры запроса (без начального символа "?")
Пример:
# устанавливаем значение Web-404-Redirect для контейнера
$ curl -i -XPOST https://xxx.selcdn.ru/new_container \
-H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \
-H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}"
> HTTP/1.1 204 No Content
# при анонимном запросе на не существующий объект получаем редирект на указанный файл
$ curl -i https://xxx.selcdn.ru/new_container/non_exist_object
> HTTP/1.1 307 Temporary Redirect
> Location: http://xxx.selcdn.ru/404.html?file=non_exist_object
Страница при ошибке 404
При анонимном GET-запросе заместо ошибки 404 будет отдано содержимое указанного файла.
Настройка осуществляется отправкой PUT или POST запроса на контейнер с указанием заголовка X-Container-Meta-Web-404-Page. В значении можно указывать путь к файл внутри контейнера, поддерживается указание как относительного пути так и абсолютного.
По умолчанию, при отдаче страницы ошибки код ответа будет 404. Можно явно указать код ответа используя следующий формат:
<path>?<code>
, где path - путь к файлу, code - код от
