Swift API (old)
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;
- иметь достаточную сумму на балансе Хранилища и CDN;
- иметь логин и пароль для доступа к хранилищу;
- получить уникальный ключ доступа (токен), который будет передаваться во всех запросах.
Авторизация и получение токена
В этом разделе описаны способы авторизации и получения токена для работы с 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 | 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