Swift API

Авторизация в Swift API происходит с помощью токена Keystone (для проекта), который передается в каждом запросе в заголовке X-Auth-Token.

Адрес (URL) можно посмотреть в списке URL.

Пример запроса для просмотра списка контейнеров в проекте аккаунта:

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>'

Укажите:

• <keystone_token> — токен Keystone;
• <pool> — пул, в котором находится объектное хранилище (например, ru-1), подробнее в подразделе Домены Swift API инструкции Домены;
• <project_id> — идентификатор проекта. Посмотреть идентификатор можно в панели управления в разделе Объектное хранилище → меню проектов → Управление проектами. Идентификатор указан под названием проекта.

Получить информацию о хранилище

Возвращает метаданные с информацией о количестве и объеме хранения контейнеров и объектов.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>'

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

В случае успеха запрос возвращает ответ с кодом 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-Meta-<...>: anyheader
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6

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

Получить информацию о хранилище и список контейнеров

Возвращает информацию о хранилище и список контейнеров.

Один запрос выводит список, который может содержать до 10 000 контейнеров. Если контейнеров больше, используйте дополнительные запросы с query-параметром marker.

Чтобы получить дополнительную информацию о контейнерах (размер, дату обновления и т. д.), используйте query-параметр ?format=json.

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

curl \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>'

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

container1
container2
container3

Управлять метаданными хранилища

Устанавливает, заменяет или удаляет метаданные, переданные в заголовке из запроса.

Заголовки запроса

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

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Account-Meta-<...>: anyheader' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>'

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

В случае успеха запрос возвращает ответ с кодом 204.

Получить метаданные контейнера

Выводит метаданные контейнера, включая количество объектов, объем хранения (в байтах) и заголовки контейнера.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае успеха запрос возвращает ответ с кодом 204.

Получить список объектов и метаданных контейнера

Возвращает метаданные контейнера и выводит список объектов.

Один запрос выводит список, который может содержать до 10 000 объектов. Если объектов больше, используйте дополнительные запросы с query-параметрами marker и limit.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае успеха запрос возвращает ответ с кодом 200 или 204.

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/plain
X-Container-Bytes-Used: 0
X-Container-Meta-Quota-Bytes: 52428800
X-Container-Meta-Quota-Count: 1000
X-Container-Meta-Type: public
X-Container-Object-Count: 1
X-Container-Storage-Policy-Index: 0
X-Container-Storage-Policy-Name: Policy-0
X-Openstack-Request-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Storage-Policy: Policy-0
X-Timestamp: 1688648194.11923
X-Trans-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Versions-Enabled: true
Date: Thu, 13 Jul 2023 15:13:53 GMT
Content-Length: 120

Object1
Object2
Object3

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

Создать контейнер

Создает контейнер с параметрами, указанными в запросе.

Заголовки запроса

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

curl -i -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Container-Meta-Type: public' \
-H 'X-Container-Meta-<...>: anyheader' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае успеха запрос возвращает ответ с кодом 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6

Управлять метаданными контейнера

Устанавливает, заменяет или удаляет метаданные, переданные в заголовке из запроса.

Заголовки запроса

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

Изменение типа контейнера:

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Container-Meta-Type: private' \
-H 'X-Versions-Enabled: true' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае успеха запрос возвращает ответ с кодом 204.

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

Удаляет контейнер в хранилище. Перед удалением контейнера удалите в нем все объекты.

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

curl -i -XDELETE \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае успеха запрос возвращает ответ с кодом 204.

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: Text/html; charset=UTF-8

Получить объект

Выведет тело и заголовки объекта.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

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

В случае успеха запрос возвращает ответ с кодом 200.

Загрузить объект

Загружает объект в контейнер. Такая загрузка используется для объектов размером до 100 МБ. Для объектов большего размера используйте сегментированную загрузку.

При использовании заголовка X-Copy-From можно загрузить в контейнер скопированный объект. Объект копируется вместе с заголовком X-Delete-At независимо от того, куда был установлен заголовок (на объект или контейнер).

Заголовки запроса

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

Загрузка объекта:

curl -i -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Delete-After: 180' \
-d "<object-body>" \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

Укажите:

• <object-body> — тело объекта;
• <object_name> — имя, которое будет присвоено объекту.

Копирование объекта:

curl -i -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Copy-From: /<container_name_1>/<object_name_1>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name_2>/<object_name_2>'

Укажите:

• <container_name_2> — контейнер, в который скопируется объект;
• <object_name_2> — имя, с которым скопируется объект;
• <container_name_1> — контейнер, в котором находится копируемый объект;
• <object_name_1> — объект, который нужно скопировать.

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

При загрузке в случае успеха объекта запрос возвращает ответ с кодом 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: b65ad34618e410d9d8bf624d61f8a980
Date: Thu, 15 Mar 2023 07:31:32 GMT

При копировании объекта в случае успеха запрос возвращает ответ с кодом 201.

HTTP/1.1 201
Created etag: 0f343b0931126a20f133d67c2b018a3b
X-Copied-From: container_name_1/object_name_1
X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
Last-Modified: Tue, 28 May 2018 06:30:51 GMT

Удалить несколько объектов

Удалит несколько объектов одновременно, в том числе объекты из разных контейнеров. Объекты удаляются последовательно.

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

Удаление объектов из разных контейнеров:

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'Content-Type: text/plain' \
-d $'<container_name_1>/<object_name_1>\n<container_name_2>/<object_name_2>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>?bulk-delete=true&format=json'

Укажите:

• <container_name_1>/<object_name_1> — путь до объекта в первом контейнере;
• <container_name_2>/<object_name_2> — путь до объекта во втором контейнере;
• \n — перенос строки, необходимо указывать между объектами.

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

В случае успеха запрос возвращает ответ с кодом 200.

HTTP/1.1 200 OK
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}

Управлять HTTP-заголовками и метаданными объектов

Устанавливает значения для указанных в запросе пользовательских и HTTP-заголовков. Заголовки используются для управления кэшированием на стороне клиента и промежуточных прокси-серверах.

Поддерживаемые HTTP-заголовки:

• Cache-Control
• Content-Encoding
• Content-Type
• Content-Disposition
• Link

Заголовки запроса

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

Добавление заголовка Link к объекту:

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'Link: rel=canonical' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

Добавление пользовательского заголовка:

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Object-Meta-Some: metadata' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

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

Запрос на добавление заголовка Link в случае успеха возвращает ответ с кодом 202.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

Запрос на добавление пользовательского заголовка в случае успеха возвращает ответ с кодом 201.

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: d41d8cd98f00b204e9800998ecf8427e

Копировать объект

Объект будет скопирован в другой контейнер или по другому префиксу. Если для заголовка X-Fresh-Metadata установить значение true, то при копировании новый объект будет создан с новыми заголовками, в том числе без X-Delete-At.

Заголовки запроса

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

curl -i -XCOPY \
-H 'X-Auth-Token: <keystone_token>' \
-H 'Destination: /<container_name_2>/<object_name_2>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name_1>/<object_name_1>'

Укажите:

• <container_name_1> — контейнер, в котором находится копируемый объект;
• <object_name_1> — объект, который нужно скопировать.
• <container_name_2> — контейнер, в который скопируется объект;
• <object_name_2> — имя, с которым скопируется объект.

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

В случае успеха запрос возвращает ответ с кодом 201.

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

Удалить объект

Объект будет удален из контейнера.

Для удаления сегментированного объекта используйте query-параметром ?multipart-manifest=delete — будут удалены сегменты объекта и манифест.

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

curl -i -XDELETE \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

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

В случае успеха запрос возвращает ответ с кодом 204.

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

Заголовки для отложенного удаления

Заголовки указываются при отправке запросов PUT и POST и определяют, когда объект будет автоматически удален из хранилища.

Если указаны оба заголовка, приоритетным будет заголовок X-Delete-After.

Особенности работы заголовков:

• если объект загружается с помощью PUT-запроса и заголовком X-Delete-At, а у контейнера модифицированный заголовок, заголовок объекта будет перезаписан на заголовок контейнера;
• если в контейнере включено версионирование, заголовки X-Delete-At и X-Delete-After не переносятся на созданную версию. Загруженная версия удалена не будет, но объект пропадет из списка.

В хранилище нет ограничений на размер загружаемых объектов, но объекты размером более 100 МБ не рекомендуется помещать в хранилище целиком — нужно разбивать объект на сегменты, загружать каждый сегмент объекта и файл манифеста, объединяющий все сегменты объекта (технология DLO/SLO). Подробнее о загрузке сегментированных объектов в инструкции документации Загрузить объект.

При использовании сегментированной загрузки можно загружать два типа больших объектов:

• динамические (DLO), при загрузке манифеста динамического объекта необходимо указать контейнер и префикс сегментов. Вы можно загружать и удалять отдельные сегменты без необходимости менять файл манифеста;
• статические (SLO), при загрузке манифеста статического объекта указывается путь до каждого сегмента, из которых состоит объект. При каждом изменении сегментов необходимо редактировать и загружать заново файл манифеста. Опционально для сегментов можно указать их контрольные суммы (Etag) и размер.

Чтобы получить файл манифеста, выполните GET-запрос с query-параметром ?multipart-manifest=get.

Удалить все сегменты и объект с манифестом можно с помощью DELETE-запроса с query-параметром ?multipart-manifest=delete.

Загрузить сегменты объекта

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

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

curl -i -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-d "hello " \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>/00000001'

curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-d "world" \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>/00000002'

curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-d "!" \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>/00000003'

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

В случае успеха запросы возвращают ответы с кодом 201.

Загрузить манифест динамического объекта

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

curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Object-Manifest: <container_name>/<object_name>/' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>'

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

В случае успеха запрос возвращает ответ с кодом 201.

Загрузить манифест статического объекта

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

В теле манифеста статического объекта укажите путь до каждого сегмента объекта.

curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Static-Large-Object: True' \
"[{"path": "/<container_name>/<object_name>/00000001"}, {"path": "/<container_name>/<object_name>/00000002"}, {"path": "/<container_name>/<object_name>/00000003"} ...]" \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>?multipart-manifest=put'

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

В случае успеха запрос возвращает ответ с кодом 201.

Установить лимиты на контейнер

Устанавливает на контейнер ограничения, переданные в заголовках X-Container-Meta-Quota-Bytes и X-Container-Meta-Quota-Count.

Заголовки запроса

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

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Container-Meta-Quota-Bytes: 52428800' \
-H 'X-Container-Meta-Quota-Count: 1000' \
-H 'X-Container-Meta-Default-Delete-After: 300' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>'

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

В случае удачного выполнения запроса будет возвращен ответ с кодом 202.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

Установить лимиты на проект

Устанавливает на проект ограничение, переданное в заголовке X-Account-Meta-Quota-Bytes.

Заголовки запроса

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

curl -i -XPOST \
-H 'X-Auth-Token: <keystone_token>' \
-H 'X-Account-Meta-Quota-Bytes: 52428800' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>'

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

В случае удачного выполнения запроса будет возвращен ответ с кодом 202.

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html

В запросе на получение списка контейнеров или объектов можно использовать дополнительные query-параметры.

format

Вернет список объектов в определенном формате.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?format=json'

Список объектов будет возвращен в формате JSON.

limit

Задаст точное количество объектов, которые будут включены в список (например, при работе с контейнерами, где хранится большое количество объектов).

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?limit=20'

В список будут включены первые 20 объектов.

marker

Задаст объект, начиная с которого будет выведен список.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?marker=<object_name>'

В списке будут отображены объекты, которые следуют после объекта <object_name>.

prefix

Включит в список объекты, имена которых начинаются с указанной последовательности символов.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?prefix=my'

В списке будут отображены объекты, которые начинаются с символов my.

delimiter

Объектное хранилище имеет плоскую структуру и не поддерживает папки, но с помощью параметра delimiter можно вывести псевдоиерархию. Запрос с параметром выведет только ту часть имени объектов, которая следует до указанных символов, если он присутствует в выводе имени объекта.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?delimiter=/'

Будут выведены файлы и части префиксов (псевдопапки) на верхнем уровне:

photos/
videos/
file.jpg

Здесь:

• photos/, videos/ — части префиксов до символа /, которые есть у объектов в контейнере;
• file.jpg — файл без префикса (символа / в названии).

Параметр delimiter можно использовать совместно с параметром prefix, чтобы выводить список объектов и псевдопапок по указанному префиксу.

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

curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.<pool>.storage.selcloud.ru/v1/<project_id>/<container_name>?prefix=photos/&delimiter=/'

Пример вывода:

photos/animals/
photos/file.jpg

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

• с другой политикой хранения — например, получить доступ к объекту в контейнере с холодным хранением из контейнера со стандартным;
• с другим типом — например, получить доступ к объекту в приватном контейнере через символическую ссылку, размещенную в публичном контейнере.

Создать символическую ссылку можно с помощью пустого PUT-запроса на загрузку объекта с заголовком X-Symlink-Target: <container_name>/<object_name>.

По умолчанию символические ссылки динамические — они ссылаются на объект по его имени. Символическую ссылку можно сделать статической: при переходе по ссылке дополнительно проверяется Etag объекта. Для этого добавьте в запрос заголовок X-Symlink-Target-Etag: <etag>.

Если объект с ссылкой будет не пустой, запрос вернет ответ 400.

Чтобы получить объект с символической ссылкой, выполните GET или HEAD-запрос с параметром ?symlink=get.