Jak utworzyć i skonfigurować funkcję łącznika HTTP

Dowiedz się jak poruszać się po modalu funkcji Connector i procesie tworzenia.

Przegląd

Funkcje połączeń są funkcją do strukturyzowania tego, jak aplikacje Tulip współdziałają z zewnętrznymi serwerami i usługami. Jeśli Connector jest ogólnym połączeniem pomiędzy Tulipem a zewnętrznym serwerem, to funkcje Connector są specyficznymi żądaniami usług lub informacji. W tym artykule przeprowadzimy Cię przez to, jak stworzyć i skonfigurować funkcję konektora, aby uzyskać dostęp do konkretnych danych lub informacji z zewnętrznej usługi.

Aby uzyskać informacje na temat podstaw API, zapoznaj się z artykułem Jak używać API.

Konfiguracja

Przed utworzeniem funkcji łącznika musisz utworzyć łącznik HTTP, aby utworzyć połączenie między aplikacją a usługą, z którą chcesz się komunikować. Funkcje konektorów będą tworzone w ramach tego konektora, a każda funkcja konektora w ramach konektora będzie współdzielić konfigurację swojego konektora nadrzędnego. Aby utworzyć Connector HTTP, wykonaj kroki w tym artykule: How to Configure a Connector.

Po utworzeniu konektora, nadszedł czas na utworzenie funkcji konektora. Funkcje konektora to poszczególne operacje, które wykonuje konektor, aby pobrać dane z serwera API, z którym się łączy.

Tworzenie funkcji konektora

Na stronie Connectors wybierz Connector, z którym chcesz pracować, klikając jego nazwę.

Na tej stronie widoczna jest lista funkcji powiązanych z konektorem. Aby utworzyć nową funkcję konektora, kliknij + Utwórz funkcję.

Zanim utworzymy nową funkcję, warto zapoznać się z edytorem funkcji złącza, który został podzielony w tym artykule: .:::(Internal) (Private notes) insert connector function overview article here :::

Aby nie przedłużać, w tym artykule założymy, że znasz już poszczególne części Connector Function Editor.

Oto proces, którego użyjemy, aby skonfigurować funkcję łącznika:

1. Wybierz typ {{glosariusz.API Call}}
2. Napisz adres URL API
3. Ustaw dane wejściowe
4. Zdefiniuj parametry dla zwracanych danych
5. Ustaw wyjścia używając notacji kropkowej

Typ wywołania i adres URL

Pierwsze dwa elementy do skonfigurowania dla każdej funkcji złącza HTTP to typ wywołania API (GET, POST, PUT, itd.) i adres URL punktu końcowego. Wybierz z listy typów połączeń za pomocą rozwijanej listy i wprowadź ścieżkę punktu końcowego w polu po bazowym adresie URL. Zapoznaj się z dokumentacją API dla usługi, z którą chcesz się połączyć, aby uzyskać listę punktów końcowych i szczegóły konfiguracji.

:::(Info) (UWAGA) W tym artykule używamy kawałka żargonu: API Call. Wywołanie API, lub żądanie API, jest wiadomością wysyłaną do serwera z prośbą o dostarczenie usługi lub informacji przez API. Ponieważ API są sposobem na interakcję jednego programu z drugim, wywołania są procesem, w którym jedna aplikacja wysyła prośbę do innej aplikacji :::

W tym artykule będziemy używać jako przykładu API Document360, który jest usługą hostującą Bazę Wiedzy Tulipa. Funkcja, którą tworzymy, zwraca artykuł wraz z przypisanymi do niego właściwościami na podstawie ID artykułu.

Nazwijmy naszą funkcję, ustawmy typ wywołania (GET) i wpiszmy adres URL dla wywołania:

:::(Info) (UWAGA) W adresie URL wywołania rozróżniana jest wielkość liter. Upewnij się, że wpisujesz go dokładnie tak, jak widzisz go w dokumentacji API. :::

Uzyskaj typ połączenia i adres URL z dokumentacji punktu końcowego swojego systemu. Te dwa działania określają twoje żądanie REST. Aby uzyskać szczegółowy zarys tego, czym jest żądanie REST, zobacz Anatomia żądania REST.

Kliknięcie Test uruchamia funkcję i zwraca informacje w sekcji Test Results edytora. Wybierając Body w sekcji Test Results, możesz zobaczyć pełny, nieprzefiltrowany wynik swojego żądania. Świetnie, mamy dane!

{{glosariusz.Input}}s

W sposób, w jaki nasza funkcja łącznika jest obecnie skonfigurowana, możemy uzyskać tylko jeden konkretny identyfikator artykułu.

Naszym celem w przypadku tej funkcji jest skonfigurowanie jej tak, aby zwracała informacje o każdym interesującym nas artykule. Aby to zrobić, będziemy musieli edytować naszą funkcję, aby umożliwić nam przekazanie wartości dla dowolnego identyfikatora artykułu.

Możemy edytować naszą funkcję konektora, aby przyjmowała dowolną wartość poprzez konfigurację Inputs. Wejścia pozwalają na pobieranie wartości z aplikacji i przekazywanie ich do funkcji konektora.

Wejścia są konfigurowane w dwóch częściach: 1.) tworzenie wejścia w panelu wejściowym, 2.) określenie, gdzie to wejście będzie używane w funkcji konektora.

Najpierw dodaj pole do okienka wejściowego. Możesz zmodyfikować typ danych wejścia klikając na ikonę obok nazwy wejścia. Upewnij się, że wybrany typ odpowiada typowi źródła, którego będziesz używać w swojej aplikacji. Pole obok nazwy wejścia może być użyte do testowania wartości, które chcesz przekazać do funkcji złącza, i może symulować wejścia z twoich aplikacji.

Następnie musimy określić, gdzie dane wejściowe będą używane w naszej funkcji złącza. Wejścia mogą być dostępne w całej funkcji konektora, w tym w adresie URL punktu końcowego, parametrach zapytań i w ekstraktorach JSON w wyjściach. Proszę zapoznać się z dokumentacją API dla każdej usługi, którą chcesz użyć, aby uzyskać więcej informacji na temat tego, jak konkretna funkcja musi być skonfigurowana.

W naszym przykładzie możemy uzyskać dostęp do konkretnego artykułu, określając go na końcu ścieżki punktu końcowego lub w miejsce "{articleId}".

Używając inputs, możemy dynamicznie przekazać wartość do tego adresu URL, a tym samym użyć tej funkcji złącza, aby uzyskać informacje o dowolnym artykule, który chcemy.

Dodajemy dane wejściowe do ścieżki punktu końcowego poprzez umieszczenie znaku dolara**($**) przed i po parametrze (w tym przypadku "ID"). Ciąg znaków pomiędzy znakami dolara jest wrażliwy na wielkość liter i musi być dokładnie dopasowany do nazwy twojego wejścia. Jeśli wrócimy do naszego przykładu, zmieńmy adres URL tak, aby ID było wyrównane z naszym wejściem. Tekst pomiędzy znakami dolara zamienia się w blok, wskazując na właściwość, jak np:

Teraz możemy ustawić ID jako wartości wejściowe, zamiast hardcodować wartość bezpośrednio w adresie URL punktu końcowego.

Aby dodać więcej wejść, kliknij + w prawym górnym rogu pola wejść.

Parametry

Parametry zapytań są parami klucz-wartość, które pojawiają się po ? w punkcie końcowym lub w parametrach zapyt ań podczas tworzenia funkcji Connector.

Teraz, gdy skonfigurowaliśmy nasze wejścia, możesz stworzyć kilka parametrów, aby zmodyfikować wyniki testu i upewnić się, że otrzymujesz tylko te informacje, które chcesz. Znajdź klucze i wartości dla tych parametrów w dokumentacji API serwera, z którym się łączysz.

Z parami Key-Value, jeden z elementów jest "Kluczem", a drugi jest "Wartością"; oba są dodawane do końca adresu URL linku formularza. Pomyśl o nich jak o tokenach w e-mailu, aby spersonalizować czyjeś imię. Używanie par Key-Value pozwala na przekazywanie informacji do formularza.

Klucz wskazuje na nazwę zmiennej.

Wartość wskazuje na wartość właściwości.

W tym przykładzie chcemy ustawić parametr, który zapewni, że zwrócony artykuł zostanie opublikowany na stronie Bazy Wiedzy. Wprowadzając informacje podane w dokumentacji API, parametr wygląda następująco:

Te parametry zapytania i żądania są opcjonalnymi polami do wypełnienia, ale nadają specyficzność Wynikom Testu, jeśli tego potrzebujesz.

{{glosariusz.Output}}s

Wyjścia są częścią funkcji łącznika, która pokazuje, jakie informacje są bezpośrednio zwracane. Są one zbudowane w Notacji Kropkowej, więc zwróć uwagę na format Wyników Testu, aby sprawdzić, czy twoja notacja podąża dokładną ścieżką. Dane wyjściowe mapują zmienne w aplikacjach, więc upewnij się, że nazywasz je czymś identyfikowalnym i unikalnym.

Zauważ, że możesz zmienić typ wyjścia na listę używając Przełącznika listy; ta opcja zagnieżdża zmienne wyjścia wewnątrz obiektów i uniwersalnie mapuje ścieżkę notacji kropkowej dla wszystkich zagnieżdżonych wyjść w liście obiektów.

Aby sprawdzić, czy wyjścia są poprawnie odwzorowane, kliknij zakładkę wyjścia w okienku Wyniki testu i zanotuj wyniki, które są zwracane.

Jeśli wyjścia są zgodne z wynikami, to gratulacje! Udało Ci się stworzyć działającą funkcję łącznika i jesteś gotowy do użycia jej w aplikacji. Sprawdź Korzystanie z łączników HTTP w aplikacjach, aby poznać kolejne kroki.

Jeśli masz problem z nieprawidłowym działaniem funkcji łącznika, zobacz nasz przewodnik rozwiązywania problemów, aby dowiedzieć się, co może być nie tak.

Weź udział w kursie Uniwersytetu Łączników HTTP, aby zapoznać się z budową łączników.

Dalsze lektury

• Przegląd konektorów HTTP
• Jak formatować dane wyjściowe łącznika HTTP

Czy znalazłeś to, czego szukałeś?

Możesz również udać się na stronę community.tulip.co, aby zadać swoje pytanie lub sprawdzić, czy inni spotkali się z podobnym pytaniem!