Документация к API/Облачные услуги/Объектное хранилище/
Swift API
С помощью Swift API (API на базе OpenStack Object Storage API) вы можете работать с ресурсами объектного хранилища:
просматривать информацию о количестве и объеме контейнеров и объектов в рамках аккаунта;
создавать и удалять контейнеры;
управлять лимитами контейнеров;
загружать, просматривать, копировать, перемещать, скачивать и удалять объекты в контейнерах.
Для доступа к Swift API у пользователя должна быть роль с доступом к проекту в объектном хранилище, подробнее в инструкции документации Управлять доступом в объектном хранилище.
Авторизация
Авторизация в Swift API происходит с помощью токена Keystone, который передается в каждом запросе в заголовке X-Auth-Token. Токен должен быть выписан для проекта.
Адрес (URL): https://swift.ru-1.storage.selcloud.ru, где ru-1 — пул, в котором размещается объектное хранилище.
Пример запроса, который выведет список контейнеров в проекте аккаунта:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1/
Укажите:
— токен Keystone, выданный для проекта;
— идентификатор проекта. Посмотреть идентификатор можно в панели управления в разделе Объектное хранилище → меню проектов → Управление проектами. Идентификатор указан под названием проекта.
Хранилище
HEAD /v1/{project_id} Получение информации о хранилище
GET /v1/{project_id} Получение информации о хранилище и списка контейнеров
POST /v1/{project_id} Управление метаданными хранилища
Получить информацию о хранилище
Возвращает метаданные с информацией о количестве и объеме хранения контейнеров и объектов.
Пример запроса
curl -I -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1/
Пример ответа
В случае успеха запрос возвращает ответ с кодом 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
Параметры ответа
Параметр Значение
X-Account-Bytes-Used Суммарный объем хранимых данных (в байтах)
X-Account-Container-Count Количество контейнеров
X-Account-Meta-<...> Метаданные, где <...> — пользовательский заголовок
X-Account-Meta-Temp-Url-Key Секретный ключ, который используется для доступа к объектам в приватном контейнере через временный URL (при наличии)
X-Account-Object-Count Общее количество хранимых объектов
X-Account-Storage-Policy-Policy-0-Bytes-Used Суммарный объем хранимых данных по политике хранения, где Policy-0 — имя политики
X-Account-Storage-Policy-Policy-0-Container-Count Количество контейнеров, которые используют политику хранения, где Policy-0 — имя политики
X-Account-Storage-Policy-Policy-0-Object-Count Количество объектов, которые используют политику хранения, где Policy-0 — имя политики
X-Openstack-Request-Id
X-Trans-Id ID запроса
X-Timestamp Дата и время в UNIX-формате, когда был создан аккаунт, контейнер или объект
Date Дата и время отправки запроса
Получить информацию о хранилище и список контейнеров
Возвращает информацию о хранилище и список контейнеров.
Один запрос выводит список, который может содержать до 10 000 контейнеров. Если контейнеров больше, используйте дополнительные запросы с query-параметром marker.
Чтобы получить дополнительную информацию о контейнерах (размер, дату обновления и т. д.), используйте query-параметр ?format=json.
Пример запроса
curl -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1/
Пример ответа
container1
container2
container3
Управлять метаданными хранилища
Устанавливает, заменяет или удаляет метаданные, переданные в заголовке из запроса.
Заголовки запроса
Заголовок Описание
X-Account-Meta-<...> Метаданные хранилища, которые будут установлены, где <...> — пользовательский заголовок
X-Remove-Account-Meta-<...> Метаданные хранилища, которые требуется удалить, где <...> — пользовательский заголовок
Пример запроса
curl -i -XPOST \
-H 'X-Auth-Token: ' \
-H 'X-Account-Meta-<...>: anyheader' \
https://swift.ru-1.storage.selcloud.ru/v1/
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Контейнеры
HEAD /v1/{project_id}/{container_name} Получение метаданных контейнера
GET /v1/{project_id}/{container_name} Получение списка объектов и метаданных контейнера
PUT /v1/{project_id}/{container_name} Создание контейнера
POST /v1/{project_id}/{container_name} Управление метаданными контейнера
DELETE /v1/{project_id}/{container_name} Удаление контейнера
Получить метаданные контейнера
Выводит метаданные контейнера, включая количество объектов, объем хранения (в байтах) и заголовки контейнера.
Пример запроса
curl -I -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Получить список объектов и метаданных контейнера
Возвращает метаданные контейнера и выводит список объектов.
Один запрос выводит список, который может содержать до 10 000 объектов. Если объектов больше, используйте дополнительные запросы с параметрами marker и limit.
Пример запроса
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//
Пример ответа
В случае успеха запрос возвращает ответ с кодом 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
Параметры ответа
Параметр Значение
X-Container-Object-Count Количество объектов в контейнере
X-Container-Bytes-Used Объем объектов в контейнере (в байтах)
X-Container-Meta-Type Тип контейнера
X-Container-Meta-Quota-Bytes Максимальный объем хранения данных (в байтах)
X-Container-Meta-Quota-Count Максимальное количество объектов в контейнере
X-Container-Meta-<...> Метаданные контейнера, где <...> — пользовательский заголовок
X-Versions-Enabled Включено ли версионирование контейнера
Создать контейнер
Создает контейнер с параметрами, указанными в запросе.
Заголовки запроса
Заголовок Описание
X-Container-Meta-Type Тип контейнера:
public (публичный);
private (приватный)
X-Container-Meta-<...> Метаданные контейнера. Укажите <...> — заголовок метаданных
X-Storage-Policy Класс хранения:
Policy-0 (по умолчанию) — стандартное хранение;
cold — холодное хранение
X-Versions-Enabled Включено ли версионирование контейнера
X-Container-Meta-Default-Delete-After Срок хранения всех объектов в контейнере (в секундах)
Пример запроса
curl -i -XPUT \
-H 'X-Auth-Token: ' \
-H 'X-Container-Meta-Type: public' \
-H 'X-Container-Meta-<...>: anyheader' \
https://swift.ru-1.storage.selcloud.ru/v1//
Пример ответа
В случае успеха запрос возвращает ответ с кодом 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
Управлять метаданными контейнера
Устанавливает, заменяет или удаляет метаданные, переданные в заголовке из запроса.
Заголовки запроса
Заголовок Описание
X-Container-Meta-Type Тип контейнера:
public (публичный);
private (приватный)
X-Container-Meta-<...> Метаданные контейнера, которые будут установлены, где <...> — пользовательский заголовок
X-Remove-Container-Meta-<...> Метаданные контейнера, которые требуется удалить, где <...> — пользовательский заголовок
X-Versions-Enabled Включено ли версионирование контейнера
Пример запроса
Изменение типа контейнера:
curl -i -XPOST \
-H 'X-Auth-Token: ' \
-H 'X-Container-Meta-Type: private' \
-H 'X-Versions-Enabled: true' \
https://swift.ru-1.storage.selcloud.ru/v1//
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
Удалить контейнер
Удаляет контейнер в хранилище. Перед удалением контейнера удалите в нем все объекты.
Пример запроса
curl -i -XDELETE -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: Text/html; charset=UTF-8
Объекты
GET /v1/{project_id}/{container_name}/{object_name} Получение объекта
PUT /v1/{project_id}/{container_name}/{object_name} Загрузка объекта
POST /v1/{project_id} Удаление нескольких объектов
POST /v1/{project_id}/{container_name}/{object_name} Управление HTTP-заголовками и метаданными объектов
COPY /v1/{project_id}/{container_name}/{object_name} Копирование объекта
DELETE /v1/{project_id}/{container_name}/{object_name} Удаление объекта
Получить объект
Выведет тело и заголовки объекта.
Пример запроса
curl -I -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1///
Пример ответа
В случае успеха запрос возвращает ответ с кодом 200.
Загрузить объект
Загружает объект в контейнер. Такая загрузка используется для объектов размером до 100 МБ. Для объектов большего размера используйте сегментированную загрузку.
При использовании заголовка X-Copy-From можно загрузить в контейнер скопированный объект. Объект копируется вместе с заголовком X-Delete-At независимо от того, куда был установлен заголовок (на объект или контейнер).
Заголовки запроса
Заголовок Описание
X-Delete-At Время удаления объекта в формате Unix Timestamp
X-Delete-After Срок хранения объекта (в секундах)
Etag Идентификатор Etag
X-Object-Meta-<...> Метаданные объекта, где <...> — пользовательский заголовок
X-Copy-From Путь до объекта, который нужно скопировать
Пример запроса
Загрузка объекта:
curl -i -XPUT \
-H 'X-Auth-Token: ' \
-H 'X-Delete-After: 180' \
-d "" \
https://swift.ru-1.storage.selcloud.ru/v1///
Укажите:
— тело объекта;
— имя, которое будет присвоено объекту.
Копирование объекта:
curl -i -XPUT \
-H 'X-Auth-Token: ' \
-H 'X-Copy-From: //' \
https://swift.ru-1.storage.selcloud.ru/v1///
Укажите:
— контейнер, в который скопируется объект;
— имя, с которым скопируется объект;
— контейнер, в котором находится копируемый объект;
— объект, который нужно скопировать.
Пример ответа
При загрузке в случае успеха объекта запрос возвращает ответ с кодом 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: ' \
-H 'Content-Type: text/plain' \
-d $'/\n/' \
https://swift.ru-1.storage.selcloud.ru/v1/?bulk-delete=true&format=json
Укажите:
/ — путь до объекта в первом контейнере;
/ — путь до объекта во втором контейнере;
\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
Заголовки запроса
Заголовок Описание
X-Container-Meta-<…> Заголовок, параметры которого нужно установить. Укажите <...> — заголовок (например, X-Container-Meta-Cache-Control)
Пример запроса
Добавление заголовка Link к объекту:
curl -i -XPOST \
-H 'X-Auth-Token: ' \
-H 'Link: rel=canonical' \
https://swift.ru-1.storage.selcloud.ru/v1///
Добавление пользовательского заголовка:
curl -i -XPOST \
-H 'X-Auth-Token: ' \
-H 'X-Object-Meta-Some: metadata' \
https://swift.ru-1.storage.selcloud.ru/v1///
Пример ответа
Запрос на добавление заголовка 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.
Заголовки запроса
Заголовок Описание
Destination Путь, по которому будет скопирован объект
Пример запроса
curl -i -XCOPY \
-H 'X-Auth-Token: ' \
-H 'Destination: //' \
https://swift.ru-1.storage.selcloud.ru/v1///
Укажите:
— контейнер, в котором находится копируемый объект;
— объект, который нужно скопировать.
— контейнер, в который скопируется объект;
— имя, с которым скопируется объект.
Пример ответа
В случае успеха запрос возвращает ответ с кодом 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: ' \
https://swift.ru-1.storage.selcloud.ru/v1///
Пример ответа
В случае успеха запрос возвращает ответ с кодом 204.
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
Заголовки для отложенного удаления
Заголовки указываются при отправке запросов PUT и POST и определяют, когда объект будет автоматически удален из хранилища.
Заголовок Значение Описание
X-Delete-At Значение времени (timestamp) в формате Unix Epoch Сервер будет хранить объект до времени, переданном в заголовке. Для конвертирования в человекочитаемый вид можно использовать EpochConverter.
X-Delete-After Целочисленное количество секунд Сервер преобразует это значение в заголовок X-Delete-At. Через указанное количество секунд запрос начнет возвращать ответ 404 на запрос к объекту, при этом объекты автоматически удаляются через некоторое время.
Если указаны оба заголовка, приоритетным будет заголовок 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: ' https://swift.ru-1.storage.selcloud.ru/v1////00000001 -d "hello " \
curl -XPUT -H 'X-Auth-Token: ' https://swift.ru-1.storage.selcloud.ru/v1////00000002 -d "world" \
curl -XPUT -H 'X-Auth-Token: ' https://swift.ru-1.storage.selcloud.ru/v1////00000003 -d "!" \
Пример ответа
В случае успеха запросы возвращают ответы с кодом 201.
Загрузить манифест динамического объекта
Пример запроса
curl -XPUT \
-H 'X-Auth-Token: ' \
-H 'X-Object-Manifest: //' \
https://swift.ru-1.storage.selcloud.ru/v1///
Пример ответа
В случае успеха запрос возвращает ответ с кодом 201.
Загрузить манифест статического объекта
Пример запроса
В теле манифеста статического объекта укажите путь до каждого сегмента объекта.
curl -XPUT \
-H 'X-Auth-Token: ' \
-H 'X-Static-Large-Object: True' \
"[{"path": "///00000001"}, {"path": "///00000002"}, {"path": "///00000003"} ...]" \
https://swift.ru-1.storage.selcloud.ru/v1///?multipart-manifest=put
Пример ответа
В случае успеха запрос возвращает ответ с кодом 201.
Лимиты
POST /v1/{project_id}/{container_name} Установка лимитов на контейнер
POST /v1/{project_id} Установка лимитов на проект
Установить лимиты на контейнер
Устанавливает на контейнер ограничения, переданные в заголовках X-Container-Meta-Quota-Bytes и X-Container-Meta-Quota-Count.
Заголовки запроса
Заголовок Описание
X-Container-Meta-Quota-Bytes Максимальный объем хранения данных (в байтах)
X-Container-Meta-Quota-Count Максимальное количество объектов в контейнере
X-Container-Meta-Default-Delete-After Срок хранения всех объектов в контейнере (в секундах). По истечении этого срока объекты будут автоматически удалены
Пример запроса
curl -i -XPOST \
-H 'X-Auth-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//
Пример ответа
В случае удачного выполнения запроса будет возвращен ответ с кодом 202.
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html
Установить лимиты на проект
Устанавливает на проект ограничение, переданное в заголовке X-Account-Meta-Quota-Bytes.
Заголовки запроса
Заголовок Описание
X-Container-Meta-Quota-Bytes Максимальный объем хранения данных (в байтах)
Пример запроса
curl -i -XPOST \
-H 'X-Auth-Token: ' \
-H 'X-Account-Meta-Quota-Bytes: 52428800' \
https://swift.ru-1.storage.selcloud.ru/v1/
Пример ответа
В случае удачного выполнения запроса будет возвращен ответ с кодом 202.
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html
Дополнительные query-параметры
В запросе на получение списка контейнеров или объектов можно использовать дополнительные query-параметры.
format
Вернет список объектов в определенном формате.
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?format=json
Список объектов будет возвращен в формате JSON.
limit
Задаст точное количество объектов, которые будут включены в список (например, при работе с контейнерами, где хранится большое количество объектов).
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?limit=20
В список будут включены первые 20 объектов.
marker
Задаст объект, начиная с которого будет выведен список.
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?marker=
В списке будут отображены объекты, которые следуют после объекта .
prefix
Включит в список объекты, имена которых начинаются с указанной последовательности символов.
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?prefix=my
В списке будут отображены объекты, которые начинаются с символов my.
delimiter
Объектное хранилище имеет плоскую структуру и не поддерживает папки, но с помощью параметра delimiter можно вывести псевдоиерархию. Запрос с параметром выведет только ту часть имени объектов, которая следует до указанных символов, если он присутствует в выводе имени объекта.
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?delimiter=/
Будут выведены файлы и части префиксов (псевдопапки) на верхнем уровне:
photos/
videos/
file.jpg
Здесь:
photos/, videos/ — части префиксов до символа /, которые есть у объектов в контейнере;
file.jpg — файл без префикса (символа / в названии).
Параметр delimiter можно использовать совместно с параметром prefix, чтобы выводить список объектов и псевдопапок по указанному префиксу.
Пример запроса:
curl -i -H 'X-Auth-Token: ' \
https://swift.ru-1.storage.selcloud.ru/v1//?prefix=photos/&delimiter=/
Пример вывода:
photos/animals/
photos/file.jpg
Символические ссылки
Символическая ссылка — это пустой объект, который указывает на другой объект. С их помощью можно получить доступ к объектам в другом контейнере:
с другой политикой хранения — например, получить доступ к объекту в контейнере с холодным хранением из контейнера со стандартным;
с другим типом — например, получить доступ к объекту в приватном контейнере через символическую ссылку, размещенную в публичном контейнере.
Создать символическую ссылку можно с помощью пустого PUT-запроса на загрузку объекта с заголовком X-Symlink-Target: /.
По умолчанию символические ссылки динамические — они ссылаются на объект по его имени. Символическую ссылку можно сделать статической: при переходе по ссылке дополнительно проверяется Etag объекта. Для этого добавьте в запрос заголовок X-Symlink-Target-Etag: .
Если объект с ссылкой будет не пустой, запрос вернет ответ 400.
Чтобы получить объект с символической ссылкой, выполните GET или HEAD-запрос с параметром ?symlink=get.