Zapytanie API

Odpytuje zewnętrzne oprogramowanie przez jego interfejs webowy w trakcie połączenia, zapisuje odpowiedź w zmiennych i przechodzi na wyjście Błąd, gdy tylko trwa to zbyt długo albo się nie powiedzie.

W skrócie

Wyjścia	OK i Błąd
Pola	Metoda, Timeout, URL, Nagłówki (1/linia), Treść (POST/PUT), oraz tabela ekstrakcji Zmienna i Ścieżka JSON
Metody	GET, POST, PUT, DELETE
Proponowany timeout	2, 3, 5, 8 albo 10 s, domyślnie 5 s
Rzeczywiście stosowany timeout	maksymalnie 8 sekund, nawet jeśli wybierzesz 10
Czas oczekiwania na nawiązanie połączenia	2 sekundy
Przekierowania śledzone	2
Bezpiecznik	5 kolejnych niepowodzeń na tym samym serwerze otwiera obwód na 30 sekund

Tekst pomocy wyświetlany w oknie to: „Odpytuje API HTTP i wyodrębnia wartości JSON do zmiennych. Jeśli API zawiedzie albo przekroczy timeout, brane jest wyjście „Błąd”. Użyj {{zmienna}} w URL, nagłówkach i treści.”

Jak to działa

Czym jest API

API to wejście serwisowe oprogramowania: adres webowy, który odpytuje inny program, i który odpowiada nie stroną do przeczytania, ale danymi ustrukturyzowanymi. Większość odpowiada w formacie JSON, który porządkuje informacje według nazwy, na wzór formularza: {"client": {"nazwa": "Kowalski", "status": "premium"}}.

Moduł wysyła zapytanie, odczytuje odpowiedź i wyodrębnia z niej to, co cię interesuje.

Zmienne w zapytaniu

URL, Nagłówki i Treść przyjmują zmienne {{zmienne}}, zastępowane tuż przed wysłaniem. Tak odpytuje się serwis o aktualnie prowadzone połączenie: https://api.przyklad.com/klient/{{caller}}.

Ekstrakcja

Odpowiedź rzadko warto brać w całości. Dolna tabela wiąże Ścieżkę JSON z nazwą Zmiennej. Ścieżka czyta się z zewnątrz do wewnątrz, poziomy oddzielone kropkami: klient.nazwa szuka nazwa wewnątrz klient. Lista jest przeglądana według swojej pozycji, zaczynając od zera: 0.nazwa oznacza nazwę pierwszego elementu.

Ścieżka pozostawiona pusta zwraca całą odpowiedź: to właśnie potrzebne, gdy serwis odpowiada bezpośrednio liczbą albo słowem, bez żadnej struktury dookoła.

Ścieżka, która donikąd nie prowadzi, daje pustą zmienną, bez błędu. Wyjście OK i tak zostaje użyte, ponieważ serwis rzeczywiście odpowiedział.

Kiedy używane jest wyjście Błąd

URL jest pusty;
serwis nie odpowiada w wyznaczonym czasie;
odpowiada kodem błędu, czyli dowolnym kodem spoza rodziny sukcesów;
bezpiecznik jest otwarty.

Bezpiecznik

Serwis, który jest niedostępny, nie powinien spowalniać wszystkich twoich połączeń. Po 5 kolejnych niepowodzeniach wobec tego samego serwera, moduł przestaje go odpytywać przez 30 sekund: wyjście Błąd zostaje użyte natychmiast, bez czekania na upływ czasu i bez wysyłania zapytania. Pierwszy sukces zeruje licznik.

To zabezpieczenie, i tłumaczy ono zaskakującą obserwację: w ciągu tych trzydziestu sekund połączenie odchodzi w Błąd błyskawicznie, mimo że serwis może już działać.

Co należy uzupełnić

Pole	Czego się oczekuje	Jeśli zostawisz puste
Metoda	GET do odczytu, POST albo PUT do wysyłania, DELETE do usuwania	GET
Timeout	czas oczekiwania, ograniczony do 8 s maksymalnie przy wykonaniu	5 s
URL	pełny adres, przyjmujący zmienne `{{zmienne}}`	wyjście Błąd zostaje użyte, bez wysłania jakiegokolwiek zapytania
Nagłówki (1/linia)	jeden nagłówek na linię, na przykład klucz uwierzytelniający	żaden nagłówek nie zostaje wysłany
Treść (POST/PUT)	wysyłana zawartość, zazwyczaj JSON	brak zawartości; treść jest i tak ignorowana w GET
Zmienna ekstrakcji	nazwa, pod którą zapisać odczytaną wartość	linia zostaje zignorowana
Ścieżka JSON ekstrakcji	ścieżka do wartości, na przykład `klient.nazwa`	cała odpowiedź zostaje zapisana w zmiennej

Przycisk Dodaj ekstrakcję tworzy linię, Usuń usuwa swoją, Zapisz zamyka okno.

Jak to zrobić krok po kroku

Zdobądź od swojego dostawcy adres do odpytania, sposób uwierzytelnienia i przykład odpowiedzi. Bez przykładu odpowiedzi nie napiszesz ścieżek ekstrakcji.
Umieść moduł Zapytanie API i połącz poprzedni węzeł z jego wejściem.
Otwórz go, wybierz Metodę i ustaw Timeout na najkrótszy czas, jaki obsługuje twój serwis.
Wpisz URL, wstawiając zmienne z panelu Dostępne zmienne.
Uzupełnij Nagłówki, jeden na linię, zazwyczaj linię uwierzytelniającą dostarczoną przez dostawcę.
Dla POST albo PUT wpisz Treść.
Kliknij Dodaj ekstrakcję i powiąż Ścieżkę JSON z nazwą Zmiennej, tyle razy, ile wartości chcesz odzyskać.
Kliknij Zapisz, a następnie połącz OK z normalnym dalszym ciągiem, a Błąd z rozwiązaniem zapasowym, które obsługuje połączenie bez tej danej.
Umieść moduł Debugowanie po wyjściu OK, z komunikatem zawierającym wyodrębnione zmienne, aby odczytać, co rzeczywiście zostało odebrane.
Kliknij Zapisz, a następnie Zastosuj zmiany w górnym pasku.
Zadzwoń pod swój numer, a następnie otwórz Dziennik debugowania planu i sprawdź wyodrębnione wartości.

Jeśli coś nie działa

Wszystkie połączenia trafiają w Błąd, mimo że URL działa w przeglądarce. Przeglądarka wysyła twoje ciasteczka sesji, moduł nie. Sprawdź nagłówek uwierzytelniający. Sprawdź następnie URL po podstawieniu zmiennych: źle napisane {{nazwa}} staje się pustką i tworzy niekompletny adres. Wreszcie każda odpowiedź spoza rodziny sukcesów liczy się jako niepowodzenie, nawet czytelna strona błędu.

Wyjście Błąd zostaje użyte natychmiast, bez odpytania serwisu. Bezpiecznik jest otwarty: pięć kolejnych niepowodzeń wobec tego serwera przełączyło go na trzydzieści sekund. Odczekaj pół minuty, zanim wyciągniesz wnioski, a następnie zadzwoń ponownie.

Wybrałem 10 sekund, a połączenie wraca po 8. Czas jest ograniczony do ośmiu sekund przy wykonaniu, niezależnie od wybranej wartości. To celowe: powyżej tego dzwoniący już by się rozłączył.

Wyodrębniona zmienna jest pusta, mimo że odpowiedź zawiera daną. Ścieżka nie pasuje. Poziomy oddziela się kropkami, listy liczy się od zera, a pusta ścieżka zwraca całą odpowiedź. Wyodrębnij najpierw całą odpowiedź do zmiennej, przeczytaj ją w Dzienniku debugowania, a następnie zapisz dokładną ścieżkę.

Połączenie kończy się, gdy serwis nie odpowiada. Wyjście Błąd nie jest z niczym połączone. Połącz je, przynajmniej ze zwyczajowym powitaniem.

Jak powstaje plan połączeń, wyjaśnione na obrazach

Zobacz stronę Plany numeracji