Call API
Call API pozwala ankiecie pobierać dane z zewnętrznej usługi internetowej i używać odpowiedzi do wypełniania pól lub walidacji odpowiedzi.
Funkcja Call API pozwala polu ankiety wykonać żądanie HTTP do zewnętrznej usługi i użyć odpowiedzi do wypełnienia obliczonej wartości lub walidacji danych wejściowych użytkownika. Umożliwia to wyszukiwanie w czasie rzeczywistym, weryfikację ID, wyszukiwanie kodów kreskowych i wszelkie inne kontrole po stronie serwera podczas zbierania danych.
Dostępne są dwie funkcje:
callapi()— pobiera wartość z API i przechowuje ją w polucalculatelubtextcallapi-verify()— wywołuje API i blokuje postęp, jeśli odpowiedź nie pasuje do oczekiwanej wartości (używane wconstraint)
callapi() — Pobieranie i przechowywanie odpowiedzi API
Składnia
Umieść callapi() w kolumnie calculation pola calculate lub text:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parametry
| # | Parametr | Opis |
|---|---|---|
| 1 | method | Metoda HTTP: 'GET' lub 'POST' |
| 2 | url | URL punktu końcowego API |
| 3 | allowed_auto | 1 wywołuje automatycznie po dotarciu do pola; 0 wymaga ręcznego przycisku wyzwalacza |
| 4 | max_retry | Maksymalna liczba ponownych prób w przypadku niepowodzenia |
| 5 | no_overwrite | 1 zachowuje istniejącą wartość, jeśli pole ją posiada; 0 zawsze nadpisuje |
| 6 | extract_expr | Wyrażenie JSONPath do wyodrębnienia pożądanej wartości z odpowiedzi (np. $.data.name) |
| 7 | timeout | Limit czasu żądania w milisekundach |
| 8 | lifetime | Jak długo (ms) buforowana odpowiedź pozostaje ważna przed ponownym pobraniem |
| 9 | response_q | Nazwa pola do przechowywania surowego kodu odpowiedzi HTTP (np. ${response_status}) |
| 10 | call_type | (Opcjonalny) Specjalny tryb wywołania: 'lazy-upload' lub 'lazy-upload-multiple' |
| 11 | post_body | (Opcjonalny) Ciąg treści POST. Odwołuj się do pól formularza za pomocą ##fieldname## |
Przykład: Żądanie GET do wyszukania gospodarstwa domowego po ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID gospodarstwa domowego | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Gospodarstwo: ${hh_name} |
Przykład: Żądanie POST z treścią JSON
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
W post_body użyj ##fieldname##, aby wstrzyknąć bieżącą wartość dowolnego pola formularza.
Wygląd: callapi
Dodaj callapi do kolumny appearance pola, aby włączyć integrację wywołania API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Gdy allowed_auto wynosi 0, rtSurvey wyświetla przycisk „Pobierz", który ankieter ręcznie dotyka.
callapi-verify() — Walidacja wartości w oparciu o API
callapi-verify() blokuje przesłanie pola do momentu potwierdzenia przez API, że wprowadzona wartość jest prawidłowa. Użyj go w kolumnie constraint.
Składnia
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parametry
| # | Parametr | Opis |
|---|---|---|
| 1 | method | Metoda HTTP: 'GET' lub 'POST' |
| 2 | url | URL API weryfikacji |
| 3 | extract_expr | JSONPath do wyodrębnienia oczekiwanej wartości z odpowiedzi |
| 4 | match_expr | Wyrażenie porównujące wyodrębnioną wartość z wartością pola (np. $.status = 'valid') |
| 5 | timeout | Limit czasu żądania w milisekundach |
| 6 | constraint_mode | 'soft' tylko dla ostrzeżenia; 'hard' blokuje postęp |
| 7 | post_body | (Opcjonalny) Treść POST z podstawieniami ##fieldname## |
| 8 | message | (Opcjonalny) Komunikat o błędzie. Obsługuje wiele języków: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Przykład: Weryfikacja kodu kreskowego w rejestrze aktywów
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Zeskanuj kod kreskowy aktywu | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Aktywo nie znaleziono w rejestrze |
Wygląd: callapi-verify(...)
Kolumna appearance pola z callapi-verify() w constraint powinna zawierać callapi-verify(params) lub callapi-verify(dynamicParams), aby poinformować rtSurvey, że to pole używa weryfikacji API.
Używanie danych App API razem z callapi
Połącz callapi() z pulldata('app-api', 'user.token'), aby wstrzyknąć token uwierzytelnionego użytkownika do żądania API:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Najlepsze praktyki
- Zawsze ustawiaj rozsądny
timeout(5000–15000 ms) — nie używaj 0 ani bardzo wysokich wartości. - Ustaw
allowed_auto=0dla weryfikacji, które ankieter powinien wyzwalać świadomie (np. sprawdzenia ID). - Ustaw
no_overwrite=1, gdy pole może być edytowane później i nie chcesz, aby ponowne pobieranie nadpisywało ręczne korekty. - Używaj
extract_exprz konkretnym JSONPath zamiast polegania na surowym tekście odpowiedzi. - Testuj wywołania API w trybie offline — callapi zakończy się niepowodzeniem z wdziękiem i pokaże błąd, ale formularz powinien nadal być możliwy do ukończenia dla pól niekrytycznych.
Ograniczenia
- Wymaga połączenia sieciowego w momencie wywołania — wywołania zakończą się niepowodzeniem, gdy urządzenie jest offline.
- Odpowiedzi API muszą być w formacie JSON — odpowiedzi XML lub zwykłego tekstu wymagają dodatkowego parsowania.
- Wysoka częstotliwość wywołań (np. jedno wywołanie API na instancję powtórzenia) może spowolnić nawigację w formularzu.