База знаний

Список статей
Работа с API Облачного хранилища
Наверх

Работа с API Облачного хранилища

Облачное хранилище предоставляет разработчикам возможность интеграции с собственными приложениями и сайтами.  Взаимодействие с хранилищем организовано на базе REST API.

API предназначен для приложений, которые работают с размещёнными в хранилище пользовательскими файлами или отправляют в хранилище собственные данные. Взаимодействие с API Swift осуществляется с помощью стандартных HTTP-запросов. В документации описаны все доступные на текущий момент вызовы API, форматы запросов и ответов. На текущий момент с помощью API можно выполнять следующие операции:

  • получать информацию об учётной записи, контейнерах и папках;

  • создавать и удалять контейнеры;

  • загружать файлы в хранилище и скачивать их;

  • копировать, перемещать и удалять файлы;

  • устанавливать срок хранения для файлов;

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

  • работать с версиями файлов;

  • создавать пользователей и задавать для них настройки доступа к хранилищу.

Формат URL

Хост для всех запросов к API — https://api.selcdn.ru.

После авторизации доступ к хранилищу осуществляется по URL вида: https://api.selcdn.ru/v1/SEL_*****,  где ***** — номер учётной записи пользователя. В URL также указывается версия API (v1). 

https://api.selcdn.ru/v1/SEL_*****/container_name обычно используется для работы авторизованного клиента. Например, при работе с приватными контейнерами или при удалении/добавлении объектов, а также при работе с метаданными. Это формат url openstack object api https://developer.openstack.org/api-ref/object-store/.

Домен ****.selcdn.ru - это персональный номерной домен пользователя, который можно узнать командой в заголовке X-Storage-Url:

curl -i -XGET "https://auth.selcdn.ru/" -H "X-Auth-User: *****" -H "X-Auth-Key: *****"

Этот домен обычно используют для раздачи статичного контента из публичных контейнеров. На этот домен делается CNAME при использовании своих доменов, которые привязывают к контейнеру, и данные, которые раздаются  через этот домен - кэшируются, что ускоряет отдачу контента.

Примечание: оба варианта будут работать, но api.selcdn.ru не будет кэшироваться.

Доступ к API

Для успешного выполнения запросов к API необходимо:

  • Быть зарегистрированным пользователем Selectel

  • Иметь достаточную сумму на балансе хранилища

  • Иметь логин и пароль для доступа к хранилищу

  • Получить уникальный ключ доступа (токен), который будет передаваться во всех запросах


Авторизация и получение токена

В этом разделе описаны способы авторизации и получения токена для работы с API. Регион -  ru-1, для программного обеспечения, которое требует указания региона (прим. --storage-openstack-region).

При использовании всех трёх способов обратите внимание на следующие моменты:

  • Срок действия токена составляет 24 часа

  • По прошествии 24 часов с момента последнего получения токена API будет возвращать ответы с кодом 401, в этом случае токен придётся получать заново

  • Если запросить токен через 12 часов с момента последней авторизации, то он будет обновлен, а полученный ранее токен станет недействительным

Авторизация по протоколу v1

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

curl -i -XGET https://api.selcdn.ru/auth/v1.0 -H "X-Auth-User: *****" -H "X-Auth-Key: $password"

При удачном выполнении запроса будет возвращён ответ с кодом 204 (No Content).

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

HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Storage-Token: $token
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: *****
X-Auth-Token: $token
X-Storage-Url: https://api.selcdn.ru/v1/SEL_*****

Параметры запроса

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/auth/v1.0

  • X-Auth-User — номер учётной записи

  • X-Auth-Key — пароль для доступа к хранилищу

Возвращает ключ авторизации (токен) для работы с хранилищем по API, который нужно будет передавать во всех последующих запросах

Внимание! Пароль для доступа к хранилищу указан на этой странице.

Параметры ответа

Параметр

Значение

X-Expire-Auth-Token

срок действия ключа авторизации (в секундах)

X-Storage-URL

URL для доступа к хранилищу

X-Auth-Token

ключ авторизации

X-Storage-Token

ключ авторизации (совпадает с предыдущим параметром)

Авторизация по протоколу v2

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

curl -i -XPOST https://api.selcdn.ru/v2.0/tokens -H 'Content-type: application/json' \
-d '{"auth": {"passwordCredentials": {"username": "*****", "password": "pA$sW0rD"}}}'

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

HTTP/1.1 200 OK
Content-Length: 423
Content-Type: application/json
{"access":{"token":{"id":"49a049462d6943d55b2ccc85abd5fdae","expires":"2016-05-20T13:12:45\n","tenant":{"id":"00000","name":"00000"}},"user":{"id":"00000","name":"00000","roles":[]},"serviceCatalog":[{"endpoints":[{"region":"common","adminURL":"https://api.selcdn.ru/v1/SEL_00000","internalURL":"https://api.selcdn.ru/v1/SEL_0000","publicURL":"https://api.selcdn.ru/v1/SEL_00000"}],"type":"object-store","name":"swift"}]}}

Авторизация по протоколу v3

curl -i -XGET https://api.selcdn.ru/v3/auth/tokens -XPOST -d '{"auth": { "identity": { "methods": ["password"], "password": { "user": { "id": "*****", "password": "pas$sW0rD"}}}}}'
HTTP/1.1 200 OK
Content-Length: 807
Content-Type: application/json
X-Subject-Token: $token
{"token":{"expires_at":"2016-05-21T09:27:53.8459900Z","issued_at":"2016-05-20T15:56:36.8459900Z","methods":["password"],"project":{"domain":{}},"Catalog":[{"endpoints":[{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_*****","region":"RegionOne","interface":"public"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_*****","region":"RegionOne","interface":"admin"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_*****","region":"RegionOne","interface":"internal"}],"type":"object-store","name":"swift","id":""}],"user":{"id":"614ed749fba45aa218d1ba68c7c83411","name":"*****","domain":{"id":"default","name":"Default","links":{}}},"audit_ids":[""]}}

Авторизация по временным токенам

Пользователям, не имеющим собственной учётной записи, можно предоставлять доступ к хранилищу по временным токенам. Срок действия таких токенов ограничен; с их помощью можно получить доступ только к определённым контейнерам, но не к аккаунту в целом.  

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/auth/v1.0

  • X-Auth-Token — токен авторизации основного пользователя

  • X-Container — контейнер, для доступа к которому выдаётся временный токен

  • X-Expire-After —   срок действия временного токена (в секундах)

Возвращает временный токен для доступа к хранилищу

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

curl -i -XGET https://api.selcdn.ru/v1/temptokens -H "X-Auth-Token: $token" -H "X-Container: container" -H "X-Expire-After: 3600"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Auth-Token: abdb173e328cc61e220300bcc3bbd7e
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 3600
X-Storage-Token: $token
X-Storage-Url: https://api.selcdn.ru/v1/SEL_*****

Временный токен передаётся в заголовках X-Auth-Token и X-Storage-Token.

Операции с аккаунтом

Получение информации об аккаунте

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****  -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: 00000
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3

Параметры ответа

Параметр

Значение

X-Account-Bytes-Used

суммарный объём хранимых данных, байт

X-Account-Container-Count

количество контейнеров

X-Account-Object-Count

общее количество хранимых объектов

Получение информации о хранилище

Тип запроса: HEAD

Параметры запроса

Параметр

Значение

X-Auth-Token

ключ авторизации

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

curl -i -XGET https://*****.selcdn.ru/ -H "X-Auth-Token: $token"

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

HTTP/1.1 204 No Content
Date: Tue, 28 Oct 2014 09:34:31 GMT
Server: Selectel_Storage/1.0
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: *****
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Received-Bytes: 345102605
X-Transfered-Bytes: 54907061
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Account-Object-Count, X-Timestamp, 
X-Account-Meta-Temp-Url-Key, X-Account-Bytes-Used, X-Account-Container-Count, X-Received-Bytes, X-Transfered-Bytes
Expires: 0
Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate

Параметры ответа

Параметр

Значение

X-Account-Bytes-Used

суммарный объём хранимых данных, байт

X-Account-Container-Count

количество контейнеров

X-Account-Object-Count

общее количество хранимых объектов

X-Transferred-Bytes

общий объём скачанной из хранилища информации, байт

X-Received-Bytes

общий объём загруженной в хранилище информации, байт

Операции с контейнерами

Получение списка контейнеров

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/SEL_*****

  • X-Auth-Token — токен авторизации

Возвращает список контейнеров, доступных в хранилище на текущий момент

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

curl https://api.selcdn.ru/v1/SEL_*****  -H "X-Auth-Token: $token"

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

container1
container2
container3
сontainer4

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

curl -i -XGET https://*****.selcdn.ru/?format=json  -X GET -H "X-Auth-Token: $token"

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

HTTP/1.1 200 OK

Server: Selectel_Storage/1.0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: ******
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
Content-Length: 300
X-Received-Bytes: 345102605
X-Transfered-Bytes: 54907061
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Account-Object-Count, X-Timestamp, 
X-Account-Meta-Temp-Url-Key, X-Account-Bytes-Used, X-Account-Container-Count, X-Received-Bytes, X-Transfered-Bytes
Expires: 0
Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate
[{"count": 1, "name": "test2", "rx_bytes": 363, "tx_bytes": 1006, "type": "public", "bytes": 363}, 
{"count": 1, "name": "upload", "rx_bytes": 0, "tx_bytes": 0, "type": "private", "bytes": 363}, 
{"count": 4, "name": "yellow", "rx_bytes": 484666, "tx_bytes": 264846, "type": "public", "bytes": 483748}]

Параметры ответа

Параметр

Значение

X-Account-Container-Count

общее количество контейнеров в хранилище

X-Account-Object-Count

общее количество хранимых в контейнерах объектов

X-Transferred-Bytes

общий объём скачанной из хранилища информации, байт

X-Received-Bytes

общий объём загруженной в хранилище информации, байт

C помощью одного запроса можно получить информацию о 10 000 контейнерах. Если контейнеров больше, то требуется использовать дополнительные запросы с параметром marker.

Создание нового контейнера

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Type — тип контейнера: публичный (public) или приватный (private)

  • X-Container-Meta-Some — метаданные контейнера

Создаёт контейнер с указанными в запросе параметрами

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

curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Type: public" -H "X-Container-Meta-Some: my test container"

В случае удачного выполнения запроса будет возвращён ответ с кодом 201.

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

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 0
Content-Type: text/html

Получение информации о контейнере

Параметры запроса

Тип запроса

URI

Заголовки

Описание

HEAD

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

Возвращает информацию об указанном контейнере

Параметры ответа

Заголовок

Значение

X-Container-Object-Count

количество объектов в контейнере

X-Container-Bytes-Used

общий объём всех хранимых объектов в байтах

X-Container-Meta-Type

тип контейнера (публичный или приватный)

X-Container-Meta-Some

метаданные контейнера

X-Container-Domains

привязанные к контейнеру домены

X-Transfered-Bytes

общий объём скачанной из контейнера информации, байт

X-Received-Bytes

общий объём загруженной в контейнер информации, байт

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/t-rex -H "X-Auth-Token: $token"

При удачном выполнении вопроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Length,Date,X-Container-Domains,X-Backend-Delete-Timestamp,X-Timestamp,X-Container-Meta-Type,X-Backend-Status-Changed-At,X-Backend-Storage-Policy-Index,X-Container-Object-Count,X-Backend-Put-Timestamp,X-Container-Bytes-Used,Content-Type,X-Backend-Timestamp,X-Put-Timestamp
Content-Type: text/plain; charset=utf-8
Date: Wed, 14 Mar 2018 08:43:43 GMT
X-Backend-Delete-Timestamp: 0000000000.00000
X-Backend-Put-Timestamp: 1445521637.35495
X-Backend-Status-Changed-At: 1445521364.56786
X-Backend-Storage-Policy-Index: 0
X-Backend-Timestamp: 1445521364.51371
X-Container-Bytes-Used: 2455570
X-Container-Domains:
X-Container-Meta-Type: gallery
X-Container-Object-Count: 9
X-Put-Timestamp: 1445521637.35495
X-Timestamp: 1445521364.51371

Установка,  изменение и удаление метаданных контейнера

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container- Meta-Type

  • X-Container-Meta-Some — метаданные контейнера

Устанавливает для указанного контейнера метаданные, переданные в заголовке X-Container-Meta-Some

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Some — метаданные контейнера

Заменяет метаданные на новые, которые передаются в заголовке  X-Container-Meta-Some

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Remove-Container-Meta-Some — метаданные контейнера, которые требуется удалить

Удаляет метаданные, переданные в заголовке  X-Remove-Container-Meta-Some

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

curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Type: gallery"

Создание галереи изображений

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Type: gallery — тип контейнера (в нашем случае — галерея)

Активирует демонстрацию изображений в виде галереи

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container  -H "X-Auth-Token: $token" -H "X-Container-Metatype: gallery"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Получение списка файлов в контейнере

Параметры запроса

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/SEL_*****/container_name

  • X-Auth-Token — токен авторизации

Возвращает список файлов, находящихся в указанном контейнере. Список объектов ограничен 10000. Воспользуйтесь query-параметрами marker и limit для гибкого получения списков объектов в контейнере

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container_name  -H "X-Auth-Token: $token"

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

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Storage-Policy-Index,X-Backend-Status-Changed-At,X-Put-Timestamp,
X-Container-Meta-Type,X-Timestamp,X-Backend-Delete-Timestamp,X-Backend-Timestamp,X-Backend-Put-Timestamp,
X-Container-Bytes-Used,Content-Length,X-Container-Object-Count,Content-Type,Date
Content-Length: 120
Content-Type: text/plain; charset=utf-8
Date: Wed, 14 Mar 2018 09:11:28 GMT
X-Backend-Delete-Timestamp: 0000000000.00000
X-Backend-Put-Timestamp: 1445521637.35495
X-Backend-Status-Changed-At: 1445521364.56786
X-Backend-Storage-Policy-Index: 0
X-Backend-Timestamp: 1445521364.51371
X-Container-Bytes-Used: 2455570
X-Container-Meta-Type: gallery
X-Container-Object-Count: 9
X-Put-Timestamp: 1445521637.35495
X-Timestamp: 1445521364.51371
File1
File2
File3
File4

Дополнительные query-параметры

В запросе на получение списка файлов можно также использовать дополнительные query-параметры, например:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?format=json -H "X-Auth-Token: $token"

В результате выполнения этой команды будет возвращён список файлов в формате json.  Можно указать и другой формат выдачи списка — xml:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?format=xml -H "X-Auth-Token: $token"

С помощью параметра limit  можно задать точное количество файлов, которые будут включены в список. Такая возможность бывает полезна при работе с контейнерами, где хранится множество объектов (например, тысячи или даже десятки тысяч):

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?limit=20 -H "X-Auth-Token: $token"

В результате выполнения этой команды в список будут включены только первые 20 файлов.  Информации обо всех остальных файлах в списке не будет.

Параметр marker позволяет указать имя файла, с которого будет начинаться список:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?marker=file3 -H "X-Auth-Token: $token"

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

С помощью параметра prefix в список можно включать файлы, имена которых начинаются с указанного буквосочетания:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?prefix=my_ -H "X-Auth-Token: $token"

С помощью параметра delimiter можно выводить только ту часть имени файлов, которая следует до определённого символа, например:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/?delimiter=.

В результате выполнения этой команды будет выведена только та часть имён файлов, которая идёт до точки (только имена без расширения).

Удаление контейнера

Внимание! Перед удалением контейнера необходимо удалить из него все файлы.  Если в контейнере имеется хотя бы один файл, удаление невозможно.

Тип запроса

URI

Заголовки

Описание

DELETE

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

Удаляет указанный контейнер

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/ -X DELETE -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Скачивание контейнера в виде zip-архива

Содержимое любого контейнера можно скачать в виде zip-архива. Для этого к ссылке на контейнер нужно добавить query-параметр download-all-as-zip=[имя архива], например:

wget https://api.selcdn.ru/v1/SEL_*****/container_name/?download-all-as-zip=container_name.zip

В публичных контейнерах функционал скачивания zip-архива отключен по умолчанию, чтобы его включить надо установить заголовок X-Container-Meta-Allow-ZipDownload: true, пример:

curl -i -XPUT https://api.selcdn.ru/v1/SEL_***/container_name -H "X-Auth-Token: $token" -H "X-Container-Meta-Allow-ZipDownload: true"

Значение этого заголовка X-Container-Meta-Allow-ZipDownload в приватных контейнерах игнорируется.

Для скачивания содержимого любого публичного контейнера в виде zip-архива могут быть использованы следующие команды:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -o name.zip

Для скачивания содержимого любого приватного контейнера в виде zip-архива могут быть использованы следующие команды:

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip

Для просмотра содержимого скачанного архива используйте команду:

unzip -l name.zip

Archive: name.zip 
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway) 
Length Date Time Name 
--------- ---------- ----- ---- 
555436    1980-00-00 00:00 IMG_20180802_121146.jpg
39        1980-00-00 00:00 copied_file 
245473    1980-00-00 00:00 mergetree.pdf
--------- ------- 
800948    3 files

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

Количество объектов в одном контейнере не должно превышать 10 000, иначе команда не сработает и вернет ошибку.

Можно скачивать объекты, начинающиеся на один заданный префикс (например, IMG), в виде zip-архива, указав данный префикс IMG в параметре IMG?download-all-as-zip:

curl -i -XGET https://*****.selcdn.ru/container/?IMG?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip

Примечание: если среди объектов будет папка, начинающаяся на этот же префикс, то будет скачана и она вместе со всем содержимым.

Скачивание папки в виде zip-архива

Содержимое любой папки можно скачать в виде zip-архива. Для этого к ссылке на папку нужно добавить query-параметр download-all-as-zip=[имя архива], например:

wget https://api.selcdn.ru/v1/SEL_*****/container_name/folder/?download-all-as-zip=container_name.zip

Для скачивания содержимого любой папки в виде zip-архива могут быть использованы следующие команды:

curl -i -XGET https://*****.selcdn.ru/container/folder?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip

Для просмотра содержимого скачанного архива используйте команду:

unzip -l name.zip

Archive: name.zip 
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway) 
Length Date Time Name 
--------- ---------- ----- ---- 
555436    1980-00-00 00:00 IMG_20180802_121146.jpg
39        1980-00-00 00:00 copied_file 
245473    1980-00-00 00:00 mergetree.pdf
--------- ------- 
800948    3 files

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

Количество объектов в одной папке не должно превышать 10 000, иначе команда не сработает и вернет ошибку.

Работа с файлами

Скачивание файла из контейнера

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/SEL_*****/container/file

  • X-Auth-Token — токен авторизации (обязателен только при скачивании из приватного контейнера; из публичных контейнеров файлы можно скачивать без токена)

Также в запросе можно использовать стандартные HTTP-заголовки, описанные в RFC2616:

  • If-Match

  • If-None-Match

  • If-Modified-Since

  • If-Unmodified-Since

Скачивает указанный файл

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

curl -O https://api.selcdn.ru/v1/SEL_*****/images/image1.png

Для того чтобы открыть файл в браузере введите команду:

https://*****.selcdn.ru/1111_Union.patch.xml?filename=1111_Union.patch.xml

Ответ будет выглядеть следующим образом:

HTTP/2 200
accept-language: bytes
access-control-allow-origin: *
access-control-expose-headers: Content-Type,Etag,X-Client,X-Timestamp,X-Trans-Id,Content-Length,Last-Modified,Accept-Ranges
content-length: 5782
content-type: application/xml
etag: "61808ed864f4c3453d329071986b04ba"

Для того чтобы скачать файл без открытия в браузере добавьте к ссылке get параметр ?filename=some_name.ext:

https://*****.selcdn.ru/1111_Union.patch.xml?filename=1111_Union.patch.xml?filename=Union.patch.xml

Браузер предложит скачать файл под именем Union.patch.xml. Ответ будет выглядеть следующим образом:

HTTP/2 200
accept-language: bytes
access-control-allow-origin: *
access-control-expose-headers: Etag,X-Client,X-Timestamp,X-Trans-Id,Last-Modified,Accept-Ranges,Content-Length,Content-Type
content-disposition: attachment; filename="1111_Union.patch.xml" ← в ответе добавляется этот заголовок, который говорит браузеру скачать файл
content-length: 5782
content-type: application/xml
etag: "61808ed864f4c3453d329071986b04ba"

Загрузка файла в контейнер

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container/file

  • X-Auth-Token — токен авторизации

  • X-Delete-At —  время удаления файла в формате Unix Timestamp

  • X-Delete-After — cрок хранения файла (в секундах)

  • Etag — идентификатор Etag

  • X-Object-Meta — метаданные загружаемого объекта

Загружает объект в указанный контейнер

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

curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/file  -H "X-Auth-Token: $token" -H "X-Delete-After: 180"  -T "file"

При удачном выполнении запроса будет возвращён ответ с кодом 201.

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

HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 0
Content-Type: text/html
Etag: b65ad34618e410d9d8bf624d61f8a980
Date: Thu, 15 Mar 2018 07:31:32 GMT

Удаление файла

Тип запроса

URI

Заголовки

Описание

DELETE

https://api.selcdn.ru/v1/SEL_*****/container/file

  • X-Auth-Token — токен авторизации

Удаляет указанный файл

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container/file -X DELETE -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Удаление множества объектов из хранилища

Команда bulk-delete в отличие от команды delete:

  • Позволяет удалить нескольких файлов одновременно
  • Позволяет удалять объекты из разных контейнеров одновременно
  • Работает последовательно

Для работы этой команды подходит только токен основного пользователя.

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_******?bulk-delete=true

  • X-Auth-Token — токен авторизации

  • X-Delete-After — cрок хранения файла (в секундах)

Удаляет несколько указанных файлов одновременно

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

curl -i -XGET "https://api.selcdn.ru/v1/SEL_******?bulk-delete=true" \
-H "X-Auth-Token: $token" -X POST -H "Content-Type: text/plain" --data  $"container/file1\ncontainer/file2\n"

При удачном выполнении запроса возвращается ответ с кодом 200.

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

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: application/json; charset=utf-8
Date: Fri, 08 Jun 2018 13:37:53 GMT
Content-Length: 101
{"Number Not Found":0,"Response Status":"200 OK","Response Body":"","Errors":null,"Number Deleted":2}

Отложенное удаление с помощью X-Delete

Имеется два возможных варианта заголовков:

  • X-Delete-At

  • X-Delete-After

Оба варианта позволяют установить временной интервал для автоматического удаления объекта из хранилища. Отправка заголовков производится с помощью PUT и POST запросов.

X-Delete-At

В качестве значения заголовка передается значение времени (timestamp) в формате Unix Epoch. Это значение укажет серверу до какого времени следует хранить объект. Для конвертирования в человекочитаемый вид удобно использовать онлайн-конвертер.

Unix Epoch

Human View

1317070737

Mon Sep 26 20:58:57 2011 UTC

X-Delete-After

В качестве значения заголовка передается целочисленное количество секунд, по прошествии которых объект отправится на удаление. Сервер, получив это значение, преобразует его в заголовок X-Delete-At и при наступлении указанного значения времени перестает хранить объект.

Доступ к объектам, которым передали заголовок X-Delete-* прекращается после того как значение времени истекло. Сервер в ответ на запрос такого объекта будет отдавать ответ 404. Сами по себе объекты автоматически удаляются через некоторое время.

Двойной заголовок

Если объекту передать оба заголовка одновременно, то система будет считать приоритетным заголовок X-Delete-After.

Внутренние операции

Текущая реализация имеет следующие особенности:

  • Если объект, имеющий X-Delete-At, помещается с помощью PUT в контейнер с модифицированным заголовком, то заголовок объекта будет перезаписан на заголовок контейнера

  • Если объект, имеющий X-Delete-At, помещается с помощью PUT и установленным заголовком X-Copy-From в контейнер, уже имеющий модифицированный заголовок, то заголовок объекта сохранится с предыдущего источника и не будет перезаписан

  • При копировании объекта с установленным заголовком X-Delete-At с помощью COPY и заголовком Destination - заголовок не сохраняется

  • При помещении объекта в контейнер для версионированных объектов через панель управления облачным хранилищем заголовок X-Delete-At / X-Delete-After сохранится в неизменном виде и объект будет удален в соответствии с указанным значением

  • При помещении объекта в контейнер для версионированных объектов c помощью API (команда COPY c заголовком Destination), заголовок не сохраняется

Распаковка архивов

Архивы в формате *.tar, *.tar.gz и *.gzip могут быть распакованы сразу после загрузки в хранилище. Чтобы распаковать архив, в запрос на загрузку файла нужно добавить query-параметр extract-archive:

curl -i -XPUT  https://api.selcdn.ru/v1/SEL_*****/new_container/archive.tar.gz/?extract-archive=tar.gz \
-H "X-Auth-Token: $token" -T "archive.tar.gz"

Управление HTTP-заголовками для файлов

Для всех файлов, помещаемых в хранилище, можно устанавливать HTTP-заголовки.  Заголовки используются для управления кэшированием на стороне клиента (и на промежуточных прокси-серверах), а также для обработки кросс-доменных запросов (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

  • Link

  • Content-Type

  • Content-Disposition (только для конечного файла)

  • Strict-Transport-Security (только для контейнера)

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-.... — заголовок, параметры которого нужно установить (сам заголовок указывается после -Meta-, например: X-Container-Meta-Cache-Control

Устанавливает значения для указанных в запросе заголовков

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

curl -i -XPOST  https://api.selcdn.ru/v1/SEL_*****/container -H "X-Auth-Token: $token" \
-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"

В случае удачного выполнения запроса API возвращает ответ с кодом 202.

Для добавления заголовка Link к объекту file1 введите:

curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container/file1 -H "X-Auth-Token: $token" -H "Link: rel=canonical"

Чтобы добавить данный заголовок сразу ко всем объектам в контейнере, используется запрос:


curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Auth-Token: $token" -H "X-Container-Meta-Link: rel=canonical"

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

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 76
Content-Type: text/html

Поддержка больших объектов

В хранилище нет ограничений на размер загружаемых файлов. Однако файлы размером более 1 ГБ не рекомендуются помещать в хранилище целиком: для этого предпочтительнее использовать сегментную загрузку.

Существует два варианта сегментной загрузки: динамическая и статистическая.

Динамическая загрузка

В динамической загрузке объект разбивается на сегменты, после чего создаётся так называемый манифест.  Манифестом называется пустой файл, содержащий указатель на контейнер, в который загружены все сегменты.  В запросе на загрузку большого объекта путь к контейнеру указывается в заголовке X-Object-Manifest.

Желательно сначала загружать сегменты, а уже потом — создавать или обновлять манифест: объект не будет доступен для скачивания, пока не завершится загрузка всех сегментов.

Пример

curl -X PUT -H 'X-Auth-Token: $token'  https://api.selcdn.ru/v1/SEL_*****/new_container/big_object/00000001 --data-binary '1' \
curl -X PUT -H 'X-Auth-Token: $token'  https://api.selcdn.ru/v1/SEL_*****/new_container/big_object/00000002 --data-binary '2' \
curl -X PUT -H 'X-Auth-Token: $token'  https://api.selcdn.ru/v1/SEL_*****/new_container/big_object/00000003 --data-binary '3'

Пример манифеста

curl -X PUT -H 'X-Auth-Token: $token' -H 'X-Object-Manifest: container/myobject/'  https://api.selcdn.ru/v1/SEL_*****/new_container/big_object/ --data-binary '' 

Статическая загрузка

При статической загрузке нужно создать статический манифест с указанием путей до сегментов, их контрольной суммы (Etag) и размера. Манифест сохраняется в специальном файле.

Пример манифеста

[{"path": "/cont/object",  "etag": "etagoftheobjectsegment",  "size_bytes": 10485760, }, ...]

Файл манифеста нужно загрузить в хранилище  PUT-запросом с query-параметром ?multipart-manifest=put  и заголовком X-Static-Large-Object: True.

Чтобы получить файл манифеста, нужно выполнить GET-запрос с query-параметром ?multipart-manifest=get.

Удалить все сегменты, а затем файл с манифестом можно с помощью DELETE-запроса с query-параметром ?multipart-manifest=delete.

Установка срока хранения для файлов

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Default-Delete-After — cрок хранения для всех файлов в контейнере (в секундах)

Устанавливает срок хранения для всех файлов, помещаемых в контейнер. По истечении этого срока все файлы будут автоматически удалены

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

curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container  -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Default-Delete-After: 300"

При удачном выполнении запроса будет возвращён ответ с кодом 202

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

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 76
Content-Type: text/html

Установка метаданных файла

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container/file

  • X-Auth-Token — токен авторизации

  • X-Object-Meta-Some —  любая дополнительная информация о файле

Добавляет в файл метаданные, переданные в заголовке X-Object-Meta-Some

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

curl -i -XPOST  https://api.selcdn.ru/v1/SEL_***/new_container/file -H "X-Auth-Token: $token" -H "X-Object-Meta-Some: metadata"

В случае успешного выполнения запроса API возвращает ответ с кодом 201.

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

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 0
Content-Type: text/html
Etag: d41d8cd98f00b204e9800998ecf8427e

Копирование файлов внутри хранилища

Способ 1

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/new_location/указываем путь к контейнеру и папке, куда нужно копировать файл/имя_файла

  • X-Auth-Token — токен авторизации

  • X-Copy-From — путь к файлу, который нужно скопировать

Копирует файл из одной локации в другую

При этой операции так же копируется значение заголовка x-delete-at, независимо от того, куда был установлен этот заголовок - на объект-источник или контейнер-источник.

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

curl -i -X PUT https://api.selcdn.ru/v1/SEL_*****/container2/file -H "X-Auth-Token: $token" -H "X-Copy-From: /container1/file"

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

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 2018 06:30:51 GMT

Способ 2

Тип запроса

URI

Заголовки

Описание

COPY

https://api.selcdn.ru/v1/SEL_*****/container/file/указываем путь к файлу, который нужно копировать/

  • X-Auth-Token — токен авторизации

  • Destination —путь к контейнеру и папке, куда нужно копировать файл

Копирует файл из одной локации в другую

Если при использовании этого способа установить заголовок -H "X-Fresh-Metadata: true", то при копировании новый объект будет создан с новыми заголовками, в том числе без X-Delete-At.

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

curl -i -X COPY https://api.selcdn.ru/v1/SEL_*****/container1/file -H "X-Auth-Token: $token" -H "Destination: /container2/file"

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

HTTP/1.1 201 
Created etag: 0f343b0931126a20f133d67c2b018a3b 
X-Copied-From: container1/file
X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT 
Last-Modified: Tue, 28 May 2013 06:30:51 GMT

Создание символической ссылки на файл

При использовании хранилища в качестве бэкенда для публичных сервисов нередко возникает необходимость разграничить доступ к файлам — например, сделать доступными для широкого круга пользователей файлы, помещённые в приватный контейнер.

Специально для таких случаев в хранилище предусмотрена возможность создавать символические ссылки. Такие ссылки можно защищать паролем, а также устанавливать для них срок действия.

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container/file

/в адресе указывается контейнер, в котором будет храниться символическая ссылка, и имя, под которым эта ссылка будет сохранена/

  • X-Auth-Token — токен авторизации

  • Content-Type —  тип символической ссылки (x-storage/onetime-symlink — одноразовая ссылка, x-storage/symlink+secure — обычная ссылка, защищенная паролем, x-storage/onetime-symlink+secure — одноразовая ссылка, защищенная паролем)

  • X-Object-Meta-Location — заквотированный путь к объекту в хранилище

  • X-Object-Meta-Delete-At — дата (в формате Unix Timestamp), до которой ссылка будет действительна

  • X-Object-Meta-Link-Key — sha1-хэш от пароля и расположения объекта (для защищённых паролем ссылок; подробности в Пример генерации X-Object-Meta-Link-Key на Python)

  • Content-Disposition — указывает, что делать с файлом, на который создана ссылка: открывать в браузере (inline) или скачивать на локальную машину (attachment)

Создаёт символическую ссылку с заданными в запросе параметрами.

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

curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/new_link \
-H "X-Auth-Token: $token" -H "Content-Type: x-storage/symlink" \
-H "X-Object-Meta-Location: /new_container/new_object" \
-H "X-Object-Meta-Link-Key: $key" -H "Content-Length: 0"

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

HTTP/1.1 201 Created
> etag: d41d8cd98f00b204e9800998ecf8427e
> Last-Modified: Mon, 27 May 2013 13:34:34 GM
import hashlib

# location of file, always with container specified
location = "/container/object"

# password
password = "12345"

# concatenate password + location and encode it
encoded_pass_loc = (password + location).encode('utf-8')

# generate sha1-hash
hash_object = hashlib.sha1(encoded_pass_loc)

# convert sha1-hash to hexadecimal digits
link_key = hash_object.hexdigest()

# show calculated value
print(link_key)

Создание ссылки для скачивания файла

Можно создавать специальные ссылки, по которым сторонние пользователи могут скачать ваши файлы (в том числе и из личных контейнеров).  

Для создания такой ссылки не нужно выполнять запрос к API.

Прежде чем генерировать ссылки на файлы аккаунта, нужно самостоятельно установить секретный ключ $key:

curl -i -XPOST http://*****.selcdn.ru/   -H "X-Auth-Token: $token" -H "X-Account-Meta-Temp-URL-Key: $key"

Для создания ссылки на конкретный контейнер, установите секретный ключ $key, добавив имя контейнера:

curl -i -XPOST http://*****.selcdn.ru/сontainer   -H "X-Auth-Token: $token" -H "X-Container-Meta-Temp-URL-Key: $key"

Доступ к файлам по сгенерированной ссылке смогут получить только пользователи, которым известен секретный ключ.

Пример на Python

import hmac
from hashlib import sha1
from time import time

# access method (always GET)
method = "GET"

# reference valid 60 seconds
expires = int(time()) + 60

# the path to the file in the repository, always with the container specified
path = "/container/dir/file"

# secret key
link_secret_key = "$key"

# generate access key
hmac_body = '%s\n%s\n%s' % (method, expires, path)

# access key
sig = hmac.new(link_secret_key, hmac_body, sha1).hexdigest()


#show calculated values
print sig,expires

При использовании ссылки вида  https://api.selcdn.ru/v1/SEL_***/container_name/object_name в вышеприведённом скрипте переменная path должна иметь вид  v1/SEL_***/container_name/object_name.

Полученный в результате ключ затем нужно будет указать в ссылке:

http://****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=13909142

где:

  • *****.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://*****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc

Секретный ключ можно изменить. После изменения секретного ключа все сгенерированные ранее ссылки перестанут работать.

Создание ссылки для загрузки файлов (sendmefile)

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container/upload

  • X-Auth-Token — токен авторизации

  • Content-Type — свойства ссылки (x-storage/sendmefile+inplace — загрузка только одного файла с указанным именем, x-storage/sendmefile+timepostfix —- загрузка файлов с добавлением времени загрузки к имени, x-storage/sendmefile+autopostfix — загрузка файлов с добавлением уникального идентификатора к имени с учетом расширения, x-storage/sendmefile+folderday — загрузка файлов в папку с именем вида yyyy-dd-mm, x-storage/sendmefile+folderhour — загрузка файлов в папку с именем вида dd-mm hh:min min, x-storage/sendmefile+folderuniq — загрузка каждого файла в отдельную папку)

  • X-Object-Meta-Sendmefile-Disable-Web  —  включает (yes)/отключает (no) веб-интерфейс для загрузки файлов; по умолчанию этот заголовок имеет значение yes (веб-интерфейс включён)

  • X-Object-Meta-Sendmefile-Max-Size — максимальный размер загружаемого файла (в байтах)

  • X-Object-Meta-Sendmefile-Allow-Overwrite —  разрешает (yes) или запрещает (no) перезапись файлов при повторной загрузке (по умолчанию перезапись запрещена)

  • X-Object-Meta-Sendmefile-Ignore-Filename — разрешить (yes) автоматическое переименование файлов в соответствии с заданными настройками

  • X-Object-Meta-Sendmefile-Secret —  хэш пароля (для защищённых паролем ссылок)

  • X-Filename  — имя, под которым файл будет загружен в хранилище

  • X-Sendmefile-Session-Id —  идентификатор сессии загрузки

Создаёт ссылку, по которой сторонние пользователи могут загружать файлы в хранилище

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

curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container/upload \
-H "X-Auth-Token: $token"    -H "Content-Type: x-storage/sendmefile+inplace"  \   
-H "X-Object-Meta-Sendmefile-Max-Size: 52428800" \
-H "X-Object-Meta-Sendmefile-Expire: 14400" \  
-H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68" \
-d "Пояснительный текст для страницы загрузки"

Версионирование

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

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Versions-Location — имя контейнера, где будут храниться версии

Активирует версионирование для указанного контейнера.  Версии всех объектов будут сохранены в контейнере, имя которого передано в заголовке X-Versions-Location

Примечание: реализован заголовок X-Versions-Location, при этом на место удалённого объекта не возвращается его последняя рабочая версия. Все версии объекта, в том числе та, что была перед удалением, хранятся в контейнере для версий.

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

curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container1/ -XPUT -H "X-Auth-Token: $token" -H "X-Versions-Location: container2"

При удачном выполнении запроса будет возвращён ответ с кодом 202.

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

HTTP/1.1 202 Accepted Content-Length: 76 
Content-Type: text/html; charset=UTF-8 
Access-Control-Allow-Origin: * Access-Control-Expose-Headers: Expires: 0 Pragma: no-cache 
Cache-Control: no-cache, no-store, must-revalidate

Специальные страницы

К специальным страницам относятся:

  • Индексная страница, отдаваемая в ответ на анонимный GET-запрос  на контейнер или папку, помещенную в этот контейнер

  • Страница ошибки (404) - файл, отдаваемые при анонимном GET-запросе к несуществующему объекту

Индексная страница

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container/index_file

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Web-Index — путь к файлу, который будет использоваться в качестве индексного

Назначает индексный файл для указанного контейнера

В запросе можно указывать как абсолютный, так и относительный путь к файлу. 

Web-IndexЗапросОтданный файл
/index.html

GET /container/

GET /container/dir1/

/container/index.html
index.htmlGET /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://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" -H "X-Auth-Token: $token" -T "./my_index.html"

Для задания индексной страницы установите значение Web-Index для контейнера:

curl -i -XPUT "https://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" \
-H "X-Auth-Token: $token" -H "X-Container-Meta-Web-Index:/my_index.html"

Страница 404

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/SEL_*****/container/error_file

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Web-404-Page — путь к файлу ошибки

Настраивает файл ошибки для указанного контейнера

Примеры

Web-404-PageЗапросАдрес перенаправления
/404.html

GET /container/nofile

GET /container/dir1/nofile

/container/404.html
404.html/container/nofile/container/404.html


GET /container/nofile/container/dir1/dir2/404.html или (если файла нет) /container/404.html
http://test.test

GET /container/nofile

/container/dir1/nofile

http://test.test

Доступные шаблонные параметры

Чтобы передавать информацию об изначально запрашиваемом файле, можно использовать специальные шаблонные параметры:

  • {container} - имя контейнера
  • {path} - путь к запрошенному файлу относительно контейнера
  • {code} - позволяет задать код ответа

По умолчанию переадресация выполняется с кодом 307.  Доступные варианты: 200, 307, 404. При установке внешней ссылки доступно
задание только кода 307.

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

Установите значение Web-404-Page для контейнера:

curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}"

При анонимном запросе на несуществующий объект задайте перенаправление на указанный файл:

curl -i "https://api.selcdn.ru/v1/SEL_*****/container_name/non_existing_object" \
> HTTP/1.1 307 Temporary Redirect 
> Location: https://api.selcdn.ru/v1/SEL_*****/404.html?file=non_existing_object

По умолчанию при отправке страницы ошибки возвращается код 404:

curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}?{code}"

Листинг файлов

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Web-Listings — on/off - включить или отключить режим листинга для контейнера

  • X-Container-Meta-Web-Listings-CSS — ссылка на файл стилей, используется для выводов в HTML-формате (необязательная)

  • X-Container-Meta-Web-Listings-Sort — тип сортировки листинга, возможные значения: name_asc, name_desc, date_asc, date_desc, size_asc, size_desc; можно сортировать по имени, дате изменения и размеру. Asc и desc определяют порядок сортировки

Включает режим листинга файлов для
указанного в запросе контейнера

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

curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings: on"

Для получения листинга файлов анонимным запросом введите: 

curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Web-Mode: listing"

Для получения листинга приватного контейнера укажите токен пользователя, имеющего доступ к контейнеру:

curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" -H "X-Web-Mode: listing"

Для выводов в HTML-формате можно задавать оформление с помощью заголовка X-Container-Meta-Web-Listings-Css, в качестве значения которого указывается ссылка на файл стилей в контейнере; можно также дать ссылку на внешний файл стилей.

Web-Listings-CSSПоведение
my.css или /my.css

Будет использоваться файл стилей, находящийся в этом же контейнере

http://my_site/my.cssБудут использоваться файл стилей с внешнего сайта

Устанавливаем значение Web-Listings-CSS для контейнера:

curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings-Css: my_style.css"

Установка лимитов

Установка лимитов для контейнера

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container/

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Quota-Bytes —максимальный допустимый объём хранимых данных (в байтах)

  • X-Container-Meta-Quota-Count — максимальное возможное количество файлов и папок в контейнере

Устанавливает для указанного контейнера ограничения, переданные в заголовках X-Container-Meta-Quota-Byte и X-Container-Meta-Quota-Count

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

curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container/  -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

В случае удачного выполнения запроса будет возвращён ответ с кодом 202.

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

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 76
Content-Type: text/html

Установка лимитов для учётной записи в целом

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/

  • X-Auth-Token — токен авторизации

  • X-Container-Meta-Quota-Bytes — максимальный допустимый объём хранимых данных (в байтах)

  • X-Container-Meta-Quota-Count — максимальное возможно количество файлов и папок

Устанавливает переданные в заголовка ограничения X-Container-Meta-Quota-Bytes и X-Container-Meta-Quota-Count ограничения.  Ограничения будут действовать на уровне аккаунта, для всех файлов и папок

curl -i -XPOST https://api.selcdn.ru/v1/SEL_***** -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

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

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 76
Content-Type: text/html

Управление пользователями

Просмотр списка пользователей

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/users

  • X-Auth-Token — токен авторизации

Выводит список пользователей для текущего аккаунта

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

curl -i https://api.selcdn.ru/v1/users  -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API вернёт ответ с кодом 200.

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

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
Content-Length: 80
main_user (true)
main_user (true)
user1 (true)
user2 (true)
user3 (true)

Добавление нового пользователя

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/users/username

  • X-Auth-Token — токен авторизации

  • X-Auth-Key —  пароль для нового пользователя

  • X-User-Active — статус пользователя (on — активен, off— неактивен)

  • X-User-ACL-Containers-R — имена контейнеров, которые новому пользователю будут доступны только для чтения

  • X-User-ACL-Containers-W — список контейнеров, которые будут доступны новому пользователю для записи

  • X-Store-Password — указывает, нужно ли хранит пароль нового пользователя в открытой базе (аналогично опции “Хранить пароль на серверах Selectel” в панели управления)

Создаёт пользователя с указанными настройками учётной записи

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

curl -i -XPUT https://api.selcdn.ru/v1/users/my_test_user  
-H "X-Auth-Token: $token" 
-H "X-Auth-Key: $key" 
-H "X-User-ACL-Containers-W: container1, container2, container3" 
-H "X-User-ACL-Containers-R: container4" 
-H "X-User-Store-Password: yes" 
-H "X-User-Active: on"

При удачном выполнении запроса API возвращает ответ с кодом 201.

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

HTTP/1.1 201 Created
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Удаление пользователя

Тип запроса

URI

Заголовки

Описание

DELETE

https://api.selcdn.ru/v1/users/username

  • X-Auth-Token — токен авторизации

Удаляет указанного пользователя

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

curl -i -X DELETE https://api.selcdn.ru/v1/users/my_test_user  -H "X-Auth-Token: $token"

В случае успешного удаления пользователя API возвращает ответ с кодом 201.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:04:25 GMT

Изменение пароля основного пользователя

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/users/

  • X-Auth-Token — токен авторизации

  • X-Auth-Key — новый пароль

  • X-Store-Password — указывает, нужно ли хранит пароль нового пользователя в открытой базе (аналогично опции “Хранить пароль на серверах Selectel” в панели управления)

Меняет пароль основного пользователя на переданный в заголовке X-Auth-Key

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

curl -i -XPOST https://api.selcdn.ru/v1/users -H "X-Auth-Token: $token" -H "X-Auth-Key: $key" -H "X-User-Store-Password: yes"

При удачном выполнении запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:30:59 GMT

Управление доменами

К контейнерам в хранилище можно прикреплять домены.  Все операции с доменами осуществляются через API.

Домены по умолчанию

Каждый пользователь облачного хранилища автоматически получает набор доменов по умолчанию, которые можно использовать для доступа к объектам в любых контейнерах:

  • *****.selcdn.ru —  домен для публичного доступа к файлам в хранилище

  • *****.selcdn.com  — домен для раздачи файлов через CDN по http

Через тикет-систему можно заказать домен вида xxxx.akamaihd.net, который может использоваться для https-доступа к объектам в контейнерах через CDN-кэш нашего партнера Akamai.

Получение списка прикреплённых доменов

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/domains

  • X-Auth-Token — токен авторизации

Возвращает список доменов

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

curl -i -XGET https://api.selcdn.ru/domains -H "X-Auth-Token: $token"

При удачном выполнении запроса API возвращает ответ с кодом 200.

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

HTTP/1.1 200 OK
Content-Length: 69
Content-Type: text/html
Date: Mon, 16 May 2016 07:36:35 GMT
Base Domains:
00000.selcdn.ru
00000.selcdn.com
Containers Domains:
container1  domain1.ru
container2  domain1.ru

Прикрепление домена

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Add-Container-Domains — имя домена, который будет прикреплён к контейнеру

Прикрепляет к контейнеру домен, имя которого передано в заголовке X-Add-Container-Domains

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

curl -i -XGET https://api.selcdn.ru/v1/container -XPOST -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API вернёт ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Tue, 20 Mar 2018 12:09:38 GMT

Удаление домена

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Remove-Container-Domains — имя домена, который будет  удалён (откреплён от контейнера)

Удаляет домен, имя которого передано в заголовке X-Remove-Container-Domains

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

curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -XPOST \
-H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff

Редактирование списка доменов

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/SEL_*****/container

  • X-Auth-Token — токен авторизации

  • X-Container-Domains — имя домена, который будет  удалён (откреплён от контейнера)

Удаляет домен, имя которого передано в заголовке X-Remove-Container-Domains

curl -i -XPOST https://api.selcdn.ru/v1/SEL_***** -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

В случае удачного выполнения запроса API возвращает ответ с кодом 204.

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

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff

Управление пользовательскими SSL-сертификатами

Получение списка сертификатов

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/ssl

  • X-Auth-Token — токен авторизации

Возвращает список сертификатов

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

curl -i -XGET https://api.selcdn.ru/v1/ssl -H "X-Auth-Token: $token"

Получение информации о сертификате

Тип запроса

URI

Заголовки

Описание

GET

https://api.selcdn.ru/v1/ssl/cert

  • X-Auth-Token — токен авторизации

Возвращает информацию об указанном сертификате

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

curl -i -XGET https://api.selcdn.ru/v1/ssl/cert -H "X-Auth-Token: $token"

Добавление сертификата

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/ssl/*****_cert1


  • X-Auth-Token — токен авторизации

Добавляет новый сертификат

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

curl -I -XGET https://api.selcdn.ru/v1/ssl/*****_cert1 -H "X-Auth-Token: $token" -XPUT -T ./cert1.pem

Имя сертификата ({cert_name}) нужно передавать в формате *****_cert1, где первая часть (цифры) представляет собой номер учётной записи пользователя, а вторая — любую произвольную комбинацию символов.

Имена сертификатов должны быть уникальными; загрузить два сертификата с одинаковыми именами невозможно.
Сам сертификат и приватный ключ нужно передать в теле запроса в одном файле.

Удаление сертификата

Тип запроса

URI

Заголовки

Описание

DELETE

https://api.selcdn.ru/v1/SEL_*****/ssl/cert

  • X-Auth-Token — токен авторизации

Удаляет указанный сертификат

Сброс кэша CDN

Тип запроса

URI

Заголовки

Описание

PUT

https://api.selcdn.ru/v1/cdn/purge

  • X-Auth-Token — токен авторизации

Очищает кэш CDN для страниц, адреса которых переданы в запросе

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

curl -i -X PUT https://api.selcdn.ru/v1/cdn/purge -H "X-Auth-Token: $token" -d $'https://*****.selcdn.com/container/file'

При удачном выполнении запроса API вернёт ответ с кодом 200.

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

HTTP/1.1 200 OK
Date: Mon, 16 May 2016 09:45:15 GMT
Content-Length: 268
Content-Type: text/plain; charset=utf-8
{"estimatedSeconds": 5, "progressUri": "/ccu/v2/purges/e4561042-1b4a-11e6-9024-f3cf5304c77a", "purgeId": "e4561042-1b4a-11e6-9024-f3cf5304c77a", "supportId": "17PY1463391915374207-348128448", "httpStatus": 201, "detail": "Request accepted.", "pingAfterSeconds": 300}

Получение логов

Запрос на создание выгрузки

Тип запроса

URI

Заголовки

Описание

POST

https://api.selcdn.ru/v1/logs

  • X-Auth-Token — токен авторизации

Создать контейнер logs и выгрузить в него логи хранилища

Тело запроса:

{
  "since": "2019-05-14T06:00:00",
  "till": "2019-12-09T13:43:00",
  "fields": [
    "container_name"
  ],
  "filters": {
    "host": [
      "example.com",
      "foo.bar.baz"
    ]
  },
  "container": "logs",
  "delete_after": 3600
}

Описание полей тела запроса:

  • since --- начало периода для выгрузки;
  • till --- конец периода для выгрузки;
  • fields --- список необходимых полей;
  • filters --- фильтры для выгрузки;
  • container --- контейнер для выгрузки;
  • delete_after --- удаление объектов с логами через заданное время.

Список возможных полей (fields):

  • container_name
  • timestamp
  • host
  • servertoclient_bytes
  • clienttoserver_bytes
  • http_method
  • status
  • path
  • query
  • client_ip

Список возможных фильтров (filters):

  • host
  • container_name

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

curl -i -XPOST -H 'X-Auth-Token: $token' -d '{"since": "2019-05-14T06:00:00","till": "2019-12-09T13:43:00", "fields": ["container_name"], "filters": {"host": ["example.com", "foo.bar.baz"]}, "container": "logs", "delete_after": 3600}' 'https://api.selcdn.ru/v1/logs'

В случае удачного выполнения запроса API вернёт ответ с кодом 200.

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

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Content-Length: 342
Content-Type: application/json
Date: Tue, 14 Jan 2020 13:01:34 GMT
 
{
  "task": {
    "id": "896aae80-bc7e-434d-8528-5ca2bfb41a56",
    "created": "2020-01-14T13:01:34",
    "updated": "2020-01-14T13:01:34",
    "type": "storage_logs",
    "data": {
      "since": "2019-05-14T06:00:00",
      "till": "2019-12-09T13:43:00",
      "provider": "storage_access",
      "container": "logs",
      "fields": ["container_name"],
      "filters": {"host": ["example.com", "foo.bar.baz"]},
      "delete_after": 3600
    },
    "status": 0,
    "progress": 0
  }
}

Получение информации о созданной задаче

Тип запроса

URL

Описание запроса

GEThttps://api.selcdn.ru/v1/logs/$task_idПолучить информацию о задаче на выгрузку логов

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

curl -i -XGET -H 'X-Auth-Token: $token' 'https://api.selcdn.ru/v1/logs/896aae80-bc7e-434d-8528-5ca2bfb41a56'

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

{
  "task": {
    "id": "896aae80-bc7e-434d-8528-5ca2bfb41a56",
    "created": "2020-01-14T13:01:34",
    "updated": "2020-01-14T13:01:45",
    "type": "storage_logs",
    "data": {
      "till": "2019-12-09T13:43:00",
      "since": "2019-05-14T06:00:00",
      "fields": ["container_name"],
      "filters": {"host": ["example.com", "foo.bar.baz"]},
      "provider": "storage_access",
      "container": "logs",
      "delete_after": 3600
    },
    "status": 2,
    "progress": 100
  }
}