Zapier – Jak zrobić integrację aplikacji?

Zapier to usługa umożliwiająca połączenie jakichkolwiek usług między sobą i zautomatyzowanie pewnych czynności. To z tym narzędziem zautomatyzujesz zapisywanie faktur z maila na dysku, połączysz formularz z mailingiem, czy prześlesz dane z jednej aplikacji do drugiej. Jeśli korzystasz z małej aplikacji albo sam ją stworzyłeś – jest mała szansa, że duże serwisy jak todoist, facebook czy github zrobią z nią bezpośrednią integrację. Jak więc nie zamykać się na funkcjonalności jednej aplikacji i umożliwić połączenie jej z innymi? A więc Zapier…

Problem

Mimo że zapier posiada wiele gotowych integracji, może się zdarzyć, że nie będzie akurat aplikacji, której używasz. Mi brakowało zaawansowanej integracji z moim mailingiem, który jest postawiony na Sendy. Chciałem mieć możliwość dodania taga dla każdego maila, który się do mnie zapisuje. Dzięki tym tagom łatwiej mi jest podzielić listę na grupy tematyczne np. programiści, startupy itp. Dla przykładu z tej LISTY dostaniesz maile typowo NoCode, raczej rzadko pojawi się coś, co wymaga wiedzy mocno technicznej. Natomiast w tej LIŚCIE może się zdarzyć coś bardziej technicznego, w tym programowanie. Standardowa integracja Sendy umożliwiała zwykły zapis do listy mailingowej z mailem, imieniem i niczym więcej.

Z pomocą przyszła możliwość tworzenia swoich integracji na ich portalu: developer.zapier.com. Samo sendy korzysta z API opartego na formacie danych multipart/form-data. Jest to raczej rzadki przypadek w nowych aplikacjach, dlatego pokażę na przykładzie mojej aplikacji cataloger, w której korzystam z API opartego o format danych JSON. Następny akapit będzie tłumaczył, czym jest Api oraz format danych JSON, więc jeśli wiesz czym to jest, przejdź DALEJ.

Łącznik

API, czyli Application Programming Interface, czyli tłumacząc na ludzkie, jest to taki zbiór “komend” danej aplikacji. Wraz z tymi komendami możesz przekazać lub otrzymać jakieś informacje. W ten sposób się komunikują wszystkie aplikacje, które na to pozwalają. API jest niezbędne do połączenia Zapiera z daną aplikacją. Jeśli nie wiesz, czy aplikacja, dla której chcesz zrobić integrację, posiada API wpisz w google “<aplikacja> API” lub “<aplikacja> developers”. W przypadku sendy, gdy wpisałem “Sendy API”, jako pierwszy wynik otrzymałem dokumentację do ich API – to właśnie tego szukasz.

Informacje, które cię interesują w tym API to:

  • URL – czyli link danej “komendy”
  • Metoda – czyli co będzie miała zrobić dana komenda. Z tych podstawowych można wyróżnić: GET – pobieranie danych z aplikacji, POST – dodawanie danych do aplikacji, DELETE – usuwanie danych z aplikacji.
  • Headers – czyli nagłówki, w nich określasz np. format przesyłanych danych
  • Body – to są już właściwe dane, np. email, imię i tag kontaktu, który zapisuje się do twojego mailingu.

Zatem czym jest JSON? To standaryzowany format danych, dzięki niemu obie strony komunikacji wiedzą jak odczytać lub wysłać wiadomość.

Przykładowy JSON

Jeśli chciałbyś sobie przećwiczyć korzystanie z takiego API, polecam aplikację Postman, a jeśli chciałbyś się dowiedzieć więcej na temat korzystania z API za pomocą Postmana, to jest przykładowy FILMIK tłumaczący to zagadnienie. A teraz wracamy do sedna.

Rozwiązanie – Zapier developer

Zaloguj się na developer.zapier.com. Twoim oczom powinien się pokazać Twój panel główny z opcją “Start Zapier Integration”. Kliknij to i na następnej stronie uzupełnij dane swojej aplikacji. Nic odkrywczego tu raczej nie ma. Ważne jest pole “Intended Audience” – jeśli aplikacja należy do Ciebie, to bez problemu możesz ustawić “Public”. W innym przypadku pozostaje ci jedynie korzystanie z opcji “Private” – czyli integracja będzie wyłącznie do użytku własnego.

Formularz dodawania integracji

Autoryzacja

Po utworzeniu integracji przechodzisz do jej ekranu. Tutaj musisz po kolei pouzupełniać segmenty, które Cię interesują. W pierwszej kolejności jest Autoryzacja. Większość API, aby zapobiegać nadużyciom, wymaga autoryzacji przed ich użyciem. W tym przykładzie przedstawię autoryzację sposobem “Session Auth”. W tym sposobie autoryzacji użytkownik musi podać dane logowania, na ich podstawie najczęściej zostaje wygenerowany token autoryzacyjny. Token autoryzacyjny jest użyty w nagłówkach każdego zapytania do API, tak by potwierdzić, że posiadasz do niego uprawnienia.

Pola logowania

Dodaj swoje pola logowania, w moim przypadku jest to email oraz hasło. Nie zapomnij oznaczyć typu danych, dla hasła musi to być “Password”, aby było bezpiecznie przechowywane.

Dodawanie pola logowania

Zapytanie autoryzacyjne

Kolejną rzeczą, którą musisz zrobić, jest skonfigurowanie zapytania autoryzacyjnego. To właśnie tutaj przekazujemy dane logowania do aplikacji i otrzymujemy token autoryzacyjny w zamian. Polecam przejść od razu trybu kodu – przycisk “Switch to code mode” poniżej formularza zapytania (po angielsku “Request”). Ten formularza od Zapiera nie jest zbytnio zmyślny cholibka, dlatego lepiej to zrobić ręcznie. W trybie kodu jest przedstawione zapytanie w kodzie JavaScript.

const options = {
  url: 'http://yourdomain.com/user/auth',
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'accept': 'application/json'
  },
  body: {
    'email': bundle.authData.email,
    'password': bundle.authData.password,
    'clientId': 'd524c1a0811da49592f841085cc0063eb62b3001252a94542795d1ca9824a941'
  }
}
return z.request(options)
  .then((response) => {
    response.throwForStatus();
    const results = response.json;
    return {
      'sessionKey': results.accessToken
    };
  });

Z ważnych parametrów do zmiany są tutaj:

  • url – tutaj daj dokładną ścieżkę do zapytania autoryzacyjnego. Taka ścieżka zwykle posiada w sobie “auth”, więc szukaj czegoś takiego.
  • headers – tutaj możliwe, że będziesz musiał zmienić domyślny parametr ‘content-type’ na ‘application/json’ lub jakikolwiek inny jest wymagany przez Twoją aplikację.
  • body – To pole domyślnie może być już uzupełnione, zwróć jednak uwagę czy parametry są nazwane tak jak w zapytaniu autoryzacyjnym twojej aplikacji (np. ‘login’ lub ‘username’ zamiast ’email’). Wszystkie dane, które zostały wprowadzone przez użytkownika, są dostępne w ‘bundle.authData’. Jeśli więc nadałeś jakiemuś polu klucz ‘name’ (w formularzu dodawania pól był to ‘Key’), możesz go użyć dodając do body ‘bundle.authData.name’.
  • Odpowiedź zapytania autoryzacyjnego – tutaj z odpowiedzi zapytania musisz wyciągnąć token autoryzacyjny i przypisać go do ‘sessionKey’ którego będziesz używał w kolejnych zapytaniach.
Odpowiedź zapytania autoryzacyjnego. Wartość ‘accessToken’ została przypisana do ‘sessionKey’

Zapytanie testowe

Zapier, aby móc sprawdzić, czy autoryzowanie przebiegło pomyślnie, wyśle zapytanie do twojej aplikacji. Możesz skonfigurować to zapytanie w kolejnej sekcji – tutaj również polecam przejść do trybu kodu.

const options = {
  url: 'http://yourdomain.com/test',
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${bundle.authData.sessionKey}`
  }
}

return z.request(options)
  .then((response) => {
    response.throwForStatus();
    return {result: response.content};
  });

Ponownie należy ustawić url na jakiś najlepiej wymagający autoryzacji. Dodać token autoryzacyjny, w moim przypadku jest to Bearer token, więc dodałem odpowiedni nagłówek w linii 5. Jak pewnie zauważyłeś, tutaj jest użyty token który wcześniej zwróciłem z zapytania autoryzacyjnego, jest on dostępny w każdym zapytaniu jako ‘bundle.authData.sessionKey’.

Osobiście zmieniłem również obsługę zwracanych danych. Wyrzuciłem tutaj ‘let results = response.json;’ – ta linijka generowała błąd, ponieważ moje zapytanie testowe nie zwraca danych JSON, tylko tekst “HELLO WORLD!’.

Jeszcze muszę dopowiedzieć – ‘response.throwForStatus’ – odpowiada za uznanie zapytania jako błędne, jeśli dostaliśmy z aplikacji odpowiedź o statusie innym niż 200. Status 200 mówi, że zapytanie przeszło pomyślnie, a kody 400 oraz 500 mówią o wystąpieniu błędu.

Jeśli chciałbyś całkowicie pominąć zapytanie testowe, skonstruuj je w następujący sposób:

const options = {
  url: 'http://google.com/',
  method: 'GET'
}

return z.request(options)
  .then((response) => {
    return {};
  });

A teraz przetestuj autoryzację! Jeśli autoryzacja się powiodła, przejdź dalej – do Akcji.

Akcje

Teraz przejdziemy do kluczowego momentu – utworzenia Akcji. Akcja to jest właśnie wywołanie takiej “komendy” w celu otrzymania jakichś danych lub wykonania jakiejś czynności w aplikacji, np. dodania nowego zadania w Todoist. Moim przykładem będzie wygenerowanie opisu produktu w Catalogerze.

W formularzu tworzenia Akcji nie ma nic odkrywczego: nazwa, opis itp. więc tłumaczyć nie trzeba, przejdę od razu do “Input Designer”. W porównaniu do formularza pól wejściowych dla zapytania autoryzacyjnego, tutaj mamy dostęp do szerszej gamy typów tych pól.

  • Text – jak nazwa wskazuje, jest to dłuższy tekst
  • String – nie do końca jest opisana różnica między String a Text, ale domyślam się, że jest to krótsza forma tekstowa, np jedno słowo.
  • Integer – liczba całkowita
  • Number – Jakakolwiek liczba, nawet te zmiennoprzecinkowe.
  • Boolean – Wartość true lub false.
  • DateTime – Jak nazwa wskazuje, jest to Data.
  • Password – hasło, czyli tekst, którego wartość pozostaje niewidoczna
  • Dictionary – słownik, czyli zbiór par – klucz oraz wartość.

Oprócz zwykłych wartości tekstowych ja wykorzystam typ Dictionary, który jest mi potrzebny do przekazania parametrów produktu. Parametry produktu to pole “specification” w poniższym JSONie. Ten JSON to rzecz jasna ciało mojego zapytania generującego opisy.

{
    "name": "Duravit PuraVida Wanna prostokątna 200x100cm wolnostojąca",
    "productType": "Wanna",
    "specification": "Długość wanny 200cm, Szerokość wanny 100cm, Rodzaj materiału akryl, Typ wanny wolnostojąca, styl Nowoczesny, gwarancja 2 lata",
    "problem": "Zapewnia komfortową kąpiel"
}

Konfiguracja zapytania

Zapytanie do aplikacji jako akcja to trochę powtórka z rozrywki względem konfiguracji autoryzacji. Różnicą jest cel, który chcemy osiągnąć.

var specification = "";
for(const [key, value] of Object.entries(bundle.inputData.params)) {
  specification += `${key} ${value},`;
}
const options = {
  url: 'yourdomain.com/description/generate',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${bundle.authData.sessionKey}`,
  },
  body: {
    'name': bundle.inputData.name,
    'productType': bundle.inputData.type,
    'specification': specification,
    'problem': bundle.inputData.designation,
    'mode': 'COPY'
  }
}
return z.request(options)
  .then((response) => {
    response.throwForStatus();
    const results = response.json;
    return results;
  });

W przypadku tego zapytania dane wejściowe dla specyfikacji musiały być zmodyfikowane tak, żeby ze Słownika zrobić tekst. Nie jest to problemem w przypadku korzystania trybu kodu, gdzie za pomocą języka JavaScript możesz dowolnie modyfikować dane. W tym zapytaniu zwracam wynik w postaci JSON. Zapier nie ma problemu z odczytaniem tego formatu danych i potem z niego wyciąga dane, które mogą być wykorzystane w kolejnych akcjach (np. dodanie produktu z opisem do sklepu internetowego).

Przetestowanie zapytania

W tym etapie niekoniecznie musisz korzystać z trybu kodu, po prostu wprowadź przykładowe dane wejściowe. Ja ze względu na wykorzystanie słownika (Dictionary) ponownie skorzystałem z dostępu do JavaScript. Standardowy formularz (Określony jako “Pretty”) nie obsługuje słowników i musiałem go dodać w następujący sposób:

"inputData": {
    "name": "Duravit PuraVida Wanna prostokątna 200x100cm wolnostojąca",
    "type": "Wanna",
    "designation": "Zapewnia komfortową kąpiel",
    "params": {
      "Długość wanny": "200cm",
      "Szerokość wanny": "100cm",
      "Materiał": "akryl",
      "Typ wanny": "wolnostojąca",
      "Styl": "Nowoczesny",
      "Gwarancja": "2 lata"
    }
  }

Dane wyjściowe

Po przetestowaniu zapytania, jeśli wszystko dobrze wprowadziłeś, powinieneś dostać odpowiedzieć. Jeśli odpowiedź z aplikacji jest w formacie JSON, w formatce “Sample data” możesz użyć funkcji “Use response from test data”. Funkcja ta zaciągnie odpowiedź z zapytania testowego i na jej podstawie możesz przypisać dane do konkretnych pól wyjściowych. Pola te mogą być używane w kolejnych akcjach, łączących się z innymi aplikacjami.

Dane wyjściowe aplikacji przypisane do pól Zapiera

Podsumowanie

Jeśli budujesz aplikację lub brakuje Ci jakichś integracji dla istniejących aplikacji, stworzenie jej w Zapierze może być dobrą opcją. Nie jest to na tyle czasochłonne (około 30-60 minut), a może dać duże możliwości funkcjonalne i nie zamknie Twojej aplikacji na współpracę z innymi aplikacjami.

Dołącz do wydajnych programistów

Dołącz do newslettera i dowiedz się jak stać się wydajnym programistą. Mięsa nie ma, ale sztuczki i narzędzia NoCode oraz LowCode do zastosowania w twoich projektach na pewno się znajdą.

Zapisz się na listę Generuj opisy szybko jak nigdy z Catalogerem

Otrzymuj informacje o rozwoju Cataloger'a i otrzymaj wczesny dostęp do naszego Generatora opisów!