Swift API
С помощью Swift API (API на базе OpenStack Object Storage API) вы можете работать с ресурсами объектного хранилища:
- просматривать информацию о количестве и объеме контейнеров и объектов в рамках аккаунта;
- создавать и удалять контейнеры;
- управлять лимитами контейнеров;
- загружать, просматривать, копировать, перемещать, скачивать и удалять объекты в контейнерах.
Для доступа к Swift API у пользователя должна быть роль с доступом к проекту в объектном хранилище, подробнее в инструкции документации Управлять доступом в объектном хранилище.
Авторизация в Swift API происходит с помощью токена Keystone (для проекта), который передается в каждом запросе в заголовке X-Auth-Token
.
Адрес (URL) можно посмотреть в списке URL.
Пример запроса для просмотра списка контейнеров в проекте аккаунта в пуле ru-1:
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>'
Укажите:
<keystone_token>
— токен Keystone;<project_id>
— идентификатор проекта. Посмотреть идентификатор можно в панели управления в разделе Объектное хранилище → меню проектов → Управление проектами. Идентификатор указан под названием проекта.
Получить информацию о хранилище
Возвращает метаданные с информацией о количестве и объеме хранения контейнеров и объектов.
Пример запроса
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.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.ru-1.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.ru-1.storage.selcloud.ru/v1/<project_id>'
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Получить метаданные контейнера
Выводит метаданные контейнера, включая количество объектов, объем хранения (в байтах) и заголовки контейнера.
Пример запроса
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>'
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Получить список объектов и метаданных контейнера
Возвращает метаданные контейнера и выводит список объектов.
Один запрос выводит список, который может содержать до 10 000 объектов. Если объектов больше, используйте дополнительные запросы с query-параметрами marker
и limit
.
Пример запроса
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.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.ru-1.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.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>'
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Удалить контейнер
Удаляет контейнер в хранилище. Перед удалением контейнера удалите в нем все объекты.
Пример запроса
curl -i -XDELETE \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>/00000001'
curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-d "world" \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>/<object_name>/00000002'
curl -XPUT \
-H 'X-Auth-Token: <keystone_token>' \
-d "!" \
'https://swift.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.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.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>?format=json'
Список объектов будет возвращен в формате JSON.
limit
Задаст точное количество объектов, которые будут включены в список (например, при работе с контейнерами, где хранится большое количество объектов).
Пример запроса:
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>?limit=20'
В список будут включены первые 20 объектов.
marker
Задаст объект, начиная с которого будет выведен список.
Пример запроса:
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>?marker=<object_name>'
В списке будут отображены объекты, которые следуют после объекта <object_name>
.
prefix
Включит в список объекты, имена которых начинаются с указанной последовательности символов.
Пример запроса:
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.storage.selcloud.ru/v1/<project_id>/<container_name>?prefix=my'
В списке будут отображены объекты, которые начинаются с символов my
.
delimiter
Объектное хранилище имеет плоскую структуру и не поддерживает папки, но с помощью параметра delimiter
можно вывести псевдоиерархию.
Запрос с параметром выведет только ту часть имени объектов, которая следует до указанных символов, если он присутствует в выводе имени объекта.
Пример запроса:
curl -i \
-H 'X-Auth-Token: <keystone_token>' \
'https://swift.ru-1.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.ru-1.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
.