Довідник Transforms
API за адресою https://transforms.nimbusnexus.net/v1 створює, версіонує, тестує й запускає конвеєри — лише для вашого робочого простору. Запити й відповіді — у JSON. Надсилайте ключ як Authorization: Bearer <key> або X-API-Key: <key> (Як отримати доступ). Timestamp-и подаються в ISO 8601 за UTC. Огляд пояснює, що це за продукт, а Конвеєри описують документ.
Маршрути
| Маршрут | Що робить | Потрібно |
|---|---|---|
POST /v1/pipelines | Створює конвеєр і його версію 1; 201 з конвеєром | write; для кроку облікових даних — admin |
GET /v1/pipelines | Конвеєри робочого простору, найновіші першими, кожен без документа | read |
GET /v1/pipelines/{id} | Один конвеєр, із поточним документом і тим, де він виконується | read |
PATCH /v1/pipelines/{id} | Перейменовує його, вмикає чи вимикає або зберігає нову версію | write; для нового кроку облікових даних — admin |
DELETE /v1/pipelines/{id} | Видаляє конвеєр і його версії назавжди; 204 | admin |
GET /v1/pipelines/{id}/versions | Збережені версії, найновіші першими, кожна без документа | read |
GET /v1/pipelines/{id}/versions/{version} | Одна версія, з документом | read |
POST /v1/pipelines/{id}/run | Запускає збережений конвеєр на запиті | read |
POST /v1/pipelines/test | Тестує документ на запиті й нічого не зберігає та не рахує | write |
GET /v1/pipelines/templates | Шаблони, з яких можна почати | read |
POST /v1/slots | Додає слот облікових даних; 201 зі слотом | admin |
GET /v1/slots, GET /v1/slots/{id} | Слоти робочого простору, найновіші першими, або один слот | read |
PATCH /v1/slots/{id} | Перейменовує слот | admin |
DELETE /v1/slots/{id} | Видаляє слот; 204 | admin |
GET /v1/plan | План робочого простору та його ліміти | read |
GET /v1/usage | Запуски за цей місяць і те, що є в робочому просторі | read |
Що означають read, write і admin, пояснено в розділі Хто що може робити.
Списки поділено на сторінки параметрами limit (від 1 до 200, за замовчуванням 50) та offset (від 0 до 10,000). Відповідь має вигляд {"items": [...], "next_offset": <offset>}: передайте next_offset назад як offset, щоб отримати наступну сторінку. На останній сторінці він дорівнює null. Виняток — GET /v1/pipelines/templates: цей маршрут не приймає ні limit, ні offset і відповідає одним простим масивом з усіма шаблонами.
Обʼєкт конвеєра
| Поле | Що це |
|---|---|
id | pipe_ і 24 шістнадцяткові символи. Його приймає кожен маршрут, і за ним на конвеєр посилається продукт. |
name | Ваша назва для нього, до 200 символів. |
status | enabled або disabled: ваш перемикач. Вимкнений конвеєр не виконується ні тут, ні в жодному продукті, який на нього посилається. |
current_version | Версія, яка виконується. |
pipeline | Документ поточної версії; null у списку. |
destinations | Сервіси, які виконують його за посиланням, кожен один раз; null у списку (Хто виконує конвеєр). |
consumers | Що виконує кожен із них: service, version, last_seen_at — коли він востаннє отримував цю версію, і pinned — true, коли посилання закріплює цю версію; null у списку. |
created_at, updated_at | Коли його створено і коли востаннє змінено. |
POST /v1/pipelines приймає name і pipeline. Документ, який ніколи не зміг би виконатися, відхиляється з 422 invalid_pipeline, а понад кількість конвеєрів, яку дозволяє план, відповідь — 402 quota_exceeded з details.metric pipelines, details.limit і details.current.
Версії
PATCH /v1/pipelines/{id} приймає будь-які з полів name, status і pipeline. Новий pipeline перевіряється так само, як під час створення, і зберігається як наступна версія.
- Версія ніколи не змінюється, тож продукт може тримати свою копію за ідентифікатором і версією.
- Збереження того самого вмісту не додає версії.
- Щоб відновити стару версію, треба знову зберегти її вміст, і вона стає найновішою.
- Зберігається стільки версій, скільки передбачає план, починаючи з найновіших, а збереження вилучає найстаріші понад цю кількість. Версія, яку продукт закріпив, теж зберігається, як і пʼять старіших версій, які, за нашими даними, продукт виконував пізніше за решту протягом останніх 30 днів.
Кожна версія в GET /v1/pipelines/{id}/versions має version, created_by і created_at; GET /v1/pipelines/{id}/versions/{version} додає її pipeline. Версія, яка більше не зберігається, відповідає 404 not_found, pipeline_version.
Запустіть конвеєр
POST /v1/pipelines/{id}/run виконує поточну версію або збережену версію, яку вказує version, на тому, що ви надсилаєте:
| Поле | Що це |
|---|---|
body | Будь-яке значення JSON, до 256 KiB як компактний JSON, із вкладеністю щонайбільше 32 рівні. |
headers | По одному значенню на назву, щонайбільше 256. Назва має до 256 символів, а значення — до 8,192. Понад це відповідь буде 422 validation_error. |
meta | Контекст для $meta, лише для читання: будь-яке значення JSON із вкладеністю щонайбільше 32 рівні. |
version | Збережена версія, яку треба виконати. Без цього поля — поточна. |
Про запит нічого не зберігається, а запуск зараховується. Відповідь — 200, хоч би що зробив конвеєр:
| Поле | Що це |
|---|---|
status | ok — надішліть body і headers; dropped — фільтр відкинув запит, тож нічого не надсилайте; failed — конвеєр не може виконатися на цьому запиті. |
version | Версія, яка виконалася; null під час тесту. |
body, body_changed | Тіло, яке треба надіслати, і true, коли крок його переписав. null, якщо статус не ok. |
headers | Заголовки, які треба надіслати; значення облікових даних замасковано як Bearer ••••. |
query | Що крок auth додає до URL; значення замасковано так само. |
step | Крок, який відкинув запит або на якому запуск провалився, рахуючи з 0; інакше null. |
note | Примітка кроку, який відкинув запит. |
reason | no_match — для фільтра, з яким запит не збігся, matched — для фільтра відкидання, з яким він збігся, або причина збою, як-от set_conflict чи too_many_nodes. Вважайте його відкритим рядком. |
error | Те саме словами, як-от step 2: set_conflict: …. |
duration_ms | Скільки тривав запуск. |
Той самий конвеєр на тому самому запиті провалюється так само, тож не повторюйте запуск зі статусом failed. Вимкнений конвеєр відповідає 409 conflict, pipeline_disabled, а понад частоту плану або коли одночасно виконується забагато запусків чи тестів робочого простору, запуск відповідає 429 rate_limited з details.retry_after.
Протестуйте документ
POST /v1/pipelines/test приймає pipeline — документ, який не обовʼязково зберігати, — разом із body, headers і meta. Він перевіряється так само, як під час збереження, виконується один раз і нічого не зберігає й не рахує, хоча має спільну із запусками частоту плану. Якщо запит відкинуто або запуск провалився, відповідь — 200, яка про це повідомляє.
Слоти облікових даних
Слот — це те, що називає крок auth: ідентифікатор і мітка, без значення. Transforms не зберігає облікових даних, і жоден маршрут їх не приймає. Продукт, який виконує конвеєр за посиланням, зіставляє слот із власним секретом (Облікові дані). POST /v1/slots приймає label до 200 символів і відповідає 201:
| Поле | Що це |
|---|---|
id | sec_, а далі літери й цифри: те, що називає крок auth. Він ніколи не змінюється. |
label | Для чого призначені облікові дані. Продукти бачать мітку, коли зіставляють слот із секретом. |
pipeline_count | У поточних версіях скількох конвеєрів він названий. |
created_at, updated_at | Коли його додано і коли востаннє перейменовано. |
PATCH /v1/slots/{id} приймає label. DELETE /v1/slots/{id} відповідає 204 або, поки слот називає поточна версія якогось конвеєра, 409 conflict з details.reason slot_in_use, details.id і details.pipelines, кількістю конвеєрів. Коли всі слоти плану вже використано, додавання нового відповідає 402 quota_exceeded з details.metric slots.
Хто виконує конвеєр
Продукт посилається на конвеєр за ідентифікатором і виконує його у власному процесі, зі своїми секретами. Перший такий продукт — Webhooks: Трансформації. Кожне отримання конвеєра записує сервіс і версію, тож читання конвеєра показує destinations і consumers.
Збереження нової версії з кроком auth доходить до кожного продукту, який виконує конвеєр, і так само видалення конвеєра. Кожен із цих викликів має назвати в confirm_destinations кожен сервіс, який має посилання або який ми бачили протягом останніх 30 днів: у тілі PATCH і в рядку query DELETE. Інакше це 409 conflict з details.reason destinations_unconfirmed і details.destinations, і нічого не змінюється. Власних URL-адрес сервісу тут ніколи немає: щодо них те саме запитання ставить сам продукт.
Хто що може робити
| Читати конвеєри, версії, шаблони, слоти, план і споживання; запускати | Створювати, змінювати й тестувати конвеєри | Видаляти конвеєр, зберігати крок облікових даних або додавати, перейменовувати чи видаляти слот | |
|---|---|---|---|
| Власник або адміністратор робочого простору | так | так | так |
| Учасник | так | так | ні |
| Переглядач або будь-яка інша роль | так | ні | ні |
Ключ із Read & write (область дії admin) | так | так | так |
Ключ із Read (область дії read) | так | ні | ні |
Заборонена дія відповідає 403 forbidden з details.reason role, а details.required називає потрібну роль. Учасник усе одно може перейменувати конвеєр із кроком облікових даних, запустити його, протестувати й вилучити цей крок. Консоль акаунта створює ключі Read і Read & write, а ключ із будь-якою іншою областю дії, як-от write, вважається ключем Read.
Transforms обслуговує робочі простори цілком. Гостьове місце або ключ, обмежений одним проєктом, отримує відмову 403 project_confined. Transforms зʼявляється в робочому просторі, щойно власник або адміністратор відкриє консоль чи додасть продукт через Add a product. До того інші учасники отримують відмову 403 product_not_enabled.
Плани й ліміти
GET /v1/plan показує, які ліміти діють: plan — план, закріплений за робочим простором; enforced_as — план, чиї ліміти діють, free, якщо плану немає; ceilings — ліміти за назвами; а також past_due, suspended і system.
Ключ у ceilings | Що це | Free | Starter | Pro | Custom |
|---|---|---|---|---|---|
max_pipelines | Конвеєрів у робочому просторі | 5 | 25 | 100 | 1,000 |
max_secret_slots | Слотів облікових даних у робочому просторі | 5 | 25 | 100 | 1,000 |
max_versions | Збережених версій на конвеєр | 10 | 25 | 50 | 100 |
run_rate_per_min | Запусків і тестів на хвилину, на робочий простір | 60 | 600 | 3,000 | 12,000 |
Швидко один за одним може надійти стільки запусків, скільки припадає на десять секунд, і щонайменше 10. Крім того, у кожному процесі сервера одночасно виконуються щонайбільше два запуски чи тести робочого простору, і ще один не ставиться в чергу, а відхиляється з 429 rate_limited і details.retry_after 1. GET /v1/usage показує, скільки використано: period — місяць, позначений своїм першим днем; runs, failures і dropped — цього місяця, через API запуску; pipelines порівняно з max_pipelines; і slots — наявні слоти — порівняно з max_secret_slots. Запуски рахуються, але не тарифікуються, а запуск у продукті, який посилається на конвеєр, зараховується до споживання цього продукту.
Поки платіж не погашено, зміни відхиляються з 402 workspace_frozen, а запуски й тести далі працюють. Коли пільговий період закінчиться, запуски й тести теж відхилятимуться, з 402 workspace_suspended. Читання й видалення лишаються доступними.
Помилки
Помилки API мають формат, описаний на сторінці Помилки.
| Статус | code | Коли |
|---|---|---|
400 | bad_request | Тіло JSON, яке не є коректним UTF-8. |
401 | unauthorized | Немає облікових даних, їх відкликано або сесія входу в консоль закінчилася; details.reason уточнює, що саме. |
401 | invalid_credential | Ключ не проходить перевірку, його строк дії сплив або його створено для іншого продукту. |
402 | quota_exceeded | Створення конвеєра чи додавання слота, коли всі конвеєри чи слоти плану вже використано; details.metric дорівнює pipelines або slots. |
402 | workspace_frozen, workspace_suspended | Зміна, поки платіж не погашено, або будь-що, крім читання чи видалення, після зупинення обслуговування. |
403 | forbidden | details.reason дорівнює role, project_confined, product_not_enabled, csrf або no_workspace. |
404 | not_found | Такого конвеєра, версії чи слота у вашому робочому просторі немає; details.reason дорівнює pipeline, pipeline_version або slot. |
405 | method_not_allowed | Шлях існує, але не для цього методу. |
409 | conflict | details.reason дорівнює pipeline_disabled (Запустіть конвеєр), destinations_unconfirmed (Хто виконує конвеєр) або slot_in_use (Слоти облікових даних). |
413 | payload_too_large | Тіло запиту понад 1 MiB. |
422 | invalid_pipeline | Конвеєр, який ніколи не зміг би виконатися, під час збереження чи тестування. |
422 | validation_error | Параметр або поле не проходить валідацію. Символ NUL у шляху, query чи тілі JSON дає тип запису transforms.nul_character. |
429 | rate_limited | Понад кількість запусків на хвилину, яку дозволяє план, або забагато одночасних запусків чи тестів робочого простору (Плани й ліміти); details.retry_after показує, коли спробувати знову. |
500 | internal_error | Щось зламалося на нашому боці. |
Недійсні конвеєри
Відмова називає першу проблему: details.reason, details.path (JSON Pointer до неї) і details.step (рахуючи з 0) — кожне, коли воно доречне.
{ "error": { "code": "invalid_pipeline", "message": "…", "details": { "reason": "credential_header", "path": "/steps/0/headers/set/Authorization", "step": 0 }, "request_id": "…" } }reason | Що не так |
|---|---|
invalid_document | Це не обʼєкт із version і списком steps. |
unsupported_version | version не дорівнює 1. |
no_steps | Кроків немає. |
too_many_steps | Кроків понад 20. |
invalid_step | Крок — не обʼєкт з одним ключем кроку, поруч із яким можуть бути лише note і, у фільтра, action. |
unknown_step | Ключ кроку не є filter, drop, set, map, headers чи auth. |
invalid_value | Налаштування не з тих, які приймає крок, як-от порожній drop чи примітка довша за 200 символів. |
invalid_path | Шлях неможливо прочитати, або він містить символ підстановки там, де крок його не приймає. |
invalid_template | Вираз неможливо прочитати, або він називає фільтр, якого не існує. |
invalid_filter | Фільтр недійсний, наприклад має невідомий оператор. |
invalid_header | Назва заголовка недійсна чи належить зʼєднанню, або значення не є друкованим ASCII в одному рядку. |
invalid_secret | secret у кроці auth не є ідентифікатором слота. Значення, вставлене туди, ніколи не повторюється в повідомленнях. |
auth_not_last | Після кроку auth стоїть інший крок. |
too_deep | Щось вкладено глибше ніж на 32 рівні. |
too_large | Налаштування кроку перевищують 16 KiB або документ перевищує 64 KiB. |
not_json | Документ містить значення, яке не є JSON. |
forbidden_header | Крок задає Set-Cookie — заголовок, якого не має жоден запит. |
credential_header | Крок headers задає Authorization, Cookie або X-Api-Key, через що облікові дані зберігалися б у конвеєрі. Натомість додайте їх кроком auth. |
unknown_slot | Крок auth називає слот, якого немає в робочому просторі. |
Вважайте reason відкритим рядком і передбачте обробку за замовчуванням для невідомого значення.
Що далі
- Швидкий старт — протестуйте конвеєр, збережіть його й запустіть.
- Конвеєри — усі кроки, шляхи, фільтри й шаблони.
- API Transforms — усі операції із запитом у curl, TypeScript, Python або Go.
- Помилки — формат помилки, усі ключі
detailsі підхід до їх обробки.