Формат файла биллинга
Для интеграции данных о затратах вашей инфраструктуры необходимо реализовать механизм передачи данных (коллектор). Ваша реализация должна обеспечивать выполнение трех ключевых задач: автоматический опрос API или баз данных первоисточника, преобразование полученных сведений в CSV-файлы строго в соответствии со спецификацией Cloudmaster и их последующую загрузку в целевые директории подключенного S3-бакета для регулярного импорта системой.
Технические требования к CSV-файлу⚓︎
- Порядок полей: Первые 15 полей должны следовать строго в указанном ниже порядке.
- Заголовки: В первой строке файла должны быть указаны технические наименования полей.
- Разделитель: Запятая (
,), десятичный разделитель: точка (.). - Кодировка: UTF-8.
Требования к пути и именованию файлов⚓︎
Для того чтобы система Cloudmaster могла автоматически идентифицировать и сопоставлять данные с конкретным подключением, файлы должны размещаться в строго определенной структуре каталогов и иметь унифицированный формат имени.
Шаблон пути в бакете:
/{customerId}/billing/cm-connection-{cloudId}/billing-{customerId}-{cloudId}-{date:yyyyMMdd}.csv
Пример корректного пути к файлу:
/503c2d6b-bb2c-4f22-87b1-ee739csdrtс6/billing/cm-connection-3478/billing-503c2d6b-bb2c-4f22-87b1-ee739csdrtс6-3478-20260413.csv
Описание параметров шаблона⚓︎
| Параметр | Описание | Где найти / Пример |
|---|---|---|
{customerId} |
Уникальный ID клиента в Cloudmaster. | В Профиле пользователя. |
billing |
Директория, определяющая тип данных. | Затраты. |
{cloudId} |
Технический ID конкретного подключения. | В разделе Мои подключения на карточке созданного подключения. |
{date:yyyyMMdd} |
Дата, за которую предоставлены данные. | 20260413 (для данных за 13 апреля). |
.csv |
Расширение файла. | Рекомендуется нижний регистр. |
Обязательные поля (Позиции 1–15)⚓︎
Эти поля определяют базовую структуру биллинга и должны быть заполнены всегда.
| № | Поле | Описание | Пример |
|---|---|---|---|
| 1 | UsageFrom |
Начало периода (UTC). Формат ISO 8601: YYYY-MM-DDThh:mm:ssZ |
2026-04-14T00:00:00Z |
| 2 | UsageTo |
Конец периода (UTC). Формат ISO 8601: YYYY-MM-DDThh:mm:ssZ |
2026-04-14T23:59:59Z |
| 3 | ObjectId |
Внешний ID ресурса в облаке. | i-07f123456789 |
| 4 | ObjectTypeCode |
Код типа объекта из справочника ObjectTypeCode. | vm |
| 5 | ObjectName |
Имя объекта. | prod-web-server-01 |
| 6 | ParentObjectId |
ID объекта-родителя (например, виртуальной машины). | i-07f123456789 |
| 7 | ResourceCode |
Параметр объекта из справочника ResourceCode. | storage.type, storage.size |
| 8 | ResourceSKU |
Артикул (SKU) для тарификации. Необходимо реализовать справочник и его обновление в коллекторе. | sku-776-std |
| 9 | ResourceName |
Описание ресурса (тип, flavor). | m5.large |
| 10 | UnitCode |
Единица измерения QuantityPaid. Cправочник Cloudmaster Ед. измерения. | GB-hour |
| 11 | Quantity |
Выделенный, установленный или фактический объем в единицах, свойственных ресурсу. Например, ГБ. | 1.0 |
| 12 | QuantityPaid |
Оплаченный объем, потребленный за сутки (из биллинга провайдера). | 24.0 |
| 13 | SourcePrice |
Цена за ед. в соответсвии с тарифом (например, за ГБ в час), в 1/1000 копеек с учетом НДС. Рассчитывается, как ROUND (цена в рублях * 100 000). | 150000 |
| 14 | FactPrice |
Вычисляемая фактическая цена в 1/1000 копеек. ROUND(Cost/Quantity)*100 000. | 150000 |
| 15 | Cost |
Итоговая стоимость за период в копейках с учетом НДС и скидок. | 3600 |
Изменять перечень стандартных кодов можно через справочники.
Необязательные поля (Организационная привязка)⚓︎
Эти поля могут идти после 15-го столбца. Они помогают распределить затраты в соответствии с организационной и бизнес-логикой. Значения будут доступны в интерфейсе, поэтому рекомендуется выбирать короткие обозначения, где это возможно. Необязательные поля могут пустыми все или частично.
PlaceL1Id,PlaceL1Code,PlaceL1Name— Уровень Платежный аккаунт / Организация. Справочник Geo и Place code.PlaceL2Id,PlaceL2Code,PlaceL2Name— Уровень Облако / Проект. Справочник Geo и Place code.PlaceL3Id,PlaceL3Code,PlaceL3Name— Уровень Каталог / VDC. Справочник Geo и Place code.ObjTypeSrvId,ObjTypeSrvName— Сервис, к которому относится объект.SrvGroupId,SrvGroupName— Логическое объединение группы сервисов.GeoL1Id,GeoL1Code,GeoL1Name— Географический регион размещения. Справочник Geo и Place code.Tags— Теги ресурсов и объектов.
Требования к группировке и полноте⚓︎
- Гранулярность: Данные сгруппированы по объектам и ресурсам. То есть: одна запись на объект и его ресурс за день.
- Ожидаемые данные: В момент опроса в бакете должен присутствовать файл, содержащий данные за предыдущие полные сутки (00:00:00 — 23:59:59 UTC).