A lekérdezési paraméterek beállítása

Ismerje meg a lekérdezési paraméterekkel való munka alapjait a HTTP-csatlakozófunkciókban az API dokumentációval összhangban.

A lekérdezési paraméterek lehetővé teszik a csatlakozófüggvények eredményeinek finomítását és testre szabását. Használja a paramétereket rendezéshez, szűréshez, korlátok beállításához, index eltolásához és még sok máshoz. Ez a cikk a Tulip Table API paramétereit használja, de más API-k eltérő paraméterkövetelményekkel rendelkezhetnek. Ellenőrizze a dokumentációt, hogy a helyes szintaxist és specifikációkat használja.

Szűrőkkel történő lekérdezés

A szűrők nagyon hasznosak lehetnek ahhoz, hogy csak az Önt érdeklő adatokat nyerje ki. Ezek a szűrők néha kicsit trükkösek lehetnek a szintaxisukkal. Az alábbiakban a rekordok GET-kérelmének példáján, majd egy teljes példán keresztül ismertetjük, hogy az egyes szűrők hogyan alakulnak.

Az egyénimezők mezőnevei elé mindig egy ötjegyű karakterlánc-azonosító kerül. Ezeket legkönnyebben egy GET all kérés után lehet megtalálni, hogy ellenőrizni lehessen a mező valódi nevét.

• Pl. "mező"="maytq_scrap_count"

Az argumentumértékek gyakran egyszerűek. Ha szöveges értékről van szó, mindenképpen tegye idézőjelbe.

• Pl. "arg":15

Egyeztesse a használni kívánt függvénytípussal.

• Pl. "functionType": "greaterThan"

Egy teljes kérés erre a célra valahogy így nézhet ki:

{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

Hogyan találja meg a lekérdezési paramétereket a dokumentációban

A kérelemhez rendelkezésre álló lekérdezési paraméterek megtalálásához navigáljon az API dokumentációjához. Ha a Tulip Table API-t használja, a dokumentációt a következő címen találja: your-instance.tulip.co/apiDocs. Válassza ki a használni kívánt kérést, majd görgessen le a Paraméterek fülre.

Minden egyes módszer saját paraméterkészlettel rendelkezik, azonban nem minden kéréshez tartoznak paraméterek. Győződjön meg róla, hogy a dokumentációban előzetesen megjegyzi, hogy mi áll rendelkezésre.

A lekérdezési paraméterek szintaxisa

A paraméterek szintaxisának lekérdezése a lekérdezési karakterlánc formátumára támaszkodik. Ez a formátum értékeket rendel a megadott paraméterekhez, maga a lekérdezési karakterlánc pedig az URL része.

A Csatlakozófunkció-szerkesztőben kattintson a Paraméter hozzáadása gombra egy új lekérdezési paraméter létrehozásához.

Egy lekérdezési paraméter két részből áll: egy kulcsból és egy értékből. A kulcs a paraméter neve, az érték pedig az az információ, amely a paramétert az eredményekhez beállítja.

A lekérdezési paraméterek szintaxisában a Dot Notation használatos, amely pontosan meghatározza a paraméter típusát. Győződjön meg arról, hogy az írásmód megfelel a másik rendszer API-szabványának.

Közös paraméterek alkalmazása a csatlakozófüggvényekhez

Ahhoz, hogy egy paramétert beállítson a csatlakozófüggvényéhez, először azonosítsa a használni kívánt paramétert az API dokumentációban. A paramétereknek eltérő követelményei vannak, ezért nézzük át, hogy ezek hogyan néznek ki.

:::(Info) (MEGJEGYZÉS) A folytonosság kedvéért az alábbi példák mindegyikében ugyanazt a kérést API Call fogjuk használni. Ez az a GET-kérés, amely a Tulip Table API-n keresztül lekérdezi egy tulip Table-ben lévő rekordok listáját. Más, Ön által használt API-k eltérő specifikációkkal rendelkeznek a paraméterekre vonatkozóan, mindenképpen nézze meg az API dokumentáció követelményeit. :::

Limitek

A Limits egy kijelölt felső határt állít be a visszaküldött eredményekre. Vegye figyelembe, hogy egyes korlátok alapértelmezett beállításokkal rendelkeznek, ezért mindenképpen nézze meg az API dokumentációját a kezdeti érték megértéséhez.

PéldaA csatlakozófüggvény futtatásakor legfeljebb 70 rekordot szeretnénk kapni. Szerencsére a limit alapértelmezett értéke ebben a kérésben 10, a legmagasabb pedig 100. A lekérdezési paraméter szintaxisának a következőképpen kell kinéznie:

Szűrők

A szűrők a paraméter megadott információi alapján választják szét és finomítják az eredményeket.

A szűrők három részből állnak, amelyeket külön paraméterekben kell megírni:

• Mező - a táblázat oszlopának neve.
• Funkció típusa - az összehasonlító függvény típusa
• Argumentum - az az érték, amellyel az eredményeket összehasonlítja

Minden szűrő 3 részből áll, és minden teljes szűrő egy Object. Az egyes kulcsok megírásához a pontjelölést használva adja meg a paraméter típusát ('filter'), a szűrő számát (0-tól n-ig) és a szűrő részét ('field', 'functionType' vagy 'arg'). A szűrő mindhárom részéhez kell paramétert adni.

PéldaBiztosítani akarjuk, hogy a csatlakozófüggvény eredményei csak egy adott mező (eubmc_value) értékeit mutassák, amelyek megegyeznek a függvény megadott bemeneti értékével (consumable). Mivel ez az első szűrőnk a függvény paramétereiben, a szűrő száma 0. Ez azt jelenti, hogy ennek a szűrőnek minden kulcsa 'filter.0'-val kezdődik. Ennek a szűrőnek a szintaxisának a következőképpen kell kinéznie:

Rendezés

Az eredmények rendezése a paraméter információi alapján rangsorolja a nézetet. A rendezett eredmények határozzák meg, hogy melyek szerepelnek az összesítésben. Többféle rendezési funkciót is használhat, azonban az opciók sorrendje határozza meg a rendezési prioritást.

A rendezési függvényeknek két része van:

• sortBy - az a mező, amely alapján az eredményeket rendezni kívánja.
• sortDir - a rendezés iránya, növekvő (asc) vagy csökkenő (desc).

Minden egyes rendezési függvény 3 részből áll. Az egyes kulcsok írásához pontjelöléssel írjuk le a paraméter típusát ('sortOptions'), a rendezési számot (0-tól n-ig) és a rendezési argumentumot ('sortBy' vagy 'sortDir'). A rendezési függvény mindhárom részének kell paraméter, hogy működjön.

PéldaAzt szeretnénk, hogy a csatlakozó függvény eredményei a legfrissebb frissített mező szerint legyenek növekvő sorrendben rendezve. Mivel ez az első rendezési függvényünk, a rendezési szám 0. Ez azt jelenti, hogy a rendezés mindkét kulcsa a 'sortOptions.0'-val kezdődik. A sortBy kulcs értéke egy speciális érték ('_updatedAt'), amely az API dokumentációból származik a frissített mezők rendezéséhez. Ezeknek a paramétereknek a szintaxisának a következőképpen kell kinéznie:

Offsets

Az Offsets határozza meg, hogy a visszaadott eredmény milyen indexről induljon. Ezt a paramétert a lapozáshoz használjuk, nem pedig a rekordok sorrendjéhez, amelyet a rendezési paraméterek határoznak meg. A paraméter értékének egész számnak kell lennie, amely nagyobb vagy egyenlő 0-val.

PéldaCsak az 5. pozíció utáni rekordokat szeretnénk megtekinteni, hogy ne az első 5 találatot lássuk. A lekérdezési paraméter szintaxisának a következőképpen kell kinéznie:

Szűrő aggregátorok

A szűrőaggregátorok határozzák meg, hogy a paraméterekben szereplő szűrők hogyan kombinálódnak. A két választható érték az 'any' és az 'all'. Az 'all' érték azt jelenti, hogy az összes szűrőnek tartalmaznia kell egy rekordot ahhoz, hogy a rekord bekerüljön az eredmények közé. Az "any" érték azt jelenti, hogy legalább az egyik szűrőnek meg kell egyeznie egy rekorddal ahhoz, hogy az szerepeljen az eredmények között. Az alapértelmezett érték az 'all', függetlenül attól, hogy beállította-e a paramétert vagy sem.

PéldaA lekérdezési paraméterekben egy sor szűrő van, de csak az egyik szűrőnek kell igaznak lennie ahhoz, hogy a rekordok megfeleljenek a kérésünknek. A lekérdezési paraméter szintaxisának a következőképpen kell kinéznie:

Több szűrő

Bizonyos esetekben előfordulhat, hogy több szűrőt is ellenőrizni kell a táblázatban. Ebben az esetben a szűrők objektumhoz többszöröseket is hozzáadhat. Ez valahogy így nézhet ki:

},{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"},{"field": "maytq\_scrap\_reason", "arg": "scratch", "functionType": "equal"}]

További olvasmányok

• A HTTP-konnektorok áttekintése
• Hogyan hozzunk létre és konfiguráljunk egy HTTP-csatlakozó funkciót?
• A táblázat API használata