Облачное хранилище: новые функции API
![Тирекс](https://selectel.ru/blog/wp-content/uploads/2023/05/T-Rex_Autor-3-400x400.png)
Недавно мы рассказали о переходе на новую платформу, благодаря которой нам удалось улучшить работу облачного хранилища. Мы подробно описали, как мы доработали логику и архитектуру хранилища и переписали некоторые компоненты на Go, благодаря чему всё стало работать гораздо быстрее и стабильнее, чем раньше. При этом мы рассказали далеко не обо всём: зЗа время работы над новым API мы запустили несколько новых функций, которые, как мы надеемся, окажутся полезными для вас. В этой статье мы подробно расскажем обо всех нововведениях.
![Изображение записи](https://selectel.ru/blog/wp-content/uploads/2016/07/PR-2495_preview.png)
Недавно мы рассказали о переходе на новую платформу, благодаря которой нам удалось улучшить работу облачного хранилища. Мы подробно описали, как мы доработали логику и архитектуру хранилища и переписали некоторые компоненты на Go, благодаря чему всё стало работать гораздо быстрее и стабильнее, чем раньше.
При этом мы рассказали далеко не обо всём: за время работы над API мы запустили несколько новых функций, которые, как мы надеемся, окажутся полезными для вас.
Аутентификация
Наше хранилище полностью поддерживает OpenStack Swift API, для которого существует множество сторонних клиентов.
Для совместимости с этими клиентами реализована поддержка аутентификации Swift v1, а также ограниченно реализованы варианты аутентификации Keystone v2 и v3. Таким образом, в нашем API теперь доступны три способа аутентификации.
Первый почти не отличается от того, что использовался раньше (изменился только URI авторизации для большего соответствия стандарту):
$ curl -i https://api.selcdn.ru/auth/v1.0 -H "X-Auth-User:[имя пользователя]" -H "X-Auth-Key:[пароль]
Во втором способе (аутентификации по типу Keystone v2) используется не GET-, а POST-запрос; имя пользователя и пароль передаются в массиве JSON:
$ curl -i -X POST https://api.selcdn.ru/v2.0/tokens -H 'Content-type: application/json' -d '{"auth": {"passwordCredentials": {"username": [имя пользователя], "password": [пароль]}}}'
Ответ на такой запрос API также вернёт в формате JSON.
Аутентификация согласно Keysone v3 выглядит так:
$ curl -i https://api.selcdn.ru/v3/auth/tokens -XPOST -d '{"auth": { "identity": { "methods": ["password"], "password": { "user": { "id": [имя пользователя], "password": [пароль]}}}}}'
Обращаем ваше внимание на то, что Keystone API в хранилище реализован не полностью: работают только функции аутентификации по логину и паролю. Никакие расширения протокола Keystone у нас не поддерживаются.
Изменился также и базовый адрес хранилища. Теперь он выглядит так: http://api.selcdn.ru/v1/SEL_XXX (вместо ХХХ нужно, естественно, подставить ID пользователя).
Еще одним изменением, связанным с системой аутентификации, является новый механизм временных токенов. Появилась возможность генерировать дополнительные токены с ограниченным сроком действия, обеспечивающие доступ только в строго определённый контейнер. Чем-то это напоминает Security Service в Amazon S3:
$ curl -i -X GET https://api.selcdn.ru/v1/temptokens -H "X-Auth-Token: [токен основного пользователя]" -H "X-Container:[контейнер]" -H "X-ExpireAfter: 8600"
В заголовке X-Auth-Token передается валидный токен основного пользователя, в X-Container указывается контейнер, для которого будет действовать токен, а в X-Expire-After — время действия этого токена в секундах.
Работа с файлами
В новом API расширены возможности работы с файлами. Так, архивы в форматах tar, .tar.gz, gzip можно распаковывать в фоновом режиме после полной загрузки файла в хранилище. Предыдущий вариант распаковки предполагал распаковку архивов «на лету», т.е. нужно было поддерживать соединение с нашими серверами, пока не выполнятся запросы на создание всех файлов из загружаемого архива. И при разрыве соединения приходилось всё загружать заново.
Теперь всё гораздо проще. Если вам, например, требуется загрузить в хранилище архив, содержащий несколько тысяч файлов, это можно сделать с помощью PUT-запроса на адрес контейнера с дополнительным query-параметром extract-archive-v2. После полной отправки архива сразу же отдаётся код 201 и запускается фоновая распаковка на стороне хранилища:
curl -i -X PUT https://api.selcdn.ru/v1/SEL_XXX/[имя контейнера]/?extract-archive-v2=tar.bz2' -H "X-Auth-Token: [токен]" -T "photos.tar.bz2"
HTTP/1.1 100 Continue
HTTP/1.1 201 Created
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Length: 0
Content-Type: text/html
Etag: a1adb438cb26e91228870158a2062ef2
Extract-Id: 6a62579d-9ee2-2a32-26a4-207d5a47af2a
Обратите внимание на заголовок Extract-Id, присутствующий в ответе. С его помощью можно узнать, на какой стадии находится операция распаковки:
$ curl -i https://api.selcdn.ru/v1/extract-archive/[Extract-Id] -H "X-Auth-Token: [токен]"
HTTP/1.1 200 OK
Number Files Created: 1185
Response Body:
Response Status: 201 Created
Errors:
В нашем случае ответ с кодом 200 означает, что операция распаковки была завершена успешно. В параметре Number Files Created указывается количество файлов, извлечённых из архива.
Новые функции
В API появилось много новых функций, в частности управление пользователями, доменами, сертификатами и работа с CDN. Подробнее о них мы расскажем ниже.
Управление пользователями
Раньше добавлять и удалять дополнительных пользователей можно было исключительно через панель управления. Сейчас это можно делать посредством стандартных HTTP-запросов к API.
Посмотреть список пользователей можно так:
$ curl -i -XGET https://api.selcd.ru/v1/users[?format=json] -H "X-Auth-Token: [токен]"
Создание нового пользователя осуществляется с помощью запроса:
$ curl -i -XPUT https://api.selcd.ru/v1/users/new_user -H "X-Auth-Token: [токен]" -H "X-Auth-Key: 123456" -H "X-User-ACL-Containers-W: container1, container2, container3" -H "X-User-ACL-Containers-R: container4" -H "X-User-Store-Password: yes" -H "X-User-Active: on"
К нам уже не раз поступали просьбы расширить управление правами для пользователей. Эти просьбы мы выполнили, и это видно из только что приведённого примера запроса: обратите внимание на заголовки X-User-ACL-Containers-W и X-User-ACL-Containers-R. В первом указываются контейнеры, в которые новый пользователь может записывать информацию, а во втором — контейнеры, доступ к которым будет открыт только для чтения.
В заголовке X-Auth-Key указывается пароль создаваемого пользователя. X-User-Store-Password является эквивалентом опции «Хранить пароль на серверах Selectel» в панели управления. Заголовок X-User-Active со значением on указывает, что новый пользователь будет активен.
Изменить данные уже созданного пользователя можно так:
$ curl -i -XPOST https://api.selcd.ru/v1/users/new_user -H "X-Auth-Token: [токен]" -H "X-Auth-Key: 123456" -H "X-User-ACL-Containers-W: container1, container4" -H "X-User-ACL-Containers-R: container4" -H "X-User-Store-Password: yes" -H "X-User-Active: on"
Удаление пользователя осуществляется с помощью DELETE-запроса:
$ curl -i -XDELETE https://selcdn.ru/users/[имя пользователя] -H "X-Auth-Token: [токен]"
Для основного пользователя можно изменять только пароль. Это делается с помощью POST-запроса с заголовком X-Auth-Key на адрес https://api.selcd.ru/v1/users/[имя основного пользователя].
Управление доменами
Работать с доменами раньше тоже можно было исключительно через графический интерфейс. Сейчас все операции можно выполнять и через API.
Вот так, например, можно просмотреть список всех доменов, привязанных к контейнерам:
$ curl -i https://api.selcdn.ru/v1/domains -H "X-Auth-Token: [токен]"
Прикрепить домен можно с помощью POST-запроса к соответствующему контейнеру с заголовком X-Add-Container-Domains:
$ curl -i https://api.selcdn.ru/v1/SEL_XXX/{container_name} -XPOST -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: [токен]"
Для удаления домена используется аналогичный запрос, только имя домена передаётся в заголовке X-Remove-Container-Domains:
$ curl -i https://api.selcdn.ru/v1/SEL_XXX/{container_name} -XPOST -H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: [токен]"
Чтобы полностью изменить список привязанных к контейнеру доменов, нужно выполнить POSТ-запрос на адрес этого контейнера и передать обновленный список в заголовке X-Container-Domains:
$ curl -i https://api.selcdn.ru/SEL_XXX/[имя контейнера] -H "X-Auth-Token: [токен]" -XPOST -H "X-Сontainer-Domains: domain1.ru domain2.ru"
Если к контейнеру прикреплены несколько доменов и их требуется удалить, то в заголовке X-Container-Domains можно просто передать цифру 0:
$ curl -i https://ххххх.selcdn.ru/[имя контейнера] -H "X-Auth-Token: [токен]" -XPOST -H "X-Сontainer-Domains: 0"
Запрос логов
Через API можно запрашивать логи сетевого доступа к пользовательским контейнерам за указанный период:
$ curl -i -XPOST https://api.selcdn.ru/v1/logs -H "X-Auth-Token: [токен]" -H "X-Start-Time: 2016-02-02 09:00:00" -H "X-End-Time: 2016-05-02 12:00:00" -H “X-Limit: 10000”
В заголовках X-Start-Time и X-End-Time, как не трудно догадаться, указываются начало и конец периода.
В факультативном заголовке X-Limit указывается максимальное количество записей логов, которые будут выданы в данном запросе (по умолчанию вы получите все логи за указанный временной интервал).
По завершении выборки в хранилище будет автоматически создан приватный контейнер logs, куда и будут помещены логи.
Управление SSL-сертификатами
Ещё одна новая функция — управление SSL-сертификатами. Работать с сертификатами можно как через графический интерфейс, так и через API.
Вот так, например, можно просмотреть список всех сертификатов, привязанных к контейнерам:
$ curl -i https://api.selcdn.ru/v1/ssl -XGET -H "X-Auth-Token: [токен]"
Для просмотра информации о сертификате используется запрос вида:
$ curl -i https://api.selcdn.ru/v1/ssl/{cert_name} -XGET -H "X-Auth-Token: [токен]"
Запрос на добавление сертификата выглядит так:
$ curl -i https://api.selcdn.ru/v1/ssl/{cert_name} -XPUT -H "X-Auth-Token: [токен]"
Имя сертификата ({cert_name}) передаётся в формате 001_cert1, где число — логин пользователя, а второй компонент — произвольное имя. Имена сертификатов не могут дублировать друг друга. Сам сертификат и приватный ключ передаются в теле запроса в виде одного файла.
Чтобы удалить сертификат, нужно отправить DELETE-запрос вида:
$ curl -I https://api.selcdn.ru/v1/ssl/001_cert1 -H "X-Auth-Token: [токен]" -XDELETE
Работа с CDN
Появилась в API и возможность работы с CDN. Вы можете отправлять запросы на очистку кэша (раньше это можно было делать только через графический интерфейс), а также просматривать статус выполнения этих запросов.
Очистка кэша CDN осуществляется при помощи PURGE-запроса:
$ curl -i -X PURGE https://api.selcdn.ru/v1/cdn -H "X-Auth-Token: [токен]" -d 'https://api.selcdn.ru/v1/SEL_XXX/container1/file1\nhttps://XXX.selcdn.ru/container1/file1'
Сейчас мы используем akamai ccu v3 с fast purge, и после отправки такого запроса кэш должен быть очищен в течение примерно 5 секунд. Ответ на запрос выглядит так:
{"estimatedSeconds": 5, "purgeId": "0bb4d6fa-4ce4-11e6-b75e-9fdde8cfe544", "supportId": "17PY1468845301403318-210404544", "httpStatus": 201, "detail": "Request accepted"}
Заключение
В этой статье мы рассказали о новых функциях API облачного хранилища. В скором времени работа по усовершенствованию хранилища будет продолжена. И если у вас есть свои пожеланию по улучшению и расширению функциональности — высказывайтесь в комментариях к этому посту. Наиболее интересные идеи мы примем к сведению и постараемся реализовать.