Synchra.24
menu_bookҚұжаттама
Практические материалы по запуску и развитию

Здесь собраны инструкции по запуску, разработке внутренних сценариев и встраиванию собственных инструментов в рабочий контур компании.

folderАвтоматтандыру

Автоматтандыру конфигурациясы

YAML және JSON анықтамалығы: кесте, жүйелік және қызмет оқиғалары, дереккөздер, Тағайындаулар және қайталаулар.

Автоматты аударма

Конфигурация автоматтандырудың жұмыс тәртібін анықтайды. Редактор YAML және JSON қабылдайды, белгілі өрістерді тексереді және олардың атауларындағы қателерді жіберіп алмайды.

Конфигурация мөлшері 256 КБ-тан аспауы керек. Схеманың нұсқаларына қолдау көрсетіледі 1 және 2. Нұсқа 2 synchra24 оқиғалары бойынша іске қосу үшін қажет.

Жоғарғы деңгей

Өріс Міндетті Мақсаты
version Иә Схема нұсқасы: 1 немесе 2. Оқиғалар үшін сізге қажет 2.
trigger Иә Қолмен іске қосу, кесте бойынша немесе оқиға бойынша іске қосу.
source оқиғасыз қарапайым режим үшін Бір HTTP көзі немесе артефакт. Үшін event пайдаланылмайды.
destination қарапайым режим үшін Бір HTTP мақсаты, артефакт немесе MAX расталған чат.
steps жетілдірілген режим үшін Бірнеше көздер мен тағайындаулар.
transform Жоқ JavaScript өңдегіш параметрлері.
retry Жоқ Деректерді тағайындауға қайта жіберу.
conditions Жоқ Кіріс деректері, оқиғалар және қосылған артефактілер үшін шарттар.
artifacts Жоқ Алиаса компанияның артефакт атаулары, іске қосудың барлық кезеңдерінде қол жетімді.

Қолмен іске қосу және кесте үшін жұпты пайдаланыңыз source + destination, немесе массив steps. Оқиға үшін кіру оның payload болып табылады, сондықтан тек көрсетіңіз destination немесе тағайындау қадамдары. Кәдімгі өрістерді араластырыңыз және steps бір автоматтандыру мүмкін емес.

version

version: 1

Өріс міндетті болып табылады және жүйеге форматтың жаңа нұсқалары пайда болғаннан кейін конфигурацияны нақты түсіндіруге мүмкіндік береді.

trigger

Қолмен іске қосу

trigger:
  type: manual

Автоматтандыру батырма арқылы жүзеге асырылады Іске қосу. Өрістер cron және timezone бұл режимде пайдаланылмайды.

Кесте бойынша іске қосу

trigger:
  type: schedule
  cron: "30 8 * * 1-5"
  timezone: Europe/Moscow
Өріс Міндетті Мағынасы
type Иә manual, schedule немесе event.
cron үшін schedule Бес cron өрісі: минут, сағат, ай күні, ай, апта күні.
timezone Жоқ IANA уақыт белдеуінің атауы. Әдепкі бойынша Europe/Moscow.
event үшін event Жүйелік оқиғаның нақты атауы (employee.late) немесе қызмет оқиғасының толық коды (custom.service_42.report_ready).

Кесте мысалдары:

Тапсырма Cron
Күн сайын сағат 00:00-де 0 0 * * *
Күн сайын сағат 08:30-да 30 8 * * *
Жұмыс күндері сағат 21:00-де 0 21 * * 1-5
Әр сағат сайын 0 * * * *
Айдың бірінші күні сағат 03:15-те 15 3 1 * *

Кесте көрсетілген уақыт белдеуінде есептеледі және жүйе ішіндегі іске қосу уақыты UTC-де сақталады.

Жоспарлы іске қосуды 30 минутта бір реттен жиі емес орнатуға болады. Мысалы, */30 * * * * айталық, а */15 * * * * конфигурацияны тексеру кезінде қабылданбайды.

Кесте немесе оқиға бойынша бір іске қосу 60 секундтан аспауы мүмкін. Бұл мерзімге барлық көздерден деректерді алу, JavaScript өңдеу, барлық тағайындауларға жіберу, кідірістер және қайталап көру кіреді. Шектеу аяқталғаннан кейін орындау тоқтатылады және тарихта қате пайда болады. 30 минуттық Интервал тек триггерге қолданылады schedule; қолмен және тексеру іске қосулары олармен шектелмейді.

Оқиға бойынша іске қосу

version: 2
trigger:
  type: event
  event: employee.late

Бұл режимде кіріс деректері іс-шарада қамтылған, сондықтан source және қадамдар kind: source көрсету мүмкін емес. Тек өңдеуші және бір немесе бірнеше тапсырма қажет. Оқиғалардың толық тізімі және шарттардың мысалы бөлімде келтірілген Synchra24 оқиғалары бойынша іске қосу.

Жеке қызмет оқиғасы үшін қойындыдан толық кодты көрсетіңіз Оқиғалар, мысалы custom.service_42.report_ready. Редакторда компанияның қызметтер каталогынан оқиғаны таңдау мүмкіндігі бар. Қызметтің өзі жергілікті атауды шақырады report_ready арқылы synchra.emitEvent; бұл сынақ оқиғаның анықтамасын жасамайды. Тіркеу, шектеулер және конфигурацияның толық мысалы: Қызметтердің пайдаланушы оқиғалары.

source

Дереккөз-автоматтандыру деректерді алатын HTTP мекенжайы.

source:
  type: http
  method: GET
  url: https://api.example.com/v1/orders
  headers:
    Authorization: "Bearer ${secrets.SOURCE_TOKEN}"
    Accept: application/json
  response:
    format: json
    encoding: utf-8
Өріс Міндетті Мағынасы
type Иә Көзі мен мақсаты үшін — http немесе artifact.
method Жоқ HTTP әдісі. Әдепкі дереккөз үшін қолданылады GET.
url HTTP үшін Абсолютті мекен-жайы http:// немесе https://.
headers Жоқ 50 HTTP тақырыптарына дейін. Мәндерде құпияларды қолдануға болады.
body Жоқ Бастапқы сұрау денесі. Егер API сүзгіні POST арқылы алса қолданылады.
response HTTP үшін Жауапты оқу ережелері.

Егер берілген болса body. ол JSON ретінде жіберіледі. Егер қабылдаушы API тақырыпты қажет етсе Content-Type: application/json, оны қосыңыз headers анық. Кәдімгі GET үшін өрісті қоспаған дұрыс.

Дереккөз тек 200-ден 299-ға дейінгі HTTP күйінде сәтті деп саналады.

response

response:
  format: xml
  encoding: windows-1251
  options:
    delimiter: ";"
    header: true
Өріс Міндетті Мағынасы
format Жоқ json, xml, csv, tsv немесе text. Егер өріс бос болса, формат келесідей анықталады Content-Type.
encoding Жоқ utf-8 немесе windows-1251. Әдепкі бойынша UTF-8.
options.delimiter Жоқ CSV үшін бір бөлгіш таңба. Әдепкі бойынша ;.
options.header Жоқ CSV бірінші жолын тақырып деп санау керек пе. Әдепкі бойынша true.
options.root Жоқ Оқу үшін пайдаланылмайды; XML жасау кезінде қолданылады.

Толығырақ: Деректер форматтары.

transform

transform:
  type: javascript
  timeout_seconds: 2
Өріс Міндетті Мағынасы
type Жоқ Бос мән немесе javascript.
timeout_seconds Жоқ Функцияның орындалу шегі 1-ден 5 секундқа дейін. Әдепкі бойынша 2 секунд.

Егер type көрсетілмеген, деректер JavaScript түрлендірусіз тағайындалған жерге жіберіледі. Егер көрсетілген болса javascript, қойындыда Өңдеуші функция болуы керек transform(input, context).

destination

Тағайындау автоматтандырудың қорытынды деректерді қайда жіберетінін анықтайды: сыртқы HTTP қызметіне, артефакт немесе расталған MAX чатына.

destination:
  type: http
  method: POST
  url: https://receiver.example.com/v1/orders/import
  headers:
    Authorization: "Bearer ${secrets.DESTINATION_TOKEN}"
  request:
    format: json
    encoding: utf-8
Өріс Міндетті Мағынасы
type Иә Көзі мен мақсаты үшін — http немесе artifact.
method Жоқ HTTP әдісі. Әдепкі тағайындау үшін қолданылады POST.
url HTTP үшін Абсолютті HTTP немесе https мекенжайы.
headers Жоқ 50-ге дейін тақырып. Реттелетін Content-Type таңдалған формат түрімен ауыстырылады.
request HTTP үшін Нәтижені кодтау ережелері.
body Жоқ Айқын http тағайындалған дене; онсыз transform нәтижесі жіберіледі.

Тағайындау 200-ден 299-ға дейінгі HTTP мәртебесінде сәтті болып саналады. Тағайындалған жауап денесі пайдаланылмайды.

Artifact мақсаты

Http сұрауының орнына нәтижені synchra24-те сақтауға болады:

destination:
  type: artifact
  name: warehouse.stock

Бұл мақсат үшін тек рұқсат етіледі type және name. HTTP өрістері көрсетілмейді. Толығырақ: Автоматтандыру артефактілері.

Max-ке ортақ бот арқылы жіберу

Бұлтты Synchra24-те платформаның жалпы боты арқылы хабарландырулар жіберуге болады. Ол үшін ашыңыз Әкімші → автоматтандыру → MAX чаттары. Лицензия қажет API интеграциясы және интеграцияны басқару құқығы. Егер терезе боттың әлі қосылмағанын айтса, автоматтандыруды өшіріп, оператор ботты қосқаннан кейін параметрге оралыңыз.

Терезеде көрсетілген ботты топтық чатқа немесе MAX арнасына хабарлама жіберу құқығымен қосыңыз. Осы чатта пәрмен жіберіңіз /chatid алынған идентификаторды көшіріңіз. Synchra24-те қосылым атауы мен идентификаторын көрсетіңіз, басыңыз Кодты MAX-қа жіберіңіз. содан кейін бот хабарламасынан алты санды енгізіңіз. Код 10 минутқа созылады; бес қате әрекеттен кейін жаңасы қажет болады. Компанияға және чатқа бір сағат ішінде беске дейін код сұраулары бар, соның ішінде сәтсіз жіберулер. Компанияда 20-ға дейін байланыс болуы мүмкін.

Егер дайын кеңейтім MAX-ке хабарлама жіберсе, оны қоспас бұрын қосылымды тексеріңіз Max чаттары. Кеңейтімді орнатудың өзі чатты қоспайды. Егер қосылым тізімі жүктелмесе, бөлімді қайта ашыңыз; қайталанатын автоматтандыруды жасамаңыз.

Дайын кеңейтімдер үшін атау қалдырыңыз default. Егер хабарландырулар әртүрлі чаттарға өтуі керек болса, әртүрлі атаулармен қосылыстар жасаңыз және конфигурациядан қажетті атауды таңдаңыз. Жалпы бот таңбалауышын енгізудің және сатушыға берудің қажеті жоқ. Байланыс мәліметтері тек өз компаниясында қол жетімді.

Автоматтандыруды жасаушы үшін тағайындау келесідей:

destination:
  type: max
  name: default

Бұл тағайындауда тек рұқсат етіледі type және name. Кодта чат идентификаторы мен токен орнатылмаған. Өңдеуші Қарапайым мәтінді 4000 таңбаға дейін қайтарады. Бұлтты веб-нұсқадағы ағымдағы компанияның бөлімдеріне бір немесе екі сілтеме түймелерінің бір жолына рұқсат етіледі:

function transform(input, context) {
  return {
    text: 'В Synchra24 появился новый инцидент.',
    attachments: [{
      type: 'inline_keyboard',
      payload: {buttons: [[{
        type: 'link', text: 'Открыть инциденты',
        url: 'https://app.synchra24.com/activity/' + context.provider_id + '/incidents'
      }]]}
    }]
  };
}

Тексеруді іске қосу өңдеушінің нәтижесін MAX-қа жібермей көрсетеді. Қосар алдында расталған чат қажет. Нақты оқиғадан кейін хабарлама мен автоматтандыру тарихын тексеріңіз. Табыс дегеніміз-адамның оқуы емес, MAX API-ді растау. MAX үшін қайта жіберу тіпті орнату кезінде де автоматты түрде орындалмайды retry: белгісіз жауап хабарламаның жіберілгенін білдіруі мүмкін. Қайта әрекет жасамас бұрын чатты тексеріңіз.

Хабарландыруларды тоқтату үшін автоматтандыруды өшіріңіз немесе оның қосылымын жойыңыз Max чаттары. Егер бұл атау бірнеше автоматтандыруды қолданса, жіберу олардың әрқайсысында тоқтайды. Жіберілген хабарламалар жойылмайды. Ботты чаттан жойғаннан кейін байланыс кері қайтарылады; қайта жұмыс істеу үшін чатты қайта растаңыз. Жалпы ботты ауыстыру жаңа растауды қажет етеді. Жеке қорап серверлеріне сілтемелер осы мақсатта қолдау көрсетілмейді.

request

Құрылым сәйкес келеді response:

request:
  format: csv
  encoding: windows-1251
  options:
    delimiter: ";"

Егер пішім көрсетілмесе, нәтиже JSON ретінде жіберіледі.

retry

retry:
  attempts: 3
  delay_seconds: 10
Өріс Ауқымы Мағынасы
attempts 0-ден 5-ке дейін Жіберу әрекеттерінің жалпы саны. Мәндер 0 және 1 бір әрекетті білдіреді.
delay_seconds 0-ден 3600-ге дейін Секундтардағы әрекеттер арасындағы үзіліс.

Қайталаулар http тағайындауларына жіберуді білдіреді. Жалпы MAX боты үшін автоматты қайталау жоқ. Дереккөзге қате сұрау ағымдағы іске қосу шеңберінде қайталанбайды.

YAML толық мысалы

version: 1

trigger:
  type: schedule
  cron: "0 2 * * *"
  timezone: Europe/Moscow

source:
  type: http
  method: GET
  url: https://accounting.example.com/export/employees
  headers:
    X-API-Key: "${secrets.ACCOUNTING_API_KEY}"
  response:
    format: xml
    encoding: windows-1251

transform:
  type: javascript
  timeout_seconds: 3

destination:
  type: http
  method: POST
  url: https://hr.example.com/api/employees/import
  headers:
    Authorization: "Bearer ${secrets.HR_TOKEN}"
  request:
    format: json
    encoding: utf-8

retry:
  attempts: 3
  delay_seconds: 15

JSON-да бірдей мысал

{
  "version": 1,
  "trigger": {
    "type": "schedule",
    "cron": "0 2 * * *",
    "timezone": "Europe/Moscow"
  },
  "source": {
    "type": "http",
    "method": "GET",
    "url": "https://accounting.example.com/export/employees",
    "headers": {
      "X-API-Key": "${secrets.ACCOUNTING_API_KEY}"
    },
    "response": {
      "format": "xml",
      "encoding": "windows-1251"
    }
  },
  "transform": {
    "type": "javascript",
    "timeout_seconds": 3
  },
  "destination": {
    "type": "http",
    "method": "POST",
    "url": "https://hr.example.com/api/employees/import",
    "headers": {
      "Authorization": "Bearer ${secrets.HR_TOKEN}"
    },
    "request": {
      "format": "json",
      "encoding": "utf-8"
    }
  },
  "retry": {
    "attempts": 3,
    "delay_seconds": 15
  }
}

Редактордағы пішімдеу түймесі YAML немесе JSON -. оқылатын көрініске әкеледі. Жүктеу түймесі дайын файлды таңдауға мүмкіндік береді .yaml, .yml немесе .json өлшемі 256 КБ дейін.

Барлық кезеңдердегі кіріс артефактілері

Қосыңыз artifacts: {settings: service.settings} конфигурацияның түбірінде. Мәндер қол жетімді source, conditions, transform және destination. Дереккөз type: artifact с name сақталған мәнді қайтарады; http қолдайды ${artifacts.settings.field} URL, тақырыптар және JSON-да. В steps тағайындау таңдай алады input: ${artifacts.settings}. Шарттар қолданылады path: artifacts.settings.field немесе input.field; value қосылған артефактіге сілтеме жасай алады. Өңдегіште оқыңыз context.artifacts.settings.

Кіріс мәндері іске қосу басталғанға дейін бір рет жүктеледі, оның ішінде тексеру. Артефакт болмаған кезде іске қосу қатемен аяқталады. Оқиғалар үшін дереккөз оқиғаның конверті болып қалады, бірақ блок artifacts дәл осылай жұмыс істейді. Толық мысал, типтік ережелер, шектеулер мен қателер-в артефактілер автоматтандыру.

Zip автоматтандыру үлгісін импорттау және экспорттау

Веб-әкімшіде ашыңыз Автоматтандыру → ZIP үлгісінен. Буманы жүктеп алып, көрсетілген опцияларды тексеріңіз: шаблон идентификаторы мен нұсқасы, іске қосу түрі, құпия айнымалыларға сілтемелер, артефактілер және оқиға. Жасамас бұрын атауды өзгертуге болады. Импорттау үшін сізге әкімшіге кіру, лицензия қажет API және admin_edit_provider_integrations; AI лицензиясы қажет емес.

Түйме Автоматтандыруды жасаңыз қосады жаңа өшірулі жазу. Қолданыстағы автоматика шаблонның аты немесе идентификаторы бірдей болса да ауыстырылмайды. Импорттау кезінде Код, HTTP сұраулары мен тапсырмалары орындалмайды; кесте мен оқиғалар pipeline іске қосылмайды. Редакторда мекен-жайларды, уақыт белдеуін, құпия айнымалыларды, артефактілерді және ағымдағы компанияның оқиға кодын тексеріңіз. Содан кейін қажетті тексерулерді орындаңыз және автоматтандыруды бөлек қосыңыз.

Редактор қақпағындағы стандартты жүктеу түймесі — Zip автоматтандыру үлгісін экспорттау - сақталмаған өңдеулерді қоса, ағымдағы конфигурацияны, өңдегішті, атауды және сипаттаманы орайды. Экспорт автоматтандырудағы өзгерістерді сақтамайды және оны іске қоспайды.

Пакет форматы

automation.json
pipeline.yaml
transform.js
{
  "format": "synchra.automation-template",
  "schema_version": 1,
  "template": {
    "id": "com.example.exchange",
    "version": "1.0.0",
    "description": "Обмен данными с учётной системой"
  },
  "automation": {
    "name": "Обмен данными",
    "description": "Получить данные, преобразовать и сохранить результат"
  },
  "files": {
    "pipeline": "pipeline.yaml",
    "transform": "transform.js"
  }
}

schema_version - zip форматының нұсқасы; template.version - белгілі бір үлгінің нұсқасы; version ішінде pipeline схемасының YAML нұсқасы бар. Бұл үш мәннің мақсаты әртүрлі. Редакторды экспорттау жергілікті идентификаторды пайдаланады local.automation және нұсқасы 1.0.0; тарату үшін меншікті мәндерді орнатыңыз. Идентификатор-3-128 кіші латын әріптері, сандар, нүктелер, _ немесе -, әріптен басталады; нұсқасы келесідей 1.0.0, жұрнаққа рұқсат етіледі -beta.1.

automation.name міндетті: 2 таңбадан 100 байтқа дейін UTF-8. automation.description қосымша, 4000 таңбаға дейін. Үлгі сипаттамасы-2000 таңбаға дейін. Файлдар files міндетті: конфигурация .yaml, .yml немесе .json және жеке өңдеуші .js. JavaScript түрлендірусіз pipeline үшін өңдеуші файлын бос қалдырыңыз. Өріс transform.script қажет емес: код редактордағыдай бөлек файлда сақталады.

Кірістірілген каталогтарға және бір ортақ қалтаға рұқсат етіледі automation.json. Жолдар пакеттің конфигурациясына қатысты қарастырылады. Қосуға болады README.md, LICENSE және LICENSE.txt; macOS қызметтік файлдары еленбейді. Басқа файлдар импортталмайды.

Қол жетімділік және шектеулер

ZIP-дейін 1 МиБ, automation.json - дейін 64 КиБ, конфигурация және өңдеуші-дейін Әрқайсысы 256 КиБ. Каталогтармен бірге барлығы 32 жазбаға дейін және 640 КиБ-ке дейін декларацияланған жиынтық Өлшем. UTF-8 қажет. Парольсіз, ZIP64, бірнеше томдар мен символдық сілтемелерсіз Store/DEFLATE бар тұрақты ZIP-ке қолдау көрсетіледі. Абсолютті жолдарды қолдануға болмайды, .., кері сызаттар және қайталанатын атаулар. Нақты өлшемдер мен CRC тексеріледі, zip каталогында дұрыс емес мөлшерде болса да, қораптан шығару шектеулі.

Жүйе жасамас бұрын мұрағат пен автоматтандыру параметрлерін тексереді. Егер қате табылса, жазба жасалмайды: буманы түзетіп, терезені жаппай қайта таңдауға болады. Жеке YAML немесе JSON файлы редактордағы конфигурацияны жүктеу батырмасымен жүктеледі.

Қоймадан құпия айнымалылардың мәндері, артефактілердің мазмұны, іске қосу тарихы, жазба идентификаторлары және авторлар экспортталмайды. Конфигурацияда сілтемелер қалады ${secrets.NAME}, артефакт атаулары және оқиға коды. Көрсетілген артефактілер тізіміне оқу және тапсырмалар кіреді: кіріс артефакті болуы керек, ал тағайындалған артефакт әдеттегі сәтті іске қосу арқылы жасалады. Мұндай тәуелділіктер автоматты түрде жасалмайды. Қызмет оқиғасы үшін осы компанияның қызмет кодын тексеріп, қажет болған жағдайда таңдаңыз.

Дереккөздер өңдеусіз экспортталады. Егер мекен-жай, компания идентификаторы немесе құпия мән тікелей YAML немесе JavaScript-те жазылса, олар файлдарда қалады. Мұрағат берілмес бұрын құпия мәндерді айнымалы сілтемелермен ауыстырыңыз. Ту enabled, provider_id, белгіленген жазбаның құпия мәндері және басқа өрістері automation.json рұқсат етілмейді.

ZIP үлгісі немесе дүкен

ZIP үлгісі автоматтандырудың бөлек көшірмесін жасайды. Импортталғаннан кейін оны өз компаниясына орнату керек; сатушының жаңартулары мұндай көшірмеге байланбайды.

Егер сізге жарияланымдары мен жаңартулары бар дайын өнімдер қажет болса, қолданыңыз кеңейту дүкені.