Формат API-запроса в OBS

В этом разделе описывается структура запроса REST API.

URI-запрос

URI используется в OBS для определения местоположения сегментов, объектов и их параметров.

Ниже приведен общий формат URI. Параметры, заключенные в квадратные скобки [ ], являются необязательными.

protocol://[bucket.]domain[:port][/object][?param]

Параметры URI
Параметр	Описание	Обязательный параметр
protocol	Параметр используется для отправки запросов как по протоколу HTTP, так и по HTTPS.	Да
bucket	Путь к ресурсам одного бакета в OBS.	Нет
domain	Доменное имя или IP-адрес сервера для хранения ресурсов.	Да
port	Порт, который используется для протоколов API-запросов. Его значение зависит от развертывания сервера программного обеспечения. Если не указан уникальный номер порта, то будет использоваться значение по умолчанию. В сервисе OBS значение порта по умолчанию для протокола HTTP — 80, а для протокола HTTPS — 443.	Нет
object	Путь до объекта в OBS.	Нет
param	Свойство, содержащееся в бакете или объекте. Значение этого параметра по умолчанию указывает на то, что получен бакет или объект.	Нет

Все API-запросы, за исключением запросов для получения списка бакетов, должны содержать название бакета. В Object Storage Service при запросе необходимо размещать название бакета перед параметром domain, так как оно будет использоваться для создания доменного имени третьего уровня.

Например, если бакет называется «test-bucket», расположен в регионе «ru-moscow» и нужно получить доступ через ACL к объекту «test-object» в этом бакете, то правильный URI-запрос будет выглядеть так:

https://test-bucket.obs.ru-moscow.example.com/test-object?acl

Метод API-запроса

HTTP-методы определяют тип операций в запросе к серверу.

Методы HTTP в запросе
Метод	Описание
GET	Возвращает ресурсы, например список бакетов или объект.
PUT	Обновляет ресурсы, например позволяет создать бакет или загрузить объект.
POST	Добавляет ресурсы или выполняет определенную операцию, например позволяет загрузить часть ресурсов или выполнить слияние.
DELETE	Удаляет ресурсы, например удаляет объект в бакете.
HEAD	Возвращает дайджест по ресурсу, например метаданные объекта.
OPTIONS	Проверяет разрешения пользователя на использование ресурса. Для бакета нужно настроить CORS (кросс-доменные запросы).

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

Заголовок — это необязательное и дополнительное поле запроса, например поле, требуемое определенным URI или HTTP-методом.

Общие заголовки запросов
Заголовок	Описание	Обязательный параметр
Authorization	Содержит информацию о подписи в сообщении запроса. Тип — string. Нет значения по умолчанию. Это необязательный параметр для анонимных запросов и обязательный для других запросов.	Условный
Content-Length	Длина тела запроса (исключая заголовки) в соответствии со спецификацией RFC 2616.	Условный
Content-Type	Тип данных в запросе, например `text/plain`. Тип — string. Нет значения по умолчанию.	Нет
Date	Дата и время отправки запроса, например `Wed, 27 Jun 2018 13:39:15 +0000`. Тип — string. Нет значения по умолчанию. Это необязательный параметр для анонимных запросов или тех запросов, которые содержат заголовок «x-obs-date», обязательный для других запросов.	Условный
Host	Адрес хоста, который получает запросы, например `bucketname.obs.region.example.com`. Тип — string. Нет значения по умолчанию.	Да

Тело запроса

Тело запроса отправляется в структурированном формате (например, JSON или XML). Он соответствует формату Content-Type в заголовке запроса и используется для передачи содержимого, отличного от заголовка запроса.

Некоторым API не требуется тело запроса, например API-методам GET и DELETE.

Отправка запроса

Есть два метода инициирования запросов:

cURL
Это инструмент командной строки, позволяющий взаимодействовать с различными серверами по множеству протоколов с синтаксисом URL. Подробнее — на официальном сайте cURL.

При использовании cURL возможен доступ только к анонимным общедоступным OBS-ресурсам.
Coding
Код можно использовать для выполнения API-запросов, а также для сборки, отправки и обработки сообщений запросов.

См.также

OBS API Reference