A lekérdezési paraméterek beállítása
  • 04 Nov 2023
  • 4 Elolvasandó percek
  • Közreműködők

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


Article Summary

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.

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 lapra.

Parameters in API Docs.png

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.

Query Parameters - Add Parameter.png

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:

Query Parameters - Limits.png

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:

Query Parameters - Filters.png

Rendezés

Az eredmények rendezése a nézetet a paraméter információi alapján rangsorolja. 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:

Query Parameters - Sorting.png

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:

Query Parameters - Offset.png

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:

Query Parameter - Filter Aggregators.png

További olvasmányok


Hasznos volt ez a cikk?