Selectel Storage (old)
Это старая версия Selectel Storage API, которая использовалась до обновления объектного хранилища 29.09.2023. URL и методы старой версии Selectel Storage API пока продолжают поддерживаться, но в будущем будут отключены. Мы рекомендуем использовать новую версию Selectel Storage API.
Объектное хранилище предоставляет разработчикам возможность интеграции с собственными приложениями и сайтами. Взаимодействие с хранилищем организовано на базе REST API. В документации описаны доступные на текущий момент вызовы REST API Storage, форматы запросов и ответов. На текущий момент с помощью запросов к REST API можно выполнять следующие операции:
- создавать ссылки, по которым сторонние пользователи могут загружать файлы в хранилище;
- работать с версиями файлов;
- создавать пользователей и задавать для них настройки доступа к хранилищу;
- скачивать и распаковывать архивы;
- работать со специальными страницами и т.д.
Способы авторизации и получения токена для работы с API описаны в разделе Авторизация и получение токена инструкции Swift API (old).
Ограничения для дополнительных пользователей
Дополнительные пользователи имеют ограничения при использовании API, поэтому следующие действия необходимо выполнять от имени основного пользователя Объектного хранилища:
- создание контейнера;
- удаление нескольких файлов (с помощью
?bulk-delete=true
); - создание или изменение пользователей;
- работа с доменами и пользовательскими SSL-сертификатами;
- сброс кэша CDN;
- получение логов;
- создание временных токенов (
/temptokens
).
Операции с контейнерами
Создание галереи изображений
Параметры запроса
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container -H "X-Auth-Token: $token" -H "X-Container-Metatype: gallery"
В случае удачного выполнения запроса API возвращает ответ с кодом 204.
Пример ответа
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:
Скачивание контейнера в виде zip-архива
Содержимое любого контейнера можно скачать в виде zip-архива. Для этого к ссылке на контейнер нужно добавить query-параметр download-all-as-zip=[имя архива], например:
wget https://api.selcdn.ru/v1/SEL_*****/container_name/?download-all-as-zip=container_name.zip
В публичных контейнерах функционал скачивания zip-архива отключен по умолчанию, чтобы его включить надо установить заголовок X-Container-Meta-Allow-ZipDownload: true, пример:
curl -i -XPUT https://api.selcdn.ru/v1/SEL_***/container_name -H "X-Auth-Token: $token" -H "X-Container-Meta-Allow-ZipDownload: true"
Значение этого заголовка X-Container-Meta-Allow-ZipDownload в приватных контейнерах игнорируется.
Для скачивания содержимого любого публичного контейнера в виде zip-архива могут быть использованы следующие команды:
curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -o name.zip
Для скачивания содержимого любого приватного контейнера в виде zip-архива могут быть использованы следующие команды:
curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
Для просмотра содержимого скачанного архива используйте команду:
unzip -l name.zip
Archive: name.zip
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway)
Length Date Time Name
--------- ---------- ----- ----
555436 1980-00-00 00:00 IMG_20180802_121146.jpg
39 1980-00-00 00:00 copied_file
245473 1980-00-00 00:00 mergetree.pdf
--------- -------
800948 3 files
Описываемая операция предназначена в первую очередь для упрощения скачивания, а не для э кономии трафика, поэтому файлы в архиве не сжимаются.
Количество объектов в одном контейнере не должно превышать 10 000, иначе команда не сработает и вернет ошибку.
Можно скачивать объекты, начинающиеся на один заданный префикс (например, IMG), в виде zip-архива, указав данный префикс IMG в параметре IMG?download-all-as-zip:
curl -i -XGET https://*****.selcdn.ru/container/?IMG?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
Примечание: если среди объектов будет папка, начинающаяся на этот же префикс, то будет скачана и она вместе со всем содержимым.
Скачивание папки в виде zip-архива
Содержимое любой папки можно скачать в виде zip-архива. Для этого к ссылке на папку нужно добавить query-параметр download-all-as-zip=[имя архива], например:
wget https://api.selcdn.ru/v1/SEL_*****/container_name/folder/?download-all-as-zip=container_name.zip
Для скачивания содержимого любой папки в виде zip-архива могут быть использованы следующие команды:
curl -i -XGET https://*****.selcdn.ru/container/folder?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
Для просмотра содержимого скачанного архива используйте команду:
unzip -l name.zip
Archive: name.zip
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway)
Length Date Time Name
--------- ---------- ----- ----
555436 1980-00-00 00:00 IMG_20180802_121146.jpg
39 1980-00-00 00:00 copied_file
245473 1980-00-00 00:00 mergetree.pdf
--------- -------
800948 3 files
Описываемая операция предназначена в первую очередь для упрощения скачивания, а не для экономии трафика, поэтому файлы в архиве не сжимаются.
Количество объектов в одной папке не должно превышать 10 000, иначе команда не сработает и вернет ошибку.
Работа с файлами
Распаковка архивов
Архивы в формате *.tar, *.tar.gz и *.gzip могут быть распакованы сразу после загрузки в хранилище. Чтобы распаковать архив, в запрос на загрузку файла нужно добавить query-параметр extract-archive:
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/archive.tar.gz/?extract-archive=tar.gz \
-H "X-Auth-Token: $token" -T "archive.tar.gz"
Создание символической ссылки на файл
При использовании хранилища в качестве бэкенда для публичных сервисов нередко возникает необходимость разграничить доступ к файлам --- например, сделать доступными для широкого круга пользователей файлы, помещённые в приватный контейнер.
Специально для таких случаев в хранилище предусмотрена возможность создавать символические ссылки. Такие ссылки можно защищать паролем, а также устанавливать для них срок действия.
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/new_link \
-H "X-Auth-Token: $token" -H "Content-Type: x-storage/symlink" \
-H "X-Object-Meta-Location: /new_container/new_object" \
-H "X-Object-Meta-Link-Key: $key" -H "Content-Length: 0"
Пример ответа
HTTP/1.1 201 Created
> etag: d41d8cd98f00b204e9800998ecf8427e
> Last-Modified: Mon, 27 May 2013 13:34:34 GM
Пример генерации X-Object-Meta-Link-Key на Python
import hashlib
# location of file, always with container specified
location = "/container/object"
# password
password = "12345"
# concatenate password + location and encode it
encoded_pass_loc = (password + location).encode('utf-8')
# generate sha1-hash
hash_object = hashlib.sha1(encoded_pass_loc)
# convert sha1-hash to hexadecimal digits
link_key = hash_object.hexdigest()
# show calculated value
print(link_key)
Создание ссылки для скачивания файла
Можно создавать специальные ссылки, по которым сторонние пользователи могут скачать ваши файлы (в том числе и из личных контейнеров). Для создания такой ссылки не нужно выполнять запрос к API. Прежде чем генерировать ссылки на файлы аккаунта, нужно самостоятельно установить секретный ключ $key:
curl -i -XPOST http://*****.selcdn.ru/ -H "X-Auth-Token: $token" -H "X-Account-Meta-Temp-URL-Key: $key"
Для создания ссылки на конкретный контейнер, установите секретный ключ $key, добавив имя контейнера:
curl -i -XPOST http://*****.selcdn.ru/сontainer -H "X-Auth-Token: $token" -H "X-Container-Meta-Temp-URL-Key: $key"
Доступ к файлам по сгенерированной ссылке смогут получить только пользователи, которым известен секретный ключ.
Пример на Python
import hmac
from hashlib import sha1
from time import time
# access method (always GET)
method = "GET"
# reference valid 60 seconds
expires = int(time()) + 60
# the path to the file in the repository, always with the container specified
path = "/container/dir/file"
# secret key
link_secret_key = str.encode("$key")
# generate access key
hmac_body = str.encode('%s\n%s\n%s' % (method, expires, path))
# access key
sig = hmac.new(link_secret_key, hmac_body, sha1).hexdigest()
#show calculated values
print(sig,expires)
При использовании ссылки вида https://api.selcdn.ru/v1/SEL_***/container_name/object_name
в вышеприведённом скрипте переменная path должна иметь вид /v1/SEL_***/container_name/object_name
.
Полученный в результате ключ затем нужно будет указать в ссылке:
http://****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=13909142
где:
*****.selcdn.ru
--- базовый домен;temp_url_sig
--- ключ дост упа;temp_url_expires
--- время, до которого действует ссылка (unixtime).
Если к контейнеру прикреплен домен, то его можно указать в ссылке. Имя контейнера при этом указывать не нужно:
http://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
Поддерживается управление заголовком Content-Disposition для отдаваемых по ссылке данных. Для этого нужно добавить параметр filename с соответствующим значением:
http://*****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc
Секретный ключ можно изменить. После изменения секретного ключа все сгенерированные ранее ссылки перестанут работать.
Пример на Node.js
const crypto = require('crypto');
// access method (always GET)
const method = 'GET';
// reference valid 60 seconds
const expires = Math.floor(Date.now() / 1000) + 60;
// the path to the file in the repository, always with the container specified
const path = '/container/dir/file';
// secret key
const linkSecretKey = '$key';
// generate access key
const hmacBody = `${method}\n${expires}\n${path}`;
// access key
const sig = crypto.createHmac('sha1', linkSecretKey).update(hmacBody).digest('hex');
// show calculated values
console.log(sig);
console.log(expires);
Создание ссылки для загрузки файлов (sendmefile)
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container/upload \
-H "X-Auth-Token: $token" -H "Content-Type: x-storage/sendmefile+inplace" \
-H "X-Object-Meta-Sendmefile-Max-Size: 52428800" \
-H "X-Delete-After: 14400" \
-H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68" \
-d "Поя снительный текст для страницы загрузки"
Версионирование
Чтобы хранить не только последнюю версию объекта, но и несколько предыдущих, в хранилище предусмотрена поддержка версий.
Перед началом работы с версионированием создайте контейнер для хранения версий.
При удалении объекта на его место не возвращается последняя рабочая версия. Все версии объекта, в том числе та, что была перед удалением, хранятся в контейнере для версий.
Параметры запроса
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container1/ -H "X-Auth-Token: $token" -H "X-Versions-Location: container2"
При удачном выполнении запроса будет возвращён ответ с кодом 202.
Пример ответа
HTTP/1.1 202 Accepted Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: * Access-Control-Expose-Headers: Expires: 0 Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate
Специальные страницы
К специальным страницам относятся:
- индексная страница, отдаваемая в ответ на анонимный GET-запрос на контейнер или папку, помещенную в этот контейнер;
- страница ошибки (404) --- файл, отдаваемые при анонимном GET-запросе к несуществующему объекту.
Индексная страница
Параметры запроса
В запросе можно указывать как абсолютный, так и относительный путь к файлу.
Пример запроса
Создайте индексный файл:
echo "<html>custom_index_file</html>" > my_index.html
curl -i -XPUT "https://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" -H "X-Auth-Token: $token" -T "./my_index.html"
Для задания индексной страницы установите значение Web-Index для контейнера:
curl -i -XPUT "https://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" \
-H "X-Auth-Token: $token" -H "X-Container-Meta-Web-Index:/my_index.html"
Страница 404
Параметры запроса
Примеры
Доступные шаблонные параметры
Чтобы передавать информацию об изначально запрашиваемом файле, можно использовать специальные шаблонные параметры:
- {container} --- имя контейнера;
- {path} --- путь к запрошенному файлу относительно контейнера.
По умолчанию переадресация выполняется с кодом 307. Доступные варианты: 200, 307, 404. При установке внешней ссылки доступно задание только кода 307.
Пример запроса
Установите значение Web-404-Page для контейнера:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}"
При анонимном запросе на несуществующий объект происходит перенаправление на указанный файл:
curl -i "https://api.selcdn.ru/v1/SEL_*****/container_name/non_existing_object" \
> HTTP/1.1 307 Temporary Redirect
> Location: https://api.selcdn.ru/v1/SEL_*****/404.html?file=non_existing_object
По умолчанию при отправке страницы ошибки возвращается код 404:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}?{code}"
Листинг файлов
Параметры запроса
Пример запроса
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings: on"
Для получения листинга файлов анонимным запросом введите:
curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Web-Mode: listing"
Для получения листинга приватного контейнера укажите токен пользователя, имеющего доступ к контейнеру:
curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" -H "X-Web-Mode: listing"
Для выводов в HTML-формате можно задавать оформление с помощью заголовка X-Container-Meta-Web-Listings-Css, в качестве значения которого указывается ссылка на файл стилей в контейнере; можно также дать ссылку на внешний файл стилей.
Устанавливаем значение Web-Listings-CSS для контейнера:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings-Css: my_style.css"
Управление пользователями
Просмотр списка пользователей
Параметры запроса
Пример запроса
curl -i https://api.selcdn.ru/v1/users -H "X-Auth-Token: $token"
В случае удачного выполнения запроса API вернёт ответ с кодом 200.
Пример ответа
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
Content-Length: 80
main_user (true)
main_user (true)
user1 (true)
user2 (true)
user3 (true)
Добавление нового пользователя
Параметры запроса
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/users/my_test_user
-H "X-Auth-Token: $token"
-H "X-Auth-Key: $key"
-H "X-User-ACL-Containers-W: container1, container2, container3"
-H "X-User-ACL-Containers-R: container4"
-H "X-User-S3-Password: yes"
-H "X-User-Active: on"
При удачном выполнении запроса API возвращает ответ с кодом 204.
Пример ответа
HTTP/2 204 Created
access-control-allow-origin: *
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Удаление пользователя
Параметры запроса
Пример запроса
curl -i -X DELETE https://api.selcdn.ru/v1/users/my_test_user -H "X-Auth-Token: $token"
В случае успешного удаления пользователя API возвращает ответ с кодом 204.
Пример ответа
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:04:25 GMT
Изменение пароля основного пользователя
Параметры запроса
Пример запроса
curl -i -XPOST https://api.selcdn.ru/v1/users -H "X-Auth-Token: $token" -H "X-Auth-Key: $key"
При удачном выполнении запроса API возвращает ответ с кодом 204.
Пример ответа
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:30:59 GMT
Управление доменами
К контейнерам в хранилище можно прикреплять домены. Все операции с доменами осуществляются через API.
Домены по умолчанию
Каждый пользователь объектного хранилища автоматически получает набор доменов по умолчанию, которые можно использовать для доступа к объектам в любых контейнерах:
- *****.selcdn.ru --- домен для публичного доступа к файлам в хранилище;
- *****.selcdn.com --- домен для раздачи файлов через CDN по http.
Получение списка прикреплённых доменов
Параметры запроса
Пример запроса
curl -i -XGET https://api.selcdn.ru/v1/domains -H "X-Auth-Token: $token"
При удачном выполнении запроса API возвращает ответ с кодом 200.
Пример ответа
HTTP/1.1 200 OK
Content-Length: 69
Content-Type: text/html
Date: Mon, 16 May 2016 07:36:35 GMT
Base Domains:
00000.selcdn.ru
00000.selcdn.com
Containers Domains:
container1 domain1.ru
container2 domain1.ru
Прикрепление домена
Параметры запроса
Пример запроса
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"
В случае удачного выполнения запроса API вернёт ответ с кодом 204.
Пример ответа
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Tue, 20 Mar 2018 12:09:38 GMT
Удаление домена
Параметры запроса
Пример запроса
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: $token
В случае удачного выполнения запроса API возвращает ответ с кодом 204.
Пример ответа
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Редактирование списка доменов
Параметры запроса
Пример запроса
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"
В случае удачного выполнения запроса API возвращает ответ с кодом 204.
Пример ответа
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Управление пользовательскими SSL-сертификатами
Получение списка сертификатов
Параметры запроса
Пример запроса
curl -i -XGET https://api.selcdn.ru/v1/ssl -H "X-Auth-Token: $token"
Получение информации о сертификате
Параметры запроса
Пример запроса
curl -i -XGET https://api.selcdn.ru/v1/ssl/cert -H "X-Auth-Token: $token"
Добавление сертификата
Параметры запроса
Пример запроса
curl -i -XPUT https://api.selcdn.ru/v1/ssl/*****_cert1 -H "X-Auth-Token: $token" -T ./cert1.pem
Имя сертификата ({cert_name}) нужно передавать в формате *****_cert1, где первая часть (цифры) представляет собой номер учётной записи пользователя, а вторая — любую произвольную комбинацию символов.
Имена сертификатов должны быть уникальными; загрузить два сертификата с одинаковыми им енами невозможно.
Сам сертификат и приватный ключ нужно передать в теле запроса в одном файле.
Удаление сертификата
Параметры запроса
Очистка кэша хранилища
Параметры запроса:
- Тип запроса --- POST;
- URI ---
https://api.selcdn.ru/v1/storage/purge
; - Заголовки --- токен авторизации X-Auth-Token;
- Описание --- очищает кэш Объектного хранилища для страниц, адреса которых переданы в запросе.
Пример запроса:
curl -i -XPOST https://api.selcdn.ru/v1/storage/purge -H "x-auth-token: $token" -d '{"objects":["https://example.domain.ru/test_purge/file","https://example2.domain.ru/test_purge/file2"]}'
При удачном выполнении запроса API вернёт ответ с кодом 200.
Пример ответа:
HTTP/2 200
content-type: application/json
date: Fri, 27 Aug 2021 13:00:42 GMT
content-length: 66
{"HttpStatus":201,"Detail":"Request accepted.","RejectedUrls":{}}
Получение логов
Запрос на создание выгрузки
Параметры запроса
Тело запроса:
{
"since": "2019-05-14T06:00:00",
"till": "2019-12-09T13:43:00",
"fields": [
"container_name"
],
"filters": {
"host": [
"example.com",
"foo.bar.baz"
]
},
"container": "logs",
"delete_after": 3600
}
Описание полей тела запроса:
- since --- начало периода для вы грузки;
- till --- конец периода для выгрузки;
- fields --- список необходимых полей;
- filters --- фильтры для выгрузки;
- container --- контейнер для выгрузки;
- delete_after --- удаление объектов с логами через заданное время.
Список возможных полей (fields):
- container_name
- timestamp
- host
- server_to_client_bytes
- client_to_server_bytes
- http_method
- status
- path
- query
- client_ip
Список возможных фильтров (filters):
- host
- container_name
Пример запроса
curl -i -XPOST -H 'X-Auth-Token: $token' -d '{"since": "2019-05-14T06:00:00","till": "2019-12-09T13:43:00", "fields": ["container_name"], "filters": {"host": ["example.com", "foo.bar.baz"]}, "container": "logs", "delete_after": 3600}' 'https://api.selcdn.ru/v1/logs'