Jak utworzyć i skonfigurować funkcję konektora HTTP

Dowiedz się, jak poruszać się po oknie modalnym funkcji łącznika i procesie tworzenia.

Przegląd

Funkcje konektorów to funkcja strukturyzująca sposób interakcji aplikacji Tulip z zewnętrznymi serwerami i usługami. Jeśli konektor jest ogólnym połączeniem między Tulip a serwerem zewnętrznym, funkcje konektora są konkretnymi żądaniami usług lub informacji. W tym artykule pokażemy, jak utworzyć i skonfigurować funkcję konektora, aby uzyskać dostęp do określonych danych lub informacji z usługi zewnętrznej.

Aby uzyskać informacje na temat podstaw interfejsów API, zapoznaj się z tym artykułem na temat korzystania z interfejsu API.

Konfiguracja

Przed utworzeniem funkcji konektora należy utworzyć konektor HTTP, aby utworzyć połączenie między aplikacjami a usługą, z którą chcesz się komunikować. W ramach tego konektora utworzone zostaną funkcje konektora, a każda funkcja konektora w ramach konektora będzie współdzielić konfigurację konektora nadrzędnego. Aby utworzyć konektor HTTP, wykonaj kroki opisane w tym artykule: Jak skonfigurować konektor.

Po utworzeniu konektora nadszedł czas na utworzenie funkcji konektora. Funkcje konektora to poszczególne operacje wykonywane przez konektor w celu pobrania danych z serwera API, z którym się łączysz.

Tworzenie funkcji konektora

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

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

Aby nie przedłużać, w tym artykule założymy, że znasz już różne części edytora funkcji konektora.

Oto proces, którego użyjemy do skonfigurowania funkcji konektora:

1. Wybierz typ API Call.
2. Wpisz adres URL interfejsu API
3. Ustaw dane wejściowe
4. Zdefiniuj parametry dla zwracanych danych
5. Ustawianie danych wyjściowych przy użyciu notacji kropkowej

Typ wywołania i adres URL

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

:::(Info) (UWAGA) W tym artykule używamy żargonu: API Call. Wywołanie API lub żądanie API to wiadomość wysyłana do serwera z prośbą do API o dostarczenie usługi lub informacji. Ponieważ interfejsy API są sposobem interakcji jednego programu z innym, wywołania są procesem, w którym jedna aplikacja wysyła żądanie do innej aplikacji :::

W tym artykule jako przykładu użyjemy interfejsu API Document360, który jest usługą hostującą bazę wiedzy Tulip. Funkcja, którą konfigurujemy, zwraca artykuł wraz z powiązanymi z nim właściwościami na podstawie identyfikatora artykułu.

Nazwijmy naszą funkcję, ustawmy typ wywołania (GET) i wpiszmy adres URL 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 wywołania i adres URL z dokumentacji punktu końcowego swojego systemu. Te dwie czynności określają żądanie REST. Szczegółowy opis żądania REST można znaleźć w sekcji Anatomia żądania REST.

Kliknięcie Test uruchamia funkcję i zwraca informacje w sekcji Test Results edytora. Wybierając Body w sekcji Test Results, można wyświetlić pełny, niefiltrowany wynik żądania. Świetnie, mamy dane!

Inputs

Sposób, w jaki nasza funkcja łącznika jest obecnie skonfigurowana, pozwala nam uzyskać tylko jeden konkretny identyfikator artykułu.

Naszym celem jest skonfigurowanie tej funkcji w taki sposób, aby zwracała informacje o każdym interesującym nas artykule. Aby to zrobić, musimy 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ść, konfigurując Inputs. Wejścia umożliwiają pobieranie wartości z aplikacji i przekazywanie ich do funkcji konektora.

Konfiguracja danych wejściowych składa się z dwóch części: 1.) tworzenie danych wejściowych w panelu danych wejściowych, 2.) określanie, gdzie dane wejściowe będą używane w funkcji konektora.

Najpierw należy dodać pole do panelu danych wejściowych. Typ danych danych wejściowych można edytować, klikając ikonę obok nazwy danych wejściowych. Upewnij się, że wybrany typ odpowiada typowi źródła, którego będziesz używać w swoich aplikacjach. Pole obok nazwy wejścia może być używane do testowania wartości, które chcesz przekazać do funkcji łącznika i może symulować dane wejściowe z aplikacji.

Następnie musimy określić, gdzie dane wejściowe będą używane w naszej funkcji konektora. Dane wejściowe mogą być dostępne w całej funkcji konektora, w tym w adresie URL punktu końcowego, parametrach zapytania i w ekstraktorach JSON w danych wyjściowych. Zapoznaj się z dokumentacją API dowolnej usługi, z której chcesz skorzystać, aby uzyskać więcej informacji na temat konfiguracji konkretnej funkcji.

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 zamiast "{articleId}".

Korzystając z danych wejściowych, możemy dynamicznie przekazać wartość do tego adresu URL, a tym samym użyć tej funkcji łącznika, aby uzyskać informacje o dowolnym artykule, który chcemy.

Dane wejściowe dodajemy do ścieżki punktu końcowego, umieszczając znak dolara**($**) przed i po parametrze (w tym przypadku "ID"). W ciągu znaków rozróżniana jest wielkość liter i musi on dokładnie odpowiadać nazwie danych wejściowych. Jeśli wrócimy do naszego przykładu, zmieńmy adres URL, aby ID było wyrównane z naszymi danymi wejściowymi. Tekst między znakami dolara zamienia się w blok wskazujący właściwość, jak poniżej:

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

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

Parametry

Parametry zapytania to pary klucz-wartość, które pojawiają się po ? w punkcie końcowym lub w Parametrach zapytania podczas tworzenia funkcji konektora.

Teraz, gdy skonfigurowaliśmy nasze dane wejściowe, możesz utworzyć 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.

W przypadku par klucz-wartość jeden z komponentów to "klucz", a drugi to "wartość"; oba są dodawane na końcu adresu URL linku do formularza. Pomyśl o nich jak o tokenach w e-mailu, aby spersonalizować czyjeś imię. Używanie par klucz-wartość umożliwia przekazywanie informacji do formularza.

Klucz wskazuje nazwę zmiennej.

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

W tym przykładzie chcemy ustawić parametr, który zapewni, że zwrócony artykuł zostanie opublikowany na stronie Knowledge Base. 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ą one specyficzności wynikom testu, jeśli zajdzie taka potrzeba.

Outputs

Dane wyjściowe są częścią funkcji łącznika, która pokazuje, jakie informacje są bezpośrednio zwracane. Są one zorganizowane w notacji kropkowej, więc należy zwrócić szczególną uwagę na format wyników testu, aby sprawdzić, czy notacja podąża dokładną ścieżką. Dane wyjściowe są mapowane na zmienne w aplikacjach, więc upewnij się, że nazywasz je czymś identyfikowalnym i unikalnym.

Pamiętaj, że możesz zmienić typ danych wyjściowych na listy, używając opcji List Toggle; ta opcja zagnieżdża zmienne dane wyjściowe w obiektach i uniwersalnie mapuje ścieżkę notacji kropkowej dla wszystkich zagnieżdżonych danych wyjściowych na liście obiektów.

Aby sprawdzić, czy dane wyjściowe są poprawnie zmapowane, kliknij zakładkę outputs w panelu Test Results i zanotuj zwracane wyniki.

Jeśli wyjścia pasują do wyników, to gratulacje! Pomyślnie utworzyłeś działającą funkcję konektora i jesteś gotowy do użycia jej w aplikacjach. Sprawdź Używanie konektorów HTTP w aplikacjach, aby wykonać kolejne kroki.

Jeśli masz problemy z nieprawidłowym działaniem funkcji konektora, zapoznaj się z naszym Przewodnikiem rozwiązywania problemów, aby dowiedzieć się, co może być nie tak.

Weź udział w kursie HTTP Connectors University, aby zapoznać się z instrukcjami tworzenia konektorów.

Więcej informacji

• Jak sformatować dane wyjściowe konektora HTTP

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

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