Klucze API i hasła w konektorze

Prawie każda usługa z zewnątrz wpuszcza system dopiero po okazaniu klucza API, tokenu albo hasła. Wpisany wprost w pole Metody (JSON) taki klucz zostaje w konfiguracji otwartym tekstem: widzi go każdy, kto ma dostęp do Connect, i wychodzi wszędzie, gdzie widać konfigurację konektora. Dlatego klucz trzymamy w osobnym polu, a w wywołaniu zostawiamy samo odwołanie do niego.

W aplikacji

Gdzie to znajdziesz

Konektory→wybrany konektor→Edytuj

Krok 1: wpisz klucz w Pola ukryte

Otwórz konektor do edycji, rozwiń Pokaż opcje dodatkowe i znajdź pole Pola ukryte. Wpisujesz w nim nazwę klucza i jego wartość:

{
  "api_key": "6f1c0e9d8b7a45f2",
  "application_key": "A7C41B2E9D",
  "password": "tajne-haslo"
}

Nazwę wymyślasz sam - to po niej odwołasz się do wartości w wywołaniu. Kluczy może być dowolnie wiele, więc usługa wymagająca dwóch (jak stacja pogodowa: klucz aplikacji i klucz API) mieści się bez kombinowania.

Zapisz. Po ponownym wejściu w edycję zobaczysz w tym polu same nazwy, a wartości zamaskowane kropkami - tak działa to z założenia, wartości nie da się z systemu odczytać.

Krok 2: odwołaj się do klucza w wywołaniu

W polu Metody (JSON) zamiast wartości klucza wpisz {secret.nazwa} - dokładnie tę nazwę, która stoi w Polach ukrytych:

[
  {
    "method": "real_time",
    "http_method": "GET",
    "path": "/api/v3/device/real_time?application_key={secret.application_key}&api_key={secret.api_key}",
    "description": "Bieżący odczyt czujników"
  },
  {
    "method": "set_zone",
    "http_method": "POST",
    "path": "/api/zone",
    "params": { "auth_key": "{secret.api_key}", "zone": "{number}" },
    "description": "Włącza sekcję nawadniania"
  }
]

Odwołanie działa w obu miejscach, w których klucze zwykle stoją:

w ścieżce wywołania - w parametrach adresu (pierwszy przykład) i w środku samej ścieżki, gdy usługa wymaga tokenu jako fragmentu adresu (/forward/v1/{secret.otc}/js)
w danych wysyłanych w zapytaniu - w wartościach z params (drugi przykład)

Wartość podstawia się dopiero w momencie wywołania i idzie prosto do usługi. W konfiguracji konektora zostaje samo odwołanie.

Jeśli usługa wymaga kilku wartości trzymanych razem, możesz je zagnieździć i zejść w głąb kropką - {"dane_logowania": {"klient": "abc", "haslo": "xyz"}} w Polach ukrytych i {secret.dane_logowania.haslo} w wywołaniu.

Sprawdzenie, czy podmiana działa

Wejdź na kartę konektora i uruchom wywołanie odnośnikiem execute obok jego nazwy (przy wywołaniu publicznym stoi tam url - otwórz go). Usługa powinna odpowiedzieć tak samo jak przy kluczu wpisanym wprost - jeśli odpowiada, podmiana działa.

Gdy zamiast odpowiedzi dostajesz błąd o braku wartości i nazwą klucza w treści, znaczy to, że w Polach ukrytych nie ma klucza o tej nazwie. Najczęstsza przyczyna to literówka albo podkreślenie w jednym miejscu, a myślnik w drugim - nazwa musi się zgadzać znak w znak. System celowo przerywa wywołanie zamiast wysyłać do usługi puste miejsce: w odpowiedzi dostałbyś odmowę dostępu bez wyjaśnienia, skąd się wzięła.

Zmiana i usunięcie klucza

Pole Pola ukryte pokazuje przy zapisie to, co widzisz: nazwy z zamaskowanymi wartościami. Stąd trzy zasady przy edycji:

zostawiasz maskę (kropki) - wartość zostaje bez zmian
wpisujesz nową wartość w miejsce kropek - klucz dostaje nową wartość
wpisujesz null jako wartość - klucz znika z konektora

Klucz pominięty w zapisie zostaje nietknięty, więc nie musisz przepisywać całej zawartości, żeby zmienić jedną pozycję.

Pamiętaj, żeby przy usuwaniu klucza usunąć też odwołanie {secret.nazwa} z wywołań, które z niego korzystały - inaczej pierwsze uruchomienie takiego wywołania skończy się błędem.

Czym to się różni od pola Secret Token

Na karcie konektora jest też pole Secret Token (przy części rodzajów podpisane Klucz API). To jedna wartość dla całego konektora, z której korzystają gotowe integracje - one same wiedzą, gdzie ją wstawić. Własny konektor opisujesz wywołaniami, więc podmiana musi być jawna: wartości trzymaj w Polach ukrytych i wskazuj je przez {secret.nazwa}.

O czym warto wiedzieć

Klucz i tak trafia do usługi, z którą się łączysz - to ona go wymaga. Chronimy go przed ludźmi po naszej stronie i przed zapisami w systemie, nie przed adresatem
Odwołanie chroni klucz nie tylko na ekranie - konfiguracja konektora wychodzi też w zestawieniach technicznych i w zapisach zmian, a tam zostaje samo {secret.nazwa}
Dane, z którymi uruchamiasz wywołanie, nie wyciągną klucza - tekst {secret.api_key} podany jako dane wejściowe zostaje zwykłym tekstem i nie zamienia się w wartość