Конвеєри

Конвеєр — це JSON-документ, а ця сторінка описує його мову. Webhooks і Request Bins виконують ту саму мову на тому самому рушії, тож усе, про що ви дізнаєтеся тут, діє й там — у межах правил кожного продукту щодо заголовків. Щоб спробувати будь-що з цього без акаунта, скористайтеся playground.

Документ

Цей конвеєр залишає оплачені рахунки на суму від $1,000, вилучає email клієнта й будь-які номери телефону, додає два поля й заголовок і вказує, що до запиту додається bearer-токен:

{
  "version": 1,
  "steps": [
    { "filter": { "type": "invoice.paid", "data": { "amount": { "$gte": 100000 } } }, "note": "Paid invoices of $1,000 or more" },
    { "drop": ["data.customer.email", "**.phone"] },
    { "set": { "event_type": "{{ type }}", "amount_display": "{{ data.amount | money(data.currency) }}" } },
    { "headers": { "set": { "X-Event-Type": "{{ type }}" } } },
    { "auth": { "type": "bearer", "secret": "sec_…" } }
  ]
}

version — це формат документа, завжди 1, а не версія конвеєра. Кроки виконуються в тому порядку, у якому записані. Кожен — це обʼєкт з одним ключем кроку й, за бажання, note до 200 символів: консоль показує її на кроці, а коли запит відкинуто, її повертає відповідь. filter також може мати action.

Запуск бачить один запит: body — будь-яке значення JSON, headers і meta, доступне лише для читання. В API запуску усі три — це те, що ви надсилаєте. Кожен крок бачить тіло таким, яким його залишив попередній. В API й текстах помилок кроки нумеруються з 0, а в редакторі консолі — з 1.

filter

Залишає запит, лише якщо він збігається; інакше запуск відповідає dropped. З "action": "drop" усе навпаки: відкидається те, що збігається.

{ "filter": { "data": { "status": "paid", "amount": { "$gte": 100000 } } }, "note": "Paid, $1,000 or more" }

• Кожен ключ — це умова, і виконуватися мають усі. Вкладений обʼєкт перевіряється за формою, як тут data.
• Просте значення збігається за рівністю JSON: 1 дорівнює 1.0.
• Масив збігається, коли він дорівнює значенню або коли збігається один з його елементів: {"data": {"tags": "urgent"}} виконується для ["billing", "urgent"], а {"data": {"items": {"sku": "A-1", "qty": 2}}} потребує одного елемента, у якому є обидва.
• Поле, якого в запиті немає, збігається лише з {"$exists": false} і запереченнями, як-от $neq.
• Оператори: $eq, $neq, $gt, $gte, $lt, $lte (числа з числами, текст із текстом; мітки часу ISO порівнюються за часом), $in, $nin, $exists, $startsWith, $endsWith, $contains (текст або масив, що містить значення), а також $and, $or і $not, щоб поєднувати фільтри.
• $headers, $meta і $body перевіряють відповідну частину запиту: {"$headers": {"x-github-event": "push"}}.

drop

Вилучає поля з тіла: список від 1 до 50 шляхів. * відповідає будь-якому одному рівню, а ** — будь-якій глибині, тож **.email вилучає кожне поле email, хоч би де воно було. Шлях, який нічому не відповідає, не є помилкою.

{ "drop": ["data.customer.email", "data.cards[*].number", "**.phone"] }

set

Додає або перезаписує поля: від 1 до 50 пар зі шляху й значення. Відсутні обʼєкти дорогою створюються, і кожне значення читає тіло таким, яким його застав крок. Шлях, що натрапляє на значення, яке не є обʼєктом, провалює запуск з set_conflict.

{ "set": { "event_type": "{{ type }}", "data.total_cents": { "$ref": "data.amount" } } }

map

Замінює тіло значенням, яке пишете ви, — зазвичай обʼєктом.

{ "map": {
    "invoice_id": "{{ data.id }}",
    "amount": { "$ref": "data.amount" },
    "amount_display": "{{ data.amount | money(data.currency) }}",
    "event": "{{ type }}"
} }

Для запиту invoice.paid, у якого data — це {"id": "in_42", "amount": 150000, "currency": "usd"}, тіло стає таким:

{ "invoice_id": "in_42", "amount": 150000, "amount_display": "1,500.00 USD", "event": "invoice.paid" }

headers

Задає заголовки через set, вилучає їх через remove і перейменовує через rename — у порядку remove, rename, set. Назви збігаються незалежно від регістру, а задана назва замінює всі її написання.

{ "headers": { "set": { "X-Event-Type": "{{ type }}", "Content-Type": "application/json" } } }

Крок headers не може задати заголовок, що належить зʼєднанню, як-от Host чи Content-Length, а також Set-Cookie. Не може він задати й Authorization, Cookie чи X-Api-Key, бо значення лежало б у документі, який повертає кожне читання: облікові дані додаються кроком auth. Продукт, який виконує конвеєр за посиланням, також застосовує до нього власні правила щодо заголовків.

auth

Вказує, що до запиту додаються облікові дані, і називає слот, з якого вони беруться:

{ "auth": { "type": "api_key", "in": "header", "name": "X-Api-Key", "secret": "sec_…" } }

secret — це ідентифікатор слота, який є в робочому просторі. Це ніколи не значення: вставлене туди значення відхиляється з invalid_secret, і відмова його не повторює. Продукт, який виконує конвеєр за посиланням, зіставляє слот із власним секретом (Облікові дані). Тестування й API запуску показують заголовок чи параметр із замаскованим значенням.

Кроки auth стоять після всіх інших кроків, тож жоден крок не може прочитати, скопіювати чи перевірити облікові дані.

Шляхи та значення

Шлях указує на поле тіла:

set приймає прості шляхи, drop — * і **, а значення читає з *, але не з **.

Значення в set, map чи заголовку — це JSON, який копіюється так, як записаний, за двома винятками:

• {{ path }} у рядку вставляє значення як текст. Відсутнє значення чи null нічого не вставляє, а обʼєкт або список вставляється як JSON. {{ 'text' }} і {{ 42 }} — літерали, тож буквальне {{ записується як {{ '{{' }}.
• {"$ref": "path"} вставляє саме значення й зберігає його тип: число лишається числом, список — списком. Додайте "default" на випадок, коли шляху немає.

Вираз може пропустити своє значення через фільтри, зліва направо: {{ data.amount | money(data.currency) }} дає 1,500.00 USD для суми 150000 у usd.

Циклів, умов і обчислень немає: умова — це крок filter, а список стає текстом через [*] і join.

Шаблони

У галереї є готові конвеєри, з яких можна почати. У консолі вони під Start from a template. Через API GET /v1/pipelines/templates повертає кожен шаблон із його pipeline. Після збереження шаблону ви отримуєте власний конвеєр: змінюйте його, як будь-який інший; із шаблоном він більше нічим не повʼязаний.

Кожен шаблон для чату — це крок map і крок headers, що задає Content-Type: application/json, і працює він з будь-якою подією. Відсутній тип показується як «Event», а відсутній ідентифікатор чи час — як «—», дані обрізаються під обмеження застосунку, і ніщо в події не може відформатувати повідомлення, когось згадати чи передчасно завершити блок коду.

Ліміти

Конвеєр не має циклів, годинника й мережі, а фіксовані межі обмежують кожен запуск. Якщо межу перевищено, запуск відповідає failed із причиною, а документ, що її перевищує, відхиляється під час збереження.

У playground менші межі: документ на 16 KiB, тіло на 32 KiB, 16 KiB на одне значення, яке формує крок, 20 заголовків, 1 KiB на значення одного заголовка і 10,000 прочитаних чи скопійованих значень за один запуск.

Що далі

• Швидкий старт — протестуйте конвеєр, збережіть його й запустіть.
• Довідник Transforms — усі маршрути й поля, а також що означає кожна відмова.
• Трансформації у Webhooks — та сама мова на ендпоінті Webhooks.