Openstack 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 https://developer.openstack.org/api-ref/object-store/.

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

curl -i -XGET "https://api.selcdn.ru/auth/v1.0" -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 -XPOST https://api.selcdn.ru/v3/auth/tokens -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 — метаданные контейнера;
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 Заголовки Описание
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 Заголовки Описание
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/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

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

В хранилище нет ограничений на размер загружаемых файлов. Однако файлы размером более 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 Заголовки Описание
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