Swift (old)

к сведению

Это старая версия Swift API, которая использовалась до обновления объектного хранилища. URL и методы старой версии Swift API пока продолжают поддерживаться, но в будущем будут отключены. Мы рекомендуем использовать новую версию Swift API.

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

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

Формат 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. Подробнее в документации Openstack.

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

curl -i \
-H 'X-Auth-User: *****' \
-H 'X-Auth-Key: *****' \
https://api.selcdn.ru/auth/v1.0

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

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

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

Получить домен с помощью API можно следующим запросом:

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

В будущем мы планируем отказываться от номерных доменов, поэтому рекомендуется использовать ссылки типа https://api.selcdn.ru/v1/SEL_*****.

Доступ к 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 -XPOST https://api.selcdn.ru/v3/auth/tokens -d '{"auth": { "identity": { "methods": ["password"], "password": { "user": { "id": "*****", "password": "pA$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":[""]}}

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

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

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

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	общее количество хранимых объектов

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

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

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

Параметр	Значение
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	общее количество хранимых объектов

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

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

Тип запроса	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	общее количество хранимых в контейнерах объектов

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

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

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

Тип запроса URI Заголовки Описание

PUT

Тип запроса	URI	Заголовки	Описание
PUT	`https://api.selcdn.ru/v1/SEL\_\\\\\*/container`	X-Auth-Token — токен авторизации; X-Container-Meta-Type — тип контейнера: публичный (public) или приватный (private); X-Container-Meta-Some — метаданные контейнера; X-Storage-Policy — политика хранения: горячий (Policy-0) по-умолчанию, холодный (cold)	Создаёт контейнер с указанными в запросе параметрами

https://api.selcdn.ru/v1/SEL\_\*\*\*\*\*/container

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

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

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

X-Storage-Policy — политика хранения:

горячий (Policy-0) по-умолчанию,

холодный (cold)

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

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

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	Заголовки	Описание
GET	`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	Заголовки	Описание
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 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:

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

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

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

Тип запроса	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/container/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/container/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 -XDELETE https://api.selcdn.ru/v1/SEL_*****/container/file -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 -XPOST "https://api.selcdn.ru/v1/SEL_******?bulk-delete=true" -H "X-Auth-Token: $token" -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), заголовок не сохраняется.

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

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

Поддерживаются следующие заголовки:

Cache-Control
Access-Control-Allow-Origin
Access-Control-Max-Age
Access-Control-Allow-Methods
Access-Control-Allow-Credentials
Access-Control-Expose-Headers
Access-Control-Allow-Headers
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-Allow-Methods: 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

Просмотр заголовков конкретного объекта⁠

Для просмотра заголовков конкретного объекта введите:

curl --head https://api.selcdn.ru/v1/SEL_*****/images/file.png

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

В хранилище нет ограничений на размер загружаемых файлов, но файлы размером более 100 МБ не рекомендуется помещать в хранилище целиком — нужно использовать сегментированную загрузку.

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

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

В динамической загрузке объект разбивается на сегменты, после чего создается манифест — пустой файл, содержащий указатель на контейнер, в который загружены все сегменты. В запросе на загрузку большого объекта путь к контейнеру указывается в заголовке 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: new_container/big_object/" 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	Заголовки	Описание
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-Bytes и 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-Account-Meta-Quota-Bytes — максимальный допустимый объём хранимых данных (в байтах)	Устанавливает для указанного аккаунта ограничение, переданное в заголовке X-Account-Meta-Quota-Bytes

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

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

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

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

Формат URL⁠​

Доступ к API⁠​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

X-Delete-At⁠​

X-Delete-After⁠​

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

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

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

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

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

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

Просмотр заголовков конкретного объекта⁠​

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

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

Формат URL⁠

Доступ к API⁠

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

X-Delete-At⁠

X-Delete-After⁠

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

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

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

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

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

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

Просмотр заголовков конкретного объекта⁠

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

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