Jak ustawić parametry zapytania

Poznaj podstawy pracy z parametrami zapytań w funkcjach konektora HTTP zgodnie z dokumentacją API.

Parametry zapytań pozwalają doprecyzować i dostosować wyniki funkcji konektora. Za pomocą parametrów można sortować, filtrować, ustawiać limity, przesuwać indeks i nie tylko. W tym artykule wykorzystano parametry API Tulip Table, ale inne interfejsy API mogą mieć inne wymagania dotyczące parametrów. Sprawdź dokumentację, aby upewnić się, że używasz poprawnej składni i specyfikacji.

Wysyłanie zapytań za pomocą filtrów

Filtry mogą być bardzo przydatne do wyodrębniania tylko interesujących nas danych. Filtry te mogą czasami być nieco skomplikowane pod względem składni. Poniżej przedstawiono sposób tworzenia każdego z nich w przykładzie żądania GET dla rekordów, a następnie pełny przykład.

Nazwy pól niestandardowych są zawsze poprzedzone pięciocyfrowym identyfikatorem łańcuchowym. Można je najłatwiej znaleźć po żądaniu GET all, aby sprawdzić prawdziwą nazwę pola.

• Np. "field"="maytq_scrap_count".

Wartościargumentów są często proste. Jeśli jest to wartość tekstowa, należy umieścić ją w cudzysłowie.

• Np. "arg":15

Dopasuj typ funkcji, której chcesz użyć.

• Np. "functionType": "greaterThan"

Pełne żądanie może wyglądać mniej więcej tak:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

Jak znaleźć parametry zapytania w dokumentacji

Aby zlokalizować dostępne parametry zapytania dla żądania, przejdź do dokumentacji API. Jeśli korzystasz z interfejsu API Tulip Table, możesz znaleźć dokumentację pod adresem: your-instance.tulip.co/apiDocs. Wybierz żądanie, którego chcesz użyć, a następnie przewiń w dół do karty Parametry.

Każda metoda ma swój własny zestaw parametrów, jednak nie każde żądanie ma powiązane parametry. Upewnij się, że wcześniej zwróciłeś uwagę na to, co jest dostępne w dokumentacji.

Składnia parametrów zapytania

Zapytania o składnię parametrów opierają się na formacie ciągu zapytania. Format ten przypisuje wartości do określonych parametrów, przy czym sam ciąg zapytania jest częścią adresu URL.

W edytorze funkcji konektora kliknij przycisk Dodaj parametr, aby utworzyć nowy parametr zapytania.

Parametr zapytania składa się z dwóch części: klucza i wartości. Klucz to nazwa parametru, a wartość to informacja, która ustawia parametr dla wyników.

Składnia parametrów zapytania wykorzystuje Dot Notation, który określa dokładny typ parametru. Upewnij się, że wielkość liter jest zgodna ze standardem API innego systemu.

Stosowanie wspólnych parametrów do funkcji łącznika

Aby ustawić parametr w funkcji konektora, należy najpierw zidentyfikować parametr, którego chcesz użyć w dokumentacji API. Parametry mają różne wymagania dla każdego z nich, więc przyjrzyjmy się, jak wyglądają.

:::(Info) (UWAGA) Dla zachowania ciągłości będziemy używać tego samego żądania API Call w każdym z poniższych przykładów. Jest to żądanie GET, które pobiera listę rekordów w tabeli tulipanów za pośrednictwem interfejsu API tabeli tulipanów. Inne używane interfejsy API będą miały inne specyfikacje parametrów, należy zapoznać się z wymaganiami dokumentacji API :::

Limity

Limity ustawiają określony limit dla zwracanych wyników. Należy pamiętać, że niektóre limity mają ustawienia domyślne, więc należy sprawdzić dokumentację API, aby zrozumieć wartość początkową.

PrzykładChcemy uzyskać nie więcej niż 70 rekordów po uruchomieniu funkcji łącznika. Na szczęście domyślną wartością limitu w tym zapytaniu jest 10, a najwyższą 100. Składnia parametru zapytania powinna wyglądać następująco:

Filters

Filtry oddzielają i zawężają wyniki na podstawie podanych informacji w parametrze.

Filtry składają się z trzech części, które należy zapisać w poszczególnych parametrach:

• Field - nazwa kolumny w tabeli
• Function Type - typ funkcji porównania
• Argument - wartość, do której porównywane są wyniki.

Każdy filtr składa się z 3 części, a każdy kompletny filtr jest obiektem. Używając notacji kropkowej do zapisu każdego klucza, określ typ parametru ("filter"), numer filtra (od 0 do n) i część filtra ("field", "functionType" lub "arg"). Musi istnieć parametr dla wszystkich trzech części filtra.

PrzykładChcemy upewnić się, że wyniki funkcji łącznika pokazują tylko wartości określonego pola (eubmc_value), które są równe określonej wartości wejściowej (consumable) funkcji. Ponieważ jest to nasz pierwszy filtr w parametrach funkcji, numer filtra wynosi 0. Oznacza to, że każdy klucz dla tego filtra będzie zaczynał się od "filter.0". Składnia tego filtra powinna wyglądać następująco:

Sortowanie

Sortowanie wyników nadaje priorytet widokowi na podstawie informacji zawartych w parametrze. Posortowane wyniki określają, które z nich są uwzględniane w agregacjach. Możesz mieć wiele funkcji sortowania, jednak kolejność opcji określa priorytet sortowania.

Funkcje sortowania składają się z dwóch części:

• sortBy - pole, według którego mają być sortowane wyniki
• sortDir - kierunek sortowania, rosnący (asc) lub malejący (desc).

Każda funkcja sortowania składa się z 3 części. Używając notacji kropkowej do zapisu każdego klucza, określ typ parametru ('sortOptions'), numer sortowania (od 0 do n) i argument sortowania ('sortBy' lub 'sortDir'). Musi istnieć parametr dla wszystkich trzech części funkcji sortowania, aby działała.

PrzykładChcemy, aby wyniki funkcji łącznika były sortowane według ostatnio zaktualizowanego pola w porządku rosnącym. Ponieważ jest to nasza pierwsza funkcja sortowania, numer sortowania wynosi 0. Oznacza to, że oba klucze dla tego sortowania będą zaczynać się od "sortOptions.0". Dla klucza sortBy wartość jest specjalną wartością ('_updatedAt') pochodzącą z dokumentacji API do sortowania zaktualizowanych pól. Składnia tych parametrów powinna wyglądać następująco:

Offsets

Przesunięcia określają indeks, od którego rozpocznie się zwracany wynik. Ten parametr jest używany do paginacji, a nie kolejności rekordów, która jest określana przez parametry sortowania. Wartość parametru musi być liczbą całkowitą większą lub równą 0.

PrzykładChcemy wyświetlić tylko rekordy od 5. pozycji, aby nie widzieć 5 najlepszych wyników. Składnia parametru zapytania powinna wyglądać następująco:

Agregatory filtrów

Agregatory filtrów określają sposób łączenia filtrów w parametrach. Dwie wartości do wyboru to "any" i "all". Wartość "all" oznacza, że wszystkie filtry muszą mieć rekord, aby rekord został uwzględniony w wynikach. Wartość "any" oznacza, że co najmniej jeden z filtrów musi pasować do rekordu, aby został on uwzględniony w wynikach. Domyślną wartością jest "all", niezależnie od ustawienia parametru.

PrzykładMamy serię filtrów w parametrach zapytania, ale potrzebujemy tylko jednego z tych filtrów, aby rekordy pasowały do naszego żądania. Składnia parametru zapytania powinna wyglądać następująco:

Wiele filtrów

W niektórych przypadkach możesz mieć wiele filtrów do sprawdzenia w tabeli. W takim przypadku można dodać wiele filtrów do obiektu filters. Może to wyglądać mniej więcej tak:

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

Więcej informacji

• Przegląd konektorów HTTP
• Jak utworzyć i skonfigurować funkcję konektora HTTP
• Jak korzystać z interfejsu API tabeli