tocdepth

2

Справочник API

В справочнике собраны доступные методы API:

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

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

Примечание

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

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

  • администратор организации — для запроса информации по организации;

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

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

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

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

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.

  • start_updated_dt (string) – Фильтр по времени обновления записи. Дата начала периода.

  • end_updated_dt (string) – Фильтр по времени обновления записи. Дата окончания периода.

Status Codes
Response JSON Object

  • consumptions (array) – Массив строк с потреблением.

  • consumptions[].amount (number) – Стоимость потребления без НДС.

  • consumptions[].amount_nds (number) – Стоимость потребления с НДС.

  • consumptions[].cost (number) – Тариф потребления сервиса без НДС.

  • consumptions[].dmid (integer) – Идентификатор подключения к платформе в биллинге (внутри проекта).

  • consumptions[].dog_id (string) – Идентификатор договора в биллинге.

  • consumptions[].encode_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[].updated_dt (string) – Время обновления записи.

  • consumptions[].usedate (string) – Дата, за которую собрано потребление.

  • consumptions[].usefact (number) – Объем потребления сервиса.

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

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

Платформа Advanced

  • iam_project_id — идентификатор IAM-проекта.

  • iam_project_name — наименование проекта IAM.

  • enterprise_project_id — идентификатор Enterprise-проекта.

  • enterprise_project_name — наименование Enterpise-проекта.

  • az_code — указание на зону доступности (AZ).

  • tenant_name — название тенанта, в котором развернут сервис.

  • extended_params — расширенные параметры.

Платформа ML Space

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

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

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

/v1/consumption?

agreement_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx&

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

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

project_ids=xxxxxxxx-xxxx-xxxx-xxxxxxx01&

project_ids=xxxxxxxx-xxxx-xxxx-xxxxxxx02&

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

start_updated_dt: 2024-09-01T00:00:00Z

end_updated_dt: 2024-10-01T00:00:00Z

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

{
  "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"
     },
     "updated_dt": "2024-12-12T09:42:04.817Z",
     "encode_id": "string"
    }
  ]
}

Коды ошибок

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

Код ошибки

Возможная причина

Рекомендации

429 - received message larger than max

Превышен допустимый объем выборки

Откорректируйте запрос: сократите период выборки и/или укажите параметр page_filter.limit не более 30 000.

500 - failed to get agreement

Внутренняя ошибка сервиса

Обратитесь в техническую поддержку

500 - failed to get projects

Внутренняя ошибка сервиса

Обратитесь в техническую поддержку

500 - failed to get consumption

Внутренняя ошибка сервиса, связанная с получением потребления по заданным параметрам

Попробуйте повторить запрос позднее.

Метод для получения набора тегов по платформе Advanced

GET /v1/consumption/resource_tags

Получение тегов из сервиса потребления

Query Parameters

  • agreement_id (string) – Обязательное поле (либо project_ids). Фильтр по ID договора.

  • project_ids (array) – Обязательное поле (либо agreement_id). Фильтр по ID проектов.

  • page_filter.limit (integer) – Количество сущностей на странице.

  • page_filter.page (integer) – Номер страницы. Нумерация начинается с 1.

Status Codes
Response JSON Object

  • resource_tags (array) – Массив тегов ресурсов.

  • resource_tags[].platform (string) – Платформа облачного сервиса.

  • resource_tags[].raw_tags (string) – Теги ресурса в виде строки

  • resource_tags[].resource_id (string) – Идентификатор экземпляра ресурса.

  • resource_tags[].resource_name (string) – Название экземпляра ресурса.

  • resource_tags[].tags (object) – Теги ресурса в виде словаря.

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

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

/v1/consumption/resource_tags?

agreement_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx&

project_ids=xxxxxxxx-xxxx-xxxx-xxxxxxx01&

page_filter.page=5

page_filter.limit=10

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

{
  "resource_tags": [
      {
          "resource_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
          "resource_name": "ca-disk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
          "platform": "Cloud.ru Advanced",
          "raw_tags": "cloudadvisor:diskscan",
          "tags": {
              "cloudadvisor": "diskscan"
          }
      },
      {
          "resource_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
          "resource_name": "ca-diskscan-xxxxxxxx",
          "platform": "Cloud.ru Advanced",
          "raw_tags": "cloudadvisor:diskscan;cloudadvisor-version:1.4.8.6",
          "tags": {
              "cloudadvisor": "diskscan",
              "cloudadvisor-version": "1.4.8.6"
          }
      },
      {
          "resource_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
          "resource_name": "ca-disk-xxxx-xxxx-xxxx-xxxxxxxxx",
          "platform": "Cloud.ru Advanced",
          "raw_tags": "cloudadvisor:diskscan",
          "tags": {
              "cloudadvisor": "diskscan"
          }
      }
  ]
 }
Запустили Evolution free tier
для Dev & Test
Получить