Czy na podstawie odpowiedzi UptimeScout incidents można od razu ogłosić awarię usługi? Nie: ten endpoint wymienia usługi, dla których niedawno pojawiły się podwyższone sygnały zakłóceń, a specyfikacja wyraźnie zaznacza, że nie są to potwierdzone incydenty zgłoszone przez dostawcę. Praktycznym wynikiem jest krótka lista sygnałów do weryfikacji, a nie gotowy wniosek o przyczynie awarii.

To użyteczne rozróżnienie dla inżyniera dyżurnego i analityka: automatyczne powiadomienie może brzmieć „sprawdź usługę X w regionie Y”, a potwierdzenie zdarzenia i wyjaśnienie jego przyczyny pozostawić oficjalnemu statusowi dostawcy lub własnej diagnostyce. Specyfikacja UptimeScout opisuje osobne ścieżki dla sygnałów, bieżącego statusu i historii obserwacji.
Co dokładnie zwraca lista sygnałów
/v1/incidents to endpoint GET katalogu usług z podwyższonymi sygnałami zakłóceń. Wśród jego parametrów są filtry usługi, regionu, kategorii, zapytania wyszukiwania i przedziału czasu. Odpowiedź wymaga licencji; API opisuje uwierzytelnianie tokenem Bearer. Pole regionu przyjmuje dwuliterowy kod, a hours określa przedział od 1 do 2160 godzin.
Słowo „incident” w ścieżce łatwo odczytać jako „potwierdzona awaria”, ale dokumentacja definiuje je węziej: jako świeży sygnał z obserwacji. Dlatego powiadomienie warto sformułować zgodnie z danymi z odpowiedzi — na przykład „otrzymano sygnał o zakłóceniach dostępności” — i nie przypisywać dostawcy usługi potwierdzenia incydentu.
Minimalna weryfikacja przed powiadomieniem
Najpierw zachowaj pierwotną odpowiedź wraz z czasem jej otrzymania i parametrami zapytania. Następnie sprawdź, jaka usługa i region zostały zwrócone, oraz oceń aktualność na podstawie pól usługi observed_at i stale. Jeśli obserwacja jest oznaczona jako nieaktualna, należy oddzielić ją od bieżącego sygnału, a nie przedstawiać jako stan „w tej chwili”.
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
To przykład zapytania dotyczącego USA w przedziale 24 godzin; klucz jest odczytywany ze zmiennej środowiskowej i nie pojawia się w wierszu poleceń. Po otrzymaniu odpowiedzi sprawdź błędy HTTP i strukturę JSON, a następnie przetwarzaj każdą zwróconą usługę osobno. Wartości statusu w schemacie obejmują operational, degraded, outage i unknown; jeśli brakuje pola lub wartości, nie dopisuj własnej interpretacji.
W przypadku sygnału wymagającego działania pobierz bieżący status danej usługi przez /v1/status oraz jej historię przez /v1/history. W historii warto zachować obok szeregów wartości resolution_seconds, samples, counts i effective_start: dzięki temu analityk widzi, z jaką rozdzielczością czasową zebrano dane i za jaki rzeczywisty okres są dostępne. Specyfikacja ostrzega, że pominięte przedziały są nieznane; pustej przerwy nie można automatycznie uznać ani za dostępność, ani za awarię.
Jak przekształcić odpowiedź w weryfikowalny raport
Dla każdego wpisu utwórz pola: identyfikator i nazwę usługi, region zapytania, status, czas obserwacji, znacznik nieaktualności, czas otrzymania odpowiedzi oraz link do źródła oficjalnego statusu, jeśli zespół je sprawdził. To ostatnie pole uzupełnia integracja lub operator: specyfikacja UptimeScout nie gwarantuje, że sygnał zawiera potwierdzoną przyczynę ani oświadczenie dostawcy.

Podziel proces pracy na trzy stany. „Otrzymano sygnał” oznacza, że wpis znalazł się w wyniku /v1/incidents. „Trwa weryfikacja statusu” oznacza, że pobrano bieżący stan i historię. Stan „potwierdzono” zarezerwuj dla wniosku popartego zewnętrznym oficjalnym komunikatem lub wewnętrzną weryfikacją. Ten prosty podział zapobiega przedstawianiu zagregowanego sygnału na pulpicie jako ustalonego faktu.
Jeśli zespół tworzy raport dla kilku regionów, wysyłaj osobne zapytania z odpowiednimi kodami regionów i zapisuj parametr razem z wynikiem. Pole lang dotyczy języka opisów usług; nie zmienia regionu obserwacji. To rozróżnienie ma znaczenie przy porównywaniu na przykład lokalizowanego katalogu z regionalnym stanem usługi.
Gdzie kończą się wnioski
Weryfikowalnym rezultatem tego scenariusza jest dziennik sygnałów z wyraźnymi znacznikami czasu, regionu i aktualności, uzupełniony o osobną weryfikację statusu i historii. Pomaga on ustalić, co wymaga uwagi i co udało się potwierdzić na podstawie wybranych źródeł. Sama odpowiedź /v1/incidents informuje o podwyższonym sygnale z obserwacji; do ogłoszenia potwierdzonej awarii potrzebne są dane potwierdzające.