API облачного хранилища

• Что такое REST API
• Как использовать API
• Функции REST API
  • Аутентификация
• Временные токены
  • Получение временных токенов
  • Автоматическая распаковка архивов в фоновом режиме
• Функции хранилища
  • Получение информации об аккаунте
• Параметры ответа
  • Получение списка контейнеров
• Создание нового контейнера
• Получение информации о контейнере
• Изменение метаданных контейнера 
• Удаление контейнера
• Создание галереи изображений
• Получение списка файлов в контейнере
• Загрузка файла из контейнера
• Загрузка файла в контейнер
• Установка срока хранения для файлов
  • Распаковка архивов
  • Установка метаданных файла
• Копирование файлов в хранилище
• Удаление файла
• Создание символической ссылки на файл
• Создание ссылки для скачивания файлов
• Скачивание контейнера или папки в виде zip-архива
• Создание ссылки для загрузки файла в хранилище (sendmefile)
• Установка лимитов
  • Для отдельного контейнера
  • Для учётной записи в целом
• Версионирование
• Поддержка больших объектов
• Управление пользователями
• Просмотр списка пользователей
• Создание нового пользователя
• Удаление пользователя
• Управление доменами
• Удаление домена
• Управление пользовательскими SSL-сертификатами
• Сброс кэша CDN
• Получение логов
• Получение статуса фоновой распаковки архивов

В панели управления перейдите в раздел Облачное хранилище.

Данная услуга пока доступна только в предыдущей версии панели управления, поэтому для работы с Облачным хранилищем перейдите по ссылке в текущей версии панели.

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

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

Взаимодействие с API осуществляется посредством стандартных HTTP-запросов.

Что такое REST API

REST API определяет набор функций, к которым можно делать запросы и получать ответы.   Взаимодействие осуществляется по протоколу HTTP, что даёт возможность обращаться к API практически из любого языка программирования.  Хранилище поддерживает OpenStack API, и вы всегда можете воспользоваться соответствующими библиотеками.

Как использовать API

Все методы вызовов API представляют собой HTTP-запросы к URL вида {+}https://xxxxx.selcdn.ru+, содержащие определенные наборы параметров.  Чтобы осуществить вызов к API, вам нужно выбрать в документации нужный метод, сформировать запрос в соответствии с описанием этого метода и выполнить его.  В ответ на запрос вы получите некий результат; все типовые ответы на запросы подробно описаны ниже.
Также в документации описаны типовые ошибки, которые могут иметь место при выполнении запросов.

Функции REST API

Аутентификация

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

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

$ curl -i {+}https://api.selcdn.ru/auth/v1.0+ -H "X-Auth-User:[имя пользователя]" -H "X-Auth-Key:[пароль]

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

HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Storage-Token: ec01a5f65efa70234bba6d86187173d5
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 76134
X-Auth-Token: ec01a5f65efa70234bba6d86187173d5
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_22302+
Date: Wed, 04 May 2016 11:55:32 GMT

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

 
Возможные ошибки

Также в хранилище поддерживается аутентификация по протоколу v2.0  и  v3.
Пример запроса на авторизацию по v2.0

$ curl -i -X POST {+}https://api.selcdn.ru/v2.0/tokens+ -H 'Content-type: application/json' -d '{"auth": {"passwordCredentials": {"username": "22302", "password": "5JFH6Jk1"}}}'
HTTP/1.1 200 OK
Content-Length: 423
Content-Type: application/json
Date: Thu, 19 May 2016 07:17:08 GMT
 
{"access":{"token":{"id":"49a049462d6943d55b2ccc85abd5fdae","expires":"2016-05-20T13:12:45\n","tenant":{"id":"22302","name":"22302"}},"user":{"id":"22302","name":"22302","roles":[]},"serviceCatalog":[{"endpoints":[{"region":"common","adminURL":"https://api.selcdn.ru/v1/SEL_22302","internalURL":"https://api.selcdn.ru/v1/SEL_22302","publicURL":"https://api.selcdn.ru/v1/SEL_22302"}],"type":"object-store","name":"swift"}]}}

Пример запроса на авторизацию по v3

$ curl -i  {+}https://api.selcdn.ru/v3/auth/tokens+ -XPOST -d '{"auth": { "identity": { "methods": ["password"], "password": { "user": { "id": "43371", "password": "QyjaoXLh"}}}}}'
HTTP/1.1 200 OK
Content-Length: 807
Content-Type: application/json

X-Subject-Token: 614ed749fba45aa218d1ba68c7c83411
Date: Fri, 20 May 2016 12:56:36 GMT

{"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_43371","region":"RegionOne","interface":"public"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_43371","region":"RegionOne","interface":"admin"},{"id":"614ed749fba45aa218d1ba68c7c83411","region_id":"RegionOne","url":"https://api.selcdn.ru/v1/SEL_43371","region":"RegionOne","interface":"internal"}],"type":"object-store","name":"swift","id":""}],"user":{"id":"614ed749fba45aa218d1ba68c7c83411","name":"43371","domain":{"id":"default","name":"Default","links":{}}},"audit_ids":[""]}}

Как видно из приведённого примера, токен передаётся в ответе в заголовке X-Auth-Token.

Временные токены

В хранилище имеется возможность создания временных токенов, с помощью которых пользователи смогут получать доступ к строго определённым контейнерам.
Срок действия таких токенов ограничен и может варьироваться от нескольких минут до нескольких часов. По истечении этого срока токен становится недействительным, а пользователь лишается доступа к контейнеру и не может осуществлять никаких операций через API. 

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

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

$ curl -i {+}https://api.selcdn.ru/v1/temptokens+ -H "X-Auth-Token: $token" -H "X-Container: container_name" -H "X-ExpireAfter: $term"

В случае удачного выполнения запроса будет возвращён ответ с кодом 204 No Content. Временный токен будет возвращен в заголовке X-Auth-Token.

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

HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Auth-Token: bd1bcd683fc0dfa050fa0ab2185445te
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 6000
X-Storage-Token:  bd1bcd683fc0dfa050fa0ab2185445te
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_+...
Date: Fri, 20 May 2016 13:43:39 GMT

Получение временных токенов

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

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

$ curl -i {+}https://api.selcdn.ru/v1/temptokens+ -H "X-Auth-Token: 49a049462d6943d55b2ccc85abd5fdae" -H "X-Container: container1" -H "X-ExpireAfter: 8600"

HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Auth-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 60
X-Storage-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_43371+
Date: Fri, 20 May 2016 13:02:00 GMT

Автоматическая распаковка архивов в фоновом режиме

Архивы в форматах .tar, .tar.gz, gzip можно автоматически распаковывать после полной загрузки архива в хранилище, в фоновом режиме.  Для этого используется PUT-запрос на адрес контейнера с дополнительным query-параметром extract-archive-v2.

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

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

curl -i -X PUT {storage_url}/{container_name}/?extract-archive-v2=tar.bz2' -H "X-Auth-Token: $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

Функции хранилища

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

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

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

$ curl -I {storage_url} -H "X-Auth-Token:$token"

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

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: c5zzs2wa
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: text/plain; charset=utf-8
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

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

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

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

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

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

$ curl -i -X GET '{storage_url}?format=json' -H "X-Auth-Token:$token"

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

HTTP/1.1 200 OK
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: c53zs23аa
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
Content-Length: 300
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

[{"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}]

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

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

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

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

$ curl -i -XPUT {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Type: public"

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

HTTP/1.1 201 Created
Content-Length: 0
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

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

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

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

$ curl -I {storage_url}/{container_name} -H "X-Auth-Token: $token"

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

HTTP/1.1 200 OK
Content-Length: 113
X-Backend-Timestamp: 1445521364.51371
X-Container-Object-Count: 8
Accept-Ranges: bytes
X-Backend-Put-Timestamp: 1445521637.35495
X-Storage-Policy: Policy-0
X-Container-Bytes-Used: 2455570
X-Backend-Delete-Timestamp: 0000000000.00000
X-Container-Meta-Type: gallery
X-Timestamp: 1445521364.51371
X-Backend-Storage-Policy-Index: 0
Content-Type: text/plain; charset=utf-8
X-Backend-Status-Changed-At: 1445521364.56786
X-Container-Domains:
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, X-Container-Object-Count, X-Backend-Put-Timestamp, X-Storage-Policy, X-Container-Bytes-Used, X-Backend-Delete-Timestamp, X-Container-Meta-Type, X-Timestamp, X-Backend-Storage-Policy-Index, X-Backend-Status-Changed-At, X-Container-Domains

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

Изменение метаданных контейнера 

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

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

curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token"  -H "X-Container-Meta-Type: private" -H "X-Container-Meta-Some: any text"

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

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Если какие-то метаданные требуется удалить, их можно указать в качестве значения заголовка X-Remove-Container-Meta-Some:

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

curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token"  -H "X-Container-Meta-Type: private" -H "X-Remove-Container-Meta-Some: any text"

Коды ошибок

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

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

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

$ curl -i {storage_url}/new/ -X DELETE -H "X-Auth-Token:$token"

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

HTTP/1.1 204 No Content
content-length: 0
content-type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

Коды ошибок

Создание галереи изображений

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

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

curl -i -XPUT {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Type: gallery"

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

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:

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

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

 
В запросе также могут содержаться дополнительные query-параметры:

• limit - устанавливает максимальное количество объектов в списке (может принимать значения от 1 до 10000);
• marker - делать выборку начиная с указанного объекта;
• prefix - включает в список объекты, у которых имена начинаются с указанного префикса;
• path - возвращает список объектов в отдельной виртуальной папке;
• delimiter - вернуть объекты до указанного символа разделителя в имени;
• format - задаёт формат списка (json или xml).

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

curl -i {storage_url}/{container_name}/?format=json  -H "X-Auth-Token: $toKen"

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

HTTP/1.1 200 OK
X-Container-Object-Count: 3
Accept-Ranges: bytes
X-Container-Meta-Type: gallery
X-Timestamp: 1395042799.81374
X-Container-Bytes-Used: 925740
Content-Type: application/json; charset=utf-8
X-Container-Domains:
Content-Length: 559
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Container-Object-Count, X-Container-Meta-Type, X-Timestamp, X-Container-Bytes-Used, X-Container-Domains

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

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

curl -O {storage_url}/images/image1.png

Заголовок X-Auth-Token обязателен при загрузке файлов из приавтного контейнера; с публичными контейнерами его можно не использовать.
В запрос можно включать стандартные HTTP-заголовки, описанные в RFC2616:

• If-Match;
• If-None-Match;
• If-Modified-Since;
• If-Unmodified-Since.

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

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

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

$ curl -i -XPUT {storage_url}/new_container/new_object \    -H "X-Auth-Token: $ \    -H "X-Delete-After: 100" \    -T "./example.gz"

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

> HTTP/1.1 100 Continue > HTTP/1.1 201 Created > etag: 0f343b0931126a20f133d67c2b018a3b > Last-Modified: Wed, 29 Oct 2014 12:24:37 GMT

Установка срока хранения для файлов

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

$ curl -i -XPOST {storage_url}/{container_name} \        -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \        -H "X-Container-Meta-Default-Delete-After: 1209600"

В приведённом примере мы указываем, что все, загружаемые в контейнер файлы будут храниться 1209600 секунд, т.е. 14 дней.  По истечении этого срока они будут автоматически удаляться.

Распаковка архивов

Архивы в форматах .tar, .tar.gz, gzip можно автоматически распаковывать после загрузки в хранилище.  Для этого используется PUT-запрос на адрес контейнера с дополнительным query-параметром extract-archive.

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

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

curl -i -X PUT {storage_url}/{container_name}/?extract-archive=tar.bz2'        -H "X-Auth-Token: $toKen" -T "photos.tar.bz2"

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

{"Response Status": "201 Created", "Response Body": "", "Errors": [], "Number Files Created": 1237}

Установка метаданных файла

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

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

$ curl -i -XPOST {storage_url}/new_container/new_object  -H 
"X-Auth-Token: "$token"  -H "X-Object-Meta-Some: another"

Копирование файлов в хранилище

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

Способ 1

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

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

$ сurl -i -X PUT {storage_url}/{container_name}/first_copy -H "X-Auth-Token:$token" -H "X-Copy-From: /{container_name/new_object"

Способ 2

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

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

$ curl -i -X COPY {storage_url}/{container_name}/{file} \    -H "X-Auth-Token: $token" \    -H "Destination: /new_container/second_copy"

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

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 2013 06:30:51 GMT

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

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

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

$ curl -i -X DELETE {storage_url}/{container_name}/{file} -H "X-Auth-Token: $toKeN"

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

HTTP/1.1 204 No Content

Создание символической ссылки на файл

При использовании хранилища в качестве бэкенда для публичных сервисов нередко возникает необходимость разграничить доступ к файлам — например, сделать доступными для широкого круга пользователей файлы, помещённые в приватный контейнер.
Специально для таких случаев в хранилище предусмотрена возможность создавать символические ссылки. Такие ссылки можно защищать паролем, а также устанавливать для них срок действия.

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

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

curl -i -XPUT {storage_url}/{container_name}/{link}  -H "X-Auth-Token: $token" -H "Content-Type: x-storage/symlink" -H "X-Object-Meta-Location: /{container_name}/{file}"  -H "X-Object-Meta-Link-Key: b6589fc6ab0dc82cf12099d1c2d40ab994e8410c" -H "Content-Length: 0"

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

HTTP/1.1 201 Created etag: d41d8cd98f00b204e9800998ecf8427e Last-Modified: Mon, 27 May 2013 13:34:34 GMT

Создание ссылки для скачивания файлов

С помощью этой функции вы сможете создавать ссылки, по которым ваши файлы (в том числе и из приватных контейнеров)  может скачать любой сторонний пользователь.
Прежде чем генерировать ссылки, нужно установить секретный ключ. Ключ можно устанавливать как на уровне пользователя, так и на уровне контейнера. Секретный ключ, заданный для аккаунта, позволяет создавать ссылки на все файлы во всех контейнерах. Для установки такого глобального ключа следует выполнить авторизованный POST-запрос с заголовком X-Account-Meta-Temp-URL-Key. Если требуется дать доступ на создание ссылок только в одном определенном контейнере, следует отправить на адрес контейнера POST-запрос с заголовком X-Container-Meta-Temp-URL-Key. Здесь нужно иметь в виду, что запрос на установку пользовательского ключа следует выполнять от основного пользователя, подпользователи не имеют прав изменять глобальные настройки аккаунта. Пример запроса установки секретного ключа аккаунта:

$ curl -i -XPOST {storage_url} -H "X-Auth-Token: $token" -H "X-Account-Meta-Temp-URL-Key: $key"

Доступ  к файлам по сгенерированной ссылке смогут получить только пользователи, которым этот ключ известен.
Можно передать список ip-адресов с которых ссылка будет доступна. Это заголовки X-Account-Meta-Temp-URL-Ips и X-Container-Meta-Temp-URL-Ips.
Список необходимо разделять запятыми, без пробелов между адресами:

$ curl -i -XPOST {+}https://xxx.selcdn.ru/container1+ -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"  -H "X-Container-Meta-Temp-URL-Ips: x.x.x.x,y.y.y.y"

Пример на Python

import hmac from hashlib import sha1 from time import time # данные для генерации ссылки method = "GET"  # метод доступа expires = int(time()) + 60  # срок действия ссылки (60 секунд) path = "/container/dir/file"  # полный путь к файлу в хранилище
link_secret_key = "secret_word"  # секретный ключ # генерация ключа доступа hmac_body = '%s\n%s\n%s' % (method, expires, path) sig = hmac.new(link_secret_key, hmac_body, sha1).hexdigest()  # ключ доступа
print expires, sig

Полученный в результате ключ указывается в ссылке:

{storage_url}/container/dir/file?temp_url_sig=$sig&temp_url_expires=$expires

где:

• {storage_url} - базовый домен;
• temp_url_sig - ключ доступа;
• temp_url_expires - время, до которого действует ссылка (unixtime).

Если к контейнеру прикреплен домен, то его можно указать в ссылке. Имя контейнера при этом указывать не нужно:

{+}https://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227+

Поддерживается управление заголовком Content-Disposition для отдаваемых по ссылке данных.  Для этого нужно добавить параметр inline без значения, либо filename со значением в виде имени файла:

{storage_url}/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc 

Секретный ключ можно изменить, но все сгенерированные ранее ссылки после этого перестанут работать.

Скачивание контейнера или папки в виде zip-архива

Содержимое любого контейнера или папки можно скачать из хранилища в виде zip-архива. Скачивание в виде zip-архива может быть использовано только для публичных контейнеров и для контейнеров-галерей.
Чтобы скачать содержимое контейнера в виде  zip-архива, нужно к соответствующей ссылке добавить query-параметр download-all-as-zip=[имя архива], например, скачать все файлы из контейнера, в том числе файлы в папках и подпапках:

$ wget '{storage_url}/{container_name}/?download-all-as-zip=arch.zip'

Скачивать файлы в виде zip-архива могут и неавторизованные пользователи (за исключением случаев, если скачиваемый файл или галерея защищены паролем).

Внимание! Файлы в архиве не сжимаются: описываемая функция предназначена для упрощения скачивания, а не для экономии трафика.При выполнении запроса в архив будут включены только первые 10 000 файлов из контейнера или папки.  Все остальные файлы добавлены не будут.

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

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

• Cache-Control;
• Expires;
• Origin;
• Access-Control-Allow-Origin;
• Access-Control-Max-Age;
• Access-Control-Allow-Methods;
• Access-Control-Allow-Credentials;
• Access-Control-Expose-Headers;
• Access-Control-Request-Headers;
• Access-Control-Request-Method;
• Content-Disposition (только для конечного файла);
• Strict-Transport-Security (только на уровне контейнера).

Заголовки устанавливаются на уровне контейнера. Значения заголовков устанавливаются в виде метаданных:

$ curl -i -XPOST {+}https://xxx.selcdn.ru/new_container+ \    -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \    -H "X-Container-Meta-Access-Control-Request-Method: HEAD, GET" \    -H "X-Container-Meta-Cache-Control: public" \    -H "X-Container-Meta-Strict-Transport-Security: max-age=31536000; includeSubDomains"

Аналогичным образом (в виде метаданных X-Container-Meta-[header]) устанавливаются значения и для других заголовков.

Создание ссылки для загрузки файла в хранилище (sendmefile)

C помощью функции под кодовым названием sendmefile вы можете создать ссылку, по которой сторонние пользователи (даже не имеющие учётной записи в хранилище) смогут загрузить собственные файлы в ваши контейнеры и папки.  Эта функция может оказаться полезной для решения самых разных задач: загрузка пользовательского контента на сайты, организация обмена файлами между пользователями сайта или приложения, быстрое сохранение резервных копий и т.п.
Чтобы создать ссылку на загрузку файлов, нужно отправить PUT-запрос на адрес {storage_url}/{container_name}/upload.

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

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

$ curl -i -XPUT {storage_url}/container/upload  -H "X-Auth-Token: $token"    -H "Content-Type: x-storage/sendmefile"     -H "X-Object-Meta-Sendmefile-Max-Size: 52428800"  -H "X-Object-Meta-Sendmefile-Expire: 14400"    -H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8" -d "Пояснительный текст для страницы загрузки"

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

Специальные страницы

Облачное хранилище часто используется в качестве площадки для размещения статических сайтов. Для этого варианта использования в API предусмотрено несколько полезных функций. Одной из них является настройка так называемых специальных страниц.  К специальным страница веб-сайтов относятся:

• индексная страница, отдаваемая в ответ на анонимный GET-запросе на контейнер или папку, помещённую в этот контейнер;
• страница ошибки (404) - файл, отдаваемые при анонимном GET-запросе к несуществующему объекту;
• страница со списком файлов, выдаваемый в ответ на анонимный GET-запрос на этот контейнер.

Индексная страница

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

 
В запросе можно указывать как абсолютный, так и относительный путь к файлу. 

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

Создаем индексный файл

$ echo "<html>custom_index_file</html>" > my_index.html # закачиваем его в хранилище $ curl -i -X PUT {storage_url}/{container_name}/my_index.html \    -H "X-Auth-Token: $token" \    -T "./my_index.html" > HTTP/1.1 100 Continue > HTTP/1.1 201 Created > etag: b302ffc3b75770453e96c1348e30eb93 > Last-Modified: Mon, 27 May 2013 14:42:04 GMT

Задать индексную страницу можно и другим способом, устанавливаем значение Web-Index для контейнера

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12" \    -H "X-Container-Meta-Web-Index: /my_index.html" > HTTP/1.1 204 No Content # при анонимном запросе получаем содержимое указанного файла $ curl -i {storage_url}/new_container/ > HTTP/1.1 200 OK > last-modified: Mon, 27 May 2013 14:27:57 GMT > etag: b302ffc3b75770453e96c1348e30eb93 > accept-ranges: bytes > Content-Length: 31 > Content-Type: text/html > access-control-request-method: HEAD, GET > > <html>custom_index_file</html>

Индексная страница 404

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

В качестве значения заголовка X-Container-Meta-Web-404-Redirect можно указать как файл внутри контейнера, так и внешнюю ссылку.

Примеры

Чтобы передавать информацию об изначально запрашиваемом файле, можно использовать специальные шаблонные параметры:

• {container} - имя контейнера;
• {path} - путь к файлу относительно контейнера.

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

Устанавливаем значение Web-404-Redirect для контейнера: 

$ curl -i -XPOST {storage_url}/{container_name} -H "X-Auth-Token: $token" -H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}" > HTTP/1.1 204 No Content #

При анонимном запросе на не существующий объект получаем редирект на указанный файл.

$ curl -i {storage_url}/{container_name}/non_existing_object > HTTP/1.1 307 Temporary Redirect > Location: {+}http://xxx.selcdn.ru/404.html?file=non_existing_object+

По умолчанию, при отправке страницы ошибки возвращается код 404.  Можно указать и другой код ответа: 200 или 307.

$ curl -i -XPOST {storage_url}/new_container -H "X-Auth-Token: $token" -H "X-Container-Meta-Web-404-Redirect: /404.html?file={path}?{code}"

Вместо {code} следует указать нужный код.

Листинг файлов

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

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

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: $token" \    -H "X-Container-Meta-Web-Listings: on" > HTTP/1.1 204 No Content #

Получаем листинг файлов анонимным запросом: 

$ curl -i {storage_url}/{container_name}/ \    -H "X-Web-Mode: listing"

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

HTTP/1.1 200 OK > Content-Type: application/json; charset=UTF-8 > X-Container-Object-Count: 4 > > <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "{+}http://www.w3.org/TR/html4/loose.dtd+"> > <html> > ... > </html>

Для выводов в HTML-формате можно задавать оформление с помощью заголовка X-Container-Meta-Web-Listings-Css, в качестве значения которого указывается ссылка на файл стилей в контейнере; можно также дать ссылку на внешний файл стилей.

Пример

Устанавливаем значение Web-Listings-CSS для контейнера:

$ curl -i -XPOST {storage_url}/{container_name} \    -H "X-Auth-Token: $token" \    -H "X-Container-Meta-Web-Listings-Css: /my_style.css" > HTTP/1.1 204 No Content 

Установка лимитов

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

Для отдельного контейнера

Чтобы установить лимиты для контейнера, нужно отправить на адрес этого контейнера POST-запрос и указать в соответствующих заголовках лимит по числу объектов  или по объёму иформации в байтах:

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

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

$ curl -i -XPOST {storage_url}/{container_name}  -H "X-Auth-Token: $token"   -H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

Для учётной записи в целом

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

$ curl -i -XPOST {storage_url}/{container_name}  -H "X-Auth-Token: $token"   -H "X-Container-Meta-Quota-Bytes: 52428800" -H "X-Container-Meta-Quota-Count: 1000"

Версионирование

Как правило, электронный документ за время своего существования претерпевает многочисленные изменения. Довольно часто возникает необходимость хранить не только последнюю версию документа, но и несколько предыдущих. Для этого в хранилище предусмотрена поддержка версий.
Тип запроса: PUT /{storage_url}/{containe_namer}.

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

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

$ curl -i -X PUT -H "X-Auth-Token: $token" -H "X-Versions-Location: $container" {storage_url}/{container_name}

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

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

Отключение версионирования осуществляется путем отправки POST-запроса с заголовком X-Remove-Versions-Location на адрес контейнера. В данном заголовке может быть произвольное содержимое.

Тип запроса: POST /{storage_url}/{container_name}.

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

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

$ curl -i -X PUT -H "X-Auth-Token: $token" -H "X-Remove-Versions-Location: x" {storage_url}/{container_name}

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

В хранилище имеются ограничения на размер загружаемого объекта: он не должен превышать 20 ГБ.  Однако вы можете помещать в хранилище объекты практически любого размера, используя технику сегментации.

Существует две техники загрузки больших объектов: динамическая и статическая.

При динамической загрузке объект разбивается на сегменты, после чего создаётся так называемый манифест — пустой файл, содержащий указатель на контейнер, куда загружены все сегменты, в заголовке X-Object-Manifest.

Желательно сначала загружать сегменты, а уже потом — создавать или обновлять манифест: объект в этом случае не будет доступен для скачивания, пока не завершится загрузка всех сегментов.

Пример

Загружаем сегменты:

curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000001 --data-binary '1' curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000002 --data-binary '2' curl -X PUT -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}/00000003 --data-binary '3' #

Создаём манифест:

curl -X PUT -H 'X-Auth-Token: $token' \    -H 'X-Object-Manifest: container/myobject/' \    {storage_url}/{container_name}/{object_name} --data-binary '' #

Теперь все сегменты можно скачивать как целостный объект.

curl -H 'X-Auth-Token: $token' \    {storage_url}/{container_name}/{object_name}

При статической загрузке нужно создать статический манифест с указанием путей до сегментов, их контрольной суммы (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.

Управление пользователями

В хранилище имеется возможность гибкого разграничения доступа к контейнерам.  Она может оказаться полезной в ситуациях, когда требуется настроить взаимодействие хранилища со сторонними приложениями или просто организовать безопасный обмен файлами между несколькими пользователями.
По умолчанию после регистрации в хранилище вы получаете статус основного пользователя, который имеет доступ ко всем контейнерам и папкам.  Вы можете также создавать дополнительных пользователей, которые будут иметь доступ только к строго определённым объектам. Это можно делать как через графический интерфейс панели управления, так и через API. Особенности управления пользователями через API будут описаны ниже.

Просмотр списка пользователей

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

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

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

$ curl -i {+}https://api.selcdn.ru/v1/users?format=json+  -H "X-Auth-Token: $token"

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 580

[{"active": true, "acl_containers_w": [], "password_plain": "5216Kr1", "name": "user1", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2"], "password_plain": "OPEa222oR5", "name": "user2", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2", "container1", "container4", "container5"], "password_plain": "GIoIRFBKe", "name": "user3", "acl_containers_r": []}, {"active": true, "acl_containers_w": ["container1", "container2", "container3"], "password_plain": "poIT5fae", "name": "user6", "acl_containers_r": ["container2"]}]

Создание нового пользователя

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

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

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

curl -i -XPUT {storage_url}/users/{username} -H "X-Auth-Token: $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"

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

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 0

Изменение пароля основного пользователя

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

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

curl -i -XPOST {storage_url}/v1/users -H "X-Auth-Token: $token" -H "X-Auth-Key: 123456" -H "X-User-Store-Password: yes"

Удаление пользователя

$ curl -i -XDELETE {+}https://selcdn.ru/users/1+ -H "X-Auth-Token: 285a05936fe0817beac78e84ad2c5f12"

Управление доменами

В хранилище имеется возможность прикрепления к контейнерам доменов. Все операции с доменами можно осуществлять через API.

Получение списка доменов

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

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

curl -i {+}https://api.selcdn.ru/domains+ -H "X-Auth-Token:  $token"

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

HTTP/1.1 200 OK
Content-Length: 69
Content-Type: text/html
Date: Mon, 16 May 2016 07:36:35 GMT

Base Domains:
77218.selcdn.ru
77218.selcdn.com
Containers Domains:
container1  domain1.ru
container2  domain1.ru

Прикрепление домена

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

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

$ curl -i {storage_url}/{container_name} -XPOST -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

Удаление домена

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

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

$ curl -i {storage_url}/{container_name} -XPOST -H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"

Изменение списка доменов, привязанных к контейнеру

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

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

$ curl -i https://ххххх.selcdn.ru/{container_name} -H "X-Auth-Token:$token" -XPOST -H "X-Сontainer-Domains: domain1.rudomain2.ru"

В результате выполнения этой команды все домены, прикреплённые к контейнеру, будут заменены на переданные в заголовке X-Container-Domains.

Если к контейнеру прикреплены несколько доменов, и их требуется удалить, в заголовке X-Container-Domains нужно передать цифру 0:

$ curl -i https://ххххх.selcdn.ru/{container_name} -H "X-Auth-Token:$token" -XPOST -H "X-Сontainer-Domains: 0"

Управление пользовательскими SSL-сертификатами

Просмотр списка сертификатов

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

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

$ curl -i {+}https://api.selcdn.ru/v1/ssl+ -H "X-Auth-Token:$token" -XGET

Просмотр информации о сертификате

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

$ curl -i https://api.selcdn.ru/v1/ssl/\{cert_name} -H "X-Auth-Token:$token" -XGET

Добавление сертификата

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

Имя сертификата ({cert_name}) нужно передавать в формате 001_cert1, где число — логин пользователя, а второй компонент — произвольное имя.  Имена сертификатов не могут дублировать друг друга. Сам сертификат и приватный ключ передаются в теле запроса в виде одного файла.

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

$ curl -I {+}https://api.selcdn.ru/v1/ssl/001_cert1+ -H "X-Auth-Token:$token" -XPUT -T ./cert1.pem

Удаление сертификата

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

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

$ curl -I {+}https://api.selcdn.ru/v1/ssl/001_cert1+ -H "X-Auth-Token:$token" -XDELETE

Сброс кэша CDN

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

В теле запроса нужно перечислить полные адреса страниц (каждый на новой строчке) для которых нужно очистить кэш. В теле запроса передаются адреса страниц, для которых требуется очистить кэш.  В заголовке Content-Length (см. выше) передаётся размер тела запроса.

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

$ curl -i -X PURGE {+}https://api.selcdn.ru/v1/cdn+ -H "X-Auth-Token: $token" -d $'https://ххххх.selcdn.com/container1/file1' 

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

HTTP/1.1 200 OK
Date: Mon, 16 May 2016 09:45:15 GMT
Content-Length: 268
Content-Type: text/plain; charset=utf-8

{"estimatedSeconds": 5, "progressUri": "/ccu/v2/purges/e4561042-1b4a-11e6-9024-f3cf5304c77a", "purgeId": "e4561042-1b4a-11e6-9024-f3cf5304c77a", "supportId": "17PY1463391915374207-348128448", "httpStatus": 201, "detail": "Request accepted.", "pingAfterSeconds": 300}

Внимание! Очистка кэша CDN осуществляется примерно через 5 секунд после выполнения запроса.

Получение логов

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

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

$ curl -i -XPOST {+}https://api.selcdn.ru/v1/logs+ -H "X-Auth-Token: 49a049462d6943d55b2ccc85abd5fdae" -H "X-Start-Time: 2016-02-02 09:00:00" -H "X-End-Time: 2016-05-02 12:00:00" 

По завершении выборки файл с логами будет сохранён в приватном контейнере logs.

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

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

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

$ curl -i {+}https://api.selcdn.ru/v1/extract-archive/+6a62579d-9ee2-2a32-26a4-207d5a47af2a -H "X-Auth-Token: 49a049462d6943d55b2ccc85abd5fdae"
 
HTTP/1.1 204 No Content
Content-Type: text/plain; charset=utf-8
X-Auth-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Content-Type-Options: nosniff
X-Expire-Auth-Token: 60
X-Storage-Token: 6565c8eb14cba25afe290132f08a1d1b
X-Storage-Url: {+}https://api.selcdn.ru/v1/SEL_43371+
Date: Fri, 20 May 2016 13:02:00 GMT