API i automatyzacja UniFi: skrypty bez ryzyka dla produkcji

Automatyzacja w UniFi kusi, bo powtarzalne czynności, jak raport z listy urządzeń, rezerwacje DHCP czy włączanie sieci gości na czas spotkania, można zlecić skryptowi. Ten poradnik nie jest zbiorem gotowych wywołań. Interfejsy UniFi zmieniają się między wersjami aplikacji, więc zamiast przepisywać adresy i pola z pamięci, pokazujemy zasady, które chronią sieć przed skutkami błędu skryptu.

UCG MaxBrama z lokalnym kontrolerem NetworkUDM ProBrama rackowa z kontroleremUNVRRejestrator z aplikacją Protect

Krótko

• Używaj oficjalnie udokumentowanego API. Szczegóły (adresy, pola, wersje) sprawdź w dokumentacji i w ustawieniach swojej aplikacji, bo różnią się zależnie od wersji.
• Daj skryptowi osobny klucz lub konto z minimalnymi uprawnieniami, nie konto administratora.
• Zrób kopię konfiguracji przed pierwszym uruchomieniem i przed każdą zmianą masową.
• Najpierw tryb "tylko odczyt", potem zapis na jednym obiekcie, na końcu cała partia.

Dwa rodzaje interfejsów

W praktyce spotkasz:

1. Oficjalne, dokumentowane API udostępniane przez aplikację, zwykle powiązane z kluczami API tworzonymi w ustawieniach (nazwa sekcji zależy od wersji, szukaj opcji w rodzaju Integrations lub API). Takie interfejsy mają dokumentację i są utrzymywane.
2. Nieoficjalne wywołania, których używa sam interfejs webowy. Społeczność je opisuje, ale producent nie gwarantuje ich stabilności. Aktualizacja może zmienić ich zachowanie bez ostrzeżenia.

Do czegokolwiek, co ma działać miesiącami, wybieraj pierwszą grupę. Wywołania z drugiej traktuj jak narzędzie jednorazowe i sprawdzaj po każdej aktualizacji firmware.

Klucze API i uprawnienia

Klucz API działa jak hasło, więc obowiązują te same reguły:

• Tworzysz go w aplikacji i zwykle widzisz tylko raz. Zapisz od razu w menedżerze haseł.
• Trzymaj go w zmiennej środowiskowej lub pliku poza repozytorium kodu. Nigdy w skrypcie wrzuconym do Git.
• Jeden klucz na jedno zadanie, żeby można było go unieważnić bez psucia reszty.
• Jeśli wersja pozwala ograniczyć zakres lub rolę, wybierz najniższą wystarczającą. Skrypt raportujący nie potrzebuje prawa do zmiany ustawień.
• Dostęp do kontrolera ogranicz do sieci zarządzania. Nie wystawiaj interfejsu do internetu, nawet na chwilę; opis w poradniku Hardening UniFi: konto, 2FA, role i SSH.
• Przy odejściu osoby z firmy unieważnij jej klucze.

Bezpieczne skrypty: lista zasad

1. Odczyt przed zapisem. Pierwsza wersja skryptu tylko pobiera dane i wypisuje, co by zmieniła (tryb dry-run).
2. Idempotencja. Ponowne uruchomienie nie powinno tworzyć duplikatów. Sprawdzaj, czy obiekt już istnieje, zanim go dodasz.
3. Identyfikuj po stałych polach, np. adres MAC lub nazwa, a nie po pozycji na liście.
4. Walidacja danych wejściowych. Plik CSV z błędnym zakresem adresów może uszkodzić działającą sieć.
5. Małe partie. Zmieniaj małe porcje i sprawdzaj wynik. Masowe nadpisanie wszystkiego naraz utrudnia powrót.
6. Logi z czasem i wynikiem, ale bez kluczy i haseł.
7. Test na osobnym środowisku. Jeśli to możliwe, najpierw wypróbuj skrypt na zapasowej bramie lub w osobnej witrynie (site).

Limity i pułapki

• Limity zapytań. Kontroler to nie serwer hurtowy. Zbyt częste odpytywanie (np. co sekundę) obciąża bramę i może prowadzić do odrzucania wywołań. Wybierz rozsądny interwał i pobieraj tylko potrzebne dane.
• Zmiany wersji. Po aktualizacji aplikacji lub firmware sprawdź, czy skrypt nadal działa. Wersje potrafią zmieniać nazwy pól.
• Zmiany powodujące restart. Część ustawień (np. zmiana sieci, kanałów lub VLAN) może chwilowo rozłączyć klientów. Planuj je poza godzinami pracy.
• Brak transakcji. Jeśli skrypt padnie w połowie, konfiguracja zostaje w stanie pośrednim. Dlatego kopia zapasowa jest obowiązkowa.
• Certyfikaty. Kontroler często używa certyfikatu własnego. Nie wyłączaj weryfikacji TLS na stałe; lepiej zaufać konkretnemu certyfikatowi.

Kopie zapasowe przed automatyzacją

Przed pierwszym uruchomieniem zrób eksport konfiguracji i zachowaj go poza kontrolerem. Aplikacje oferują ręczne i automatyczne kopie; szczegóły i test odtwarzania znajdziesz w poradniku Backup i przywracanie konfiguracji UniFi. Sprawdź też, że potrafisz z takiej kopii przywrócić działanie. Kopia, której nigdy nie odtwarzałeś, to nadzieja, a nie zabezpieczenie.

Co warto zautomatyzować na początek

• Raport urządzeń: lista, wersje firmware, czas pracy, ostatni kontakt.
• Powiadomienia o urządzeniach, które przestały odpowiadać.
• Eksport rezerwacji DHCP i listy klientów do arkusza.
• Cykliczna weryfikacja, czy kopie zapasowe powstają.

Zmiany ustawień (zapory, VLAN) automatyzuj dopiero, gdy raportowanie działa od tygodni bez błędów. Do monitorowania stanu bez własnych skryptów zajrzyj do Monitorowanie UniFi: SNMP i syslog.

Najczęstsze błędy

• Klucz administratora w skrypcie na laptopie, który ktoś może zgubić.
• Dostęp do kontrolera z internetu bez ograniczenia do zaufanej sieci.
• Brak kopii przed zmianą masową.
• Poleganie na nieudokumentowanych wywołaniach w zadaniach krytycznych.
• Ślepe kopiowanie przykładów z forów bez sprawdzenia, do jakiej wersji się odnoszą.

Planujesz większe wdrożenie i potrzebujesz sprzętu pod kontroler? Napisz do nas.

Przygotowane przez AI, zredagowane przez człowieka