Фарматы дадзеных
Праца з JSON, XML, CSV, TSV і тэкстам, кадыроўкамі UTF-8 і Windows-1251, уключаючы дадзеныя з 1С.
Аўтаматычны пераклад
Аўтаматызацыі ўмеюць чытаць і ствараць JSON, XML, CSV, TSV і звычайны тэкст. Фармат наладжваецца асобна для кожнай крыніцы і прызначэння.
Адказ адной крыніцы не павінен перавышаць 5 МБ.
JSON
response:
format: json
encoding: utf-8
JSON пераўтворыцца ў звычайныя значэнні JavaScript:
- аб'ект-у аб'ект;
- масіў-у масіў;
- радкі, лікі, лагічныя значэнні і
nullзахоўваюць тып.
Прыклад уваходнага адказу:
{
"items": [
{ "id": 17, "amount": 1250.5 }
]
}
У апрацоўшчыку дадзеныя даступныя як input.items.
Пры адпраўцы ў JSON вынік transform серыялізуецца аўтаматычна. Ня трэба выклікаць JSON.stringify перад вяртаннем.
XML
response:
format: xml
encoding: windows-1251
XML пераўтворыцца ў аб'ект. Каранёвы элемент становіцца першым ключом, даччыныя элементы-палямі аб'екта.
Зыходны XML:
<?xml version="1.0" encoding="UTF-8"?>
<Employees>
<Employee active="true">
<Id>42</Id>
<Name>Анна Смирнова</Name>
</Employee>
<Employee active="false">
<Id>57</Id>
<Name>Павел Орлов</Name>
</Employee>
</Employees>
Аб'ект у JavaScript:
{
Employees: {
Employee: [
{
"@attributes": { active: "true" },
Id: "42",
Name: "Анна Смирнова"
},
{
"@attributes": { active: "false" },
Id: "57",
Name: "Павел Орлов"
}
]
}
}
Правілы пераўтварэнні:
- атрыбуты знаходзяцца ў
@attributes; - тэкст элемента знаходзіцца ў
#text, калі ў элемента адначасова ёсць тэкст і даччыныя элементы; - адзін даччыны элемент становіцца аб'ектам або радком;
- некалькі элементаў з аднолькавым імем становяцца масівам;
- колькасці і лагічныя значэння з XML паступаюць радкамі, таму іх трэба відавочна пераўтварыць;
- DTD і XML-дырэктывы, здольныя падключаць знешнія сутнасці, забароненыя;
- максімальная глыбіня ўкладзенасці XML - 100 узроўняў.
XML з 1С
Выгрузкі 1С часта выкарыстоўваюць Windows-1251 і могуць вярнуць адзін элемент замест масіва, калі запіс ўсяго адна. Бяспечны апрацоўшчык ўлічвае абодва варыянты:
function transform(input, context) {
const raw = input.Employees?.Employee;
const employees = Array.isArray(raw) ? raw : raw ? [raw] : [];
return employees.map((employee) => ({
externalId: String(employee.Id || ""),
fullName: String(employee.Name || "").trim(),
active: employee["@attributes"]?.active === "true",
}));
}
Адпраўка XML
request:
format: xml
encoding: utf-8
options:
root: Employees
options.root задае каранёвай элемент. Калі вынік апрацоўшчыка-аб'ект з адзіным верхнім ключом, гэты ключ выкарыстоўваецца як корань аўтаматычна.
CSV
response:
format: csv
encoding: windows-1251
options:
delimiter: ";"
header: true
| Наладжваньне | Безумоўна | Прызначэнне |
|---|---|---|
delimiter |
; |
Адзін сімвал-падзельнік. |
header |
true |
Першы радок змяшчае назвы калонак. |
CSV з загалоўкам:
id;name;amount
1;Первый заказ;350
2;Второй заказ;420
Пераўтворыцца ў:
[
{ id: "1", name: "Первый заказ", amount: "350" },
{ id: "2", name: "Второй заказ", amount: "420" }
]
Значэння CSV заўсёды з'яўляюцца радкамі. Для разлікаў выкарыстоўвайце Number(value).
Калі header: false, ўваходныя дадзеныя будуць масівам радкоў:
[
["1", "Первый заказ", "350"],
["2", "Второй заказ", "420"]
]
Адпраўка CSV
Каб адправіць CSV, апрацоўшчык павінен вярнуць масіў аб'ектаў:
function transform(input, context) {
return input.items.map((item) => ({
id: item.id,
name: item.name,
amount: item.amount,
}));
}
Калонкі фармуюцца па ключах першага аб'екта. Таму ва ўсіх радкоў лепш вяртаць аднолькавы набор палёў.
TSV
TSV працуе так жа, як CSV, але выкарыстоўвае сімвал табуляцыі ў якасці падзельніка.
response:
format: tsv
encoding: utf-8
Для TSV Значэнне options.delimiter не патрабуецца.
text
response:
format: text
encoding: utf-8
Апрацоўшчык атрымлівае радок без дадатковага разбору.
function transform(input, context) {
const lines = String(input)
.split("\n")
.map((line) => line.trim())
.filter(Boolean);
return { lines };
}
Пры адпраўцы ў фармаце text вынік пераўтворыцца ў радок.
Аўтаматычнае вызначэнне фармату
Калі response.format не зададзены, Synchra24 аналізуе загаловак Content-Type:
- значэнне з
json— JSON; - значэнне з
xml— XML; - значэнне з
csv— CSV; - астатнія адказы-text.
Для прадказальнай рабочай інтэграцыі фармат лепш паказваць відавочна, асабліва калі знешні сэрвіс вяртае няправільны або агульны Content-Type.
Кадоўкі
Падтрымліваць:
utf-8абоutf8;windows-1251абоcp1251.
Калі encoding не пазначаны, выкарыстоўваецца UTF-8.
Кадоўка ўжываецца пасля атрымання адказу і перад разборам фармату. Пры адпраўцы парадак зваротны: спачатку фармуецца JSON, XML, CSV, TSV або тэкст, Затым вынік кадуецца.
Як выбраць фармат
- Для сучасных API выкарыстоўвайце JSON.
- Для 1С і старых уліковых сістэм часта патрэбныя XML, CSV і Windows-1251.
- Для таблічнай выгрузкі без складанай ўкладзенасці падыходзяць CSV або TSV.
- Для нестандартнага плоскага адказу выкарыстоўвайце text і разбярыце радок у апрацоўшчыку.
Тыпы ўваходных артэфактаў
Артэфакт заўсёды захоўвае JSON незалежна ад фармату знешняй сістэмы. Поўная падстаноўка ${artifacts.alias.field} у JSON-целе захоўвае тып значэння; падстаноўка ўнутры радка ператварае яго ў тэкст. Для URL і загалоўкаў, поўнае значэнне павінна быць радком. Для масіваў выкарыстоўвайце лікавы сегмент шляху, напрыклад ${artifacts.settings.items.0.id}. Падключэнне артэфактаў.