Regulile Vision App Maker lucrează cu JSON printr-un set de operatori și apelează API-uri HTTP prin plugin-ul RestClient. În interiorul regulii, JSON-ul este un obiect pe care regula îl construiește și îl interoghează. Devine text o singură dată, la graniță, când este trimis unui plugin.
Cum funcționează
Un schimb obișnuit cu un API extern are cinci pași.
- Construiești cererea cu
JsonObjectșiJsonArray. - O serializezi o singură dată cu
JsonText. - O trimiți prin plugin-ul RestClient.
- Parsezi răspunsul cu
JsonParse. - Citești valorile cu
JsonValuesauJsonValues.
Tipurile se păstrează la ambele capete: numerele rămân numere, valorile boolean rămân boolean, iar null rămâne null. Escaparea ghilimelelor și a diacriticelor este făcută de serializator.
Operatori JSON
| Operator | Rezultat | Comportament |
|---|---|---|
JsonObject(cheie, valoare, ...) | Obiect JSON | Valorile pot fi scalari, entități, liste sau alte obiecte JSON. Null() scrie explicit null. La chei duplicate câștigă ultima. |
JsonArray(valoare, ...) | Array JSON | Fiecare operand devine un element. O listă pasată ca operand unic devine array imbricat. |
JsonText(json, [indentat]) | Text JSON | Compact implicit; cu true, formatat pentru loguri. |
JsonParse(text) | Obiect sau array interogabil | Text gol sau null returnează null. Rezultatul funcționează cu Len, Iterate, First și Index. |
JsonValue(json, cale, [implicit]) | Valoare tipizată | Acceptă obiect sau text JSON. Returnează prima potrivire; valoarea implicită acoperă căile lipsă. |
JsonValues(json, cale) | Listă tipizată | Returnează toate potrivirile; listă goală dacă nu există potriviri. |
ToJson(CustomType) | Obiect sau array | Transformă o valoare de tip custom type în JSON. |
Căi
profile.agecitește o proprietate.roles[0]citește un element de array după index.$[?(@.role=='UX Designer')].namefiltrează un array de obiecte;@este elementul curent, caCurrentValue.
Rețete uzuale
- Listă de entități în array JSON:
Iterateconstruiește câte unJsonObjectpentru fiecare element, iarJsonTextserializează colecția ca array. Când numele membrilor coincid cu cheile API-ului, ajungeJsonText(ToJson(Lista)). - Căutarea unui element după o proprietate:
Firstcu o condițieJsonValue(CurrentValue, ...)se potrivește valorilor care vin dintr-un parametru. Pentru interogări fixe, filtrul JSONPath este mai compact.
Plugin-ul RestClient
RestClient este un client HTTP generic, cu autorizare integrată. Suportă orice verb HTTP și orice tip de conținut. Returnează răspunsul brut; un status 404 sau 500 nu aruncă excepție, iar regula decide ce face.
Apelarea
Plugin-ul primește HttpRequest(url, metodă, [corp], [content type], [headere], [autorizare], [timeout]). O regulă îl apelează cu CallPluginWithParams și transmite headerele și autorizarea ca text JSON. Ieșirile se citesc după index:
| Ieșire | Conținut |
|---|---|
| #0 | Codul de status HTTP (200, 404...) |
| #1 | Corpul răspunsului, ca text |
| #2 | Headerele răspunsului, ca JSON |
| #3 | Indicator de succes, true pentru statusurile 2xx |
De obicei regula verifică #0, apoi citește corpul cu JsonValue(JsonParse(#1), ...). Pentru un status neașteptat se poate opri cu Throw și un mesaj formatat.
Corpul cererii după content type
| Content type | Corp |
|---|---|
| application/json (implicit) | Text JSON |
| application/x-www-form-urlencoded | Un obiect cu câmpurile formularului; codarea URL o face plugin-ul |
| multipart/form-data | Un obiect cu fields și files; conținutul fișierelor în Base64, obținut cu FileToBase64 |
Autorizare
Autorizarea este un obiect JSON cu câmpul type:
basic, cu nume de utilizator și parolă;bearer, cu un token;apikey, cu numele headerului și valoarea lui.
Pentru alte scheme, regula setează direct headerul Authorization prin parametrul de headere.
RestClient și MakeHttpCall
MakeHttpCall, un plugin System, trimite URL, metodă, corp JSON și headere și returnează răspunsul. RestClient adaugă:
- Content-Type corect pentru fiecare tip de corp;
- trimiterea de formulare și fișiere;
- codul de status și headerele răspunsului ca ieșiri;
- timeout pe fiecare apel.
