tocdepth: 2

Справочник API

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

Перед началом работы

Для работы с API личного кабинета Cloud.ru потребуется:

эндпоинт для запросов — https://organization.api.cloud.ru;
авторизационный токен;
customer_id — его можно скопировать в личном кабинете.

Примечание

При запросе проверяются права вашей учетной записи или сервисного аккаунта.

Запрос доступен только ролям:

администратор организации — для запроса информации по организации;
администратор проекта — для запроса информации по проекту.

Подробнее о ролях — в статье Роли пользователей Cloud.ru

Метод для получения информации

GET /v1/consumption

Получение потребления по ресурсам

Query Parameters

agreement_id (string) – обязательное поле (либо project_ids). Фильтр по id договора.
project_ids (array) – обязательное поле (либо agreement_id). Фильтр по id проекта.
service_names (array) – фильтр по названиям сервисов.
start_date (string) – обязательное поле. Фильтр по дате начала периода.
end_date (string) – обязательное поле. Фильтр по дате окончания периода.
page_filter.limit (integer) – передается вместе с page_filter.page. Количество сущностей на странице. Рекомендуемое значение - не более 30 000.
page_filter.page (integer) – передается вместе с page_filter.limit. Номер страницы. Нумерация начинается с 1.

Status Codes

200 OK – A successful response.
400 Bad Request – Некорректный запрос
401 Unauthorized – Необходима авторизация
403 Forbidden – Доступ запрещен
404 Not Found – Ресурс не найден
500 Internal Server Error – Внутренняя ошибка сервера

Response JSON Object

consumptions (array) – Массив строк с потреблением
consumptions[].amount (number) – Стоимость потребления без НДС.
consumptions[].amount_nds (number) – Стоимость потребления с НДС.
consumptions[].cost (number) – Тариф потребления сервиса без НДС.
consumptions[].dmid (integer) – Идентификатор подключения к платформе в биллинге (внутри проекта).
consumptions[].dog_id (string) – Идентификатор договора в биллинге.
consumptions[].meta (object) – Дополнительная мета-информация об экземпляре ресурса.
consumptions[].platform (string) – Платформа сервиса.
consumptions[].resource_id (string) – Идентификатор экземпляра ресурса.
consumptions[].resource_name (string) – Название экземпляра ресурса.
consumptions[].servname (string) – Название облачного сервиса в продуктовом каталоге.
consumptions[].sku (string) – Идентификатор облачного сервиса в продуктовом каталоге.
consumptions[].unit (string) – Единица измерения для тарифа сервиса.
consumptions[].usedate (string) – Дата, за которую собрано потребление.
consumptions[].usefact (number) – Объем потребления сервиса.

Метаданные платформ

В ответах могут содержаться метаданные платформ, например:

Платформа Advanced

iam_project_id — идентификатор проекта IAM.
enterprise_project_id — идентификатор Enterprise-проекта.
az_code — указание на зону доступности (AZ).
tenant_name — название тенанта, в котором развернут сервис.
extended_params — расширенные параметры.

Платформа ML Space

product_instance_name — название продуктового инстанса, в котором развернут сервис.

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

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

/v1/consumption?

agreement_id=5f3ca99e-74ab-4218-aa5f-64757889c5e8&

start_date=2024-06-01T00:00:00Z&

end_date=2024-06-09T00:00:00Z&

project_ids=c952dfaa-ec64-4176-8be8-5dba21c1eb35&

project_ids=c952dfaa-ec64-4176-8be8-5dba21c1eb34&

service_names=Привязка публичного IP адреса

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

{
  "consumptions": [
    {
      "dog_id": "string",
      "dmid": 0,
      "sku": "string",
      "servname": "string",
      "resource_id": "string",
      "resource_name": "string",
      "usedate": "2024-08-14T07:50:48.912Z",
      "amount": 0,
      "amount_nds": 0,
      "cost": 0,
      "unit": "string",
      "usefact": 0,
      "platform": "string",
      "meta": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
     }
    }
  ]
}

Коды ошибок

Если при выполнении запроса вы получили ошибку 500 - Internal server error с одним из кодов, изучите возможные причины их возникновения и рекомендации по устранению в таблице ниже.

Код ошибки	Возможная причина	Рекомендации
`500 - failed to get agreement`	Внутренняя ошибка сервиса	Обратитесь в техническую поддержку
`500 - failed to get projects`	Внутренняя ошибка сервиса	Обратитесь в техническую поддержку
`500 - failed to get consumption`	Внутренняя ошибка сервиса, связанная с получением потребления по заданным параметрам	Попробуйте повторить запрос позднее. Откорректируйте запрос: сократите период выборки и/или укажите параметр page_filter.limit не более 30 000.

Была ли статья полезной?

Спасибо за отзыв! Что можно улучшить?