Własny konektor

Większość popularnych usług ma w systemie gotowy rodzaj konektora - wybierasz go z listy, wpisujesz dane do logowania i tyle. Własny konektor jest dla wszystkiego pozostałego: stacji pogodowej, sterownika nawadniania, panelu dostawcy, usługi napisanej na zamówienie. Zamiast gotowej integracji opisujesz sam, pod jaki adres i jakim wywołaniem system ma zapytać. Rodzaje gotowe, pisane przez nas, opisuje Gotowe konektory.

Nowy konektor

Kliknij Konektor i wypełnij:

• Nazwa - widzą ją twoi ludzie na liście konektorów. Warto, żeby mówiła, z czym się łączy („Stacja pogodowa - winnica” jest lepsze niż „API 2”)
• Rodzaj - wybierz noe/custom_connector. To rodzaj bez gotowej integracji, z wywołaniami opisanymi przez ciebie
• Adres URL - adres usługi, samo miejsce bez ścieżki i bez parametrów, na przykład https://api.ecowitt.net. Ścieżka należy do pojedynczego wywołania, nie do konektora

Reszta pól siedzi pod Pokaż opcje dodatkowe. Do uruchomienia konektora potrzebne są dwa:

• Kod - krótki identyfikator bez spacji (elf-ecowitt), którym konektor wskazuje się w przepływach i w wywołaniach z zewnątrz. Nadaj go od razu; późniejsza zmiana zerwie wszystko, co się na niego powołuje
• Metody (JSON) - lista wywołań, opisana niżej

Zapisz. Konektor pojawia się na liście jako aktywny i od tej pory jego wywołania można uruchamiać.

Metody, czyli co konektor umie zapytać

Pole Metody (JSON) to lista wywołań. Każde ma nazwę, której używasz potem w przepływie, i opis samego zapytania:

[
  {
    "method": "real_time",
    "http_method": "GET",
    "path": "/api/v3/device/real_time?mac=44:17:93:1B:95:E0",
    "description": "Bieżący odczyt czujników"
  },
  {
    "method": "set_zone",
    "http_method": "POST",
    "path": "/api/zone",
    "params": { "zone": "{number}", "state": "on" },
    "description": "Włącza sekcję nawadniania"
  }
]

Co znaczą poszczególne pozycje:

• method - nazwa wywołania. Pod nią widać je na karcie konektora i pod nią wskazujesz je w przepływie
• http_method - GET, gdy wywołanie tylko pobiera dane, POST albo PUT, gdy coś zapisuje po drugiej stronie
• path - ścieżka dopisywana do adresu konektora, razem z parametrami w adresie
• params - dane wysyłane w treści zapytania; {number} w wartości oznacza „wstaw tutaj to, z czym wywołanie zostało uruchomione”
• description - zdanie dla człowieka, widoczne na karcie konektora
• public - true oznacza, że wywołanie ma też własny adres URL (patrz niżej), pod którym da się je wywołać programowo z zewnątrz, z API konta - nie tylko klikając na karcie konektora

Klucza API ani hasła nie wpisuj w to pole wprost - opisuje to Klucze API i hasła w konektorze.

Sprawdzenie, czy usługa odpowiada

Wejdź na kartę konektora. W wierszu Metody (JSON) stoi lista wywołań, a obok każdego odnośnik execute - uruchamia je od razu, tak jak zrobiłby to przepływ, i pokazuje odpowiedź usługi. To najkrótsza droga, żeby sprawdzić adres i dane do logowania, zanim konektor zacznie pracować w tle. Wywołanie oznaczone jako publiczne (do wywoływania z zewnątrz) ma w tym miejscu odnośnik url z własnym adresem - otwarcie go robi to samo.

Osobna rzecz to ruch w drugą stronę, czyli zapytania przychodzące do konektora z zewnątrz - webhooki, którymi usługa zawiadamia system o zmianie. Żeby zobaczyć, czy w ogóle docierają i z czym, włącz na konektorze Loguj żądania (w opcjach dodatkowych); zapisane wejścia pokazuje przycisk Requesty na karcie konektora. Po skończonej diagnostyce wyłącz logowanie - przy usłudze odpytującej system co kilka minut lista rośnie bardzo szybko. Pełny opis obu sposobów sprawdzania (ręczne uruchomienie i podgląd żądań) jest w Uruchamianie i sprawdzanie konektora.

Zanim konektor pójdzie do pracy

• Aktywny - wyłączony konektor zostaje na liście, ale nic go nie wywoła. Tak pauzuje się integrację bez usuwania konfiguracji
• Zabezpiecz zmianę konektora hasłem - przy konektorze, który pilnuje czegoś ważnego (płatności, sterowanie urządzeniem), warto włączyć. Bez hasła nikt nie zmieni ani nie usunie jego ustawień
• Opis - notatka dla następnej osoby: skąd wzięły się dane do logowania i po co ten konektor stoi