האם אפשר להכריז מיד על תקלה בשירות על סמך התשובה של UptimeScout incidents? לא: נקודת הקצה הזאת מציגה שירותים עם אותות חריגים מוגברים שנצפו לאחרונה, והמפרט מציין במפורש שלא מדובר באירועים שאומתו בידי ספק השירות. התוצאה המעשית היא רשימה קצרה של אותות לבדיקה, ולא מסקנה מוכנה על סיבת התקלה.

ההבחנה הזאת חשובה למהנדסי תורנות ולאנליסטים: התראה אוטומטית יכולה לומר „בדקו את שירות X באזור Y”, תוך השארת אימות העובדה והסבר הסיבה לסטטוס הרשמי של הספק או לאבחון משלכם. מפרט UptimeScout מתעד נתיבים נפרדים לאותות, לסטטוס הנוכחי ולהיסטוריית התצפיות.
מה בדיוק מחזירה רשימת האותות
/v1/incidents היא נקודת קצה מסוג GET בקטלוג השירותים שבהם נרשמו אותות חריגים מוגברים. הפרמטרים שלה כוללים מסננים לפי שירות, אזור, קטגוריה, שאילתת חיפוש וחלון זמן. לשם קבלת התשובה נדרש רישיון; ה־API מתעד אימות באמצעות אסימון Bearer. שדה האזור מקבל קוד בן שתי אותיות, והפרמטר hours מגדיר חלון של שעה עד 2160 שעות.
קל לפרש את המילה „incident” בנתיב כ„תקלה מאומתת”, אך התיעוד מגדיר אותה באופן מצומצם יותר: אות תצפיתי עדכני. לכן כדאי לנסח התראה בהתאם לנתוני התשובה — למשל, „התקבל אות על פגיעה בזמינות” — ולא לייחס לספק השירות הודאה באירוע.
בדיקה מינימלית לפני שליחת התראה
תחילה שמרו את התשובה המקורית, יחד עם שעת קבלתה ופרמטרי הבקשה. לאחר מכן בדקו איזה שירות ואיזה אזור הוחזרו, והעריכו את עדכניות הנתונים לפי שדות השירות observed_at ו־stale. אם התצפית מסומנת כמיושנת, יש להפריד אותה מאות נוכחי ולא להציג אותה כמצב „עכשיו”.
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
זוהי דוגמה לבקשה עבור ארצות הברית בחלון של 24 שעות; המפתח נקרא ממשתנה סביבה ואינו מוצג בשורת הפקודה. לאחר קבלת התשובה, בדקו שגיאות HTTP ואת מבנה ה־JSON, ואז עבדו בנפרד עם כל שירות שהוחזר. ערכי הסטטוס בסכמה כוללים operational, degraded, outage ו־unknown; אם שדה או ערך חסרים, אל תחליפו אותם בפרשנות משלכם.
עבור אות שמצריך פעולה, בקשו את הסטטוס הנוכחי של השירות המתאים באמצעות /v1/status ואת ההיסטוריה באמצעות /v1/history. בהיסטוריה כדאי לשמור לצד סדרות הנתונים את resolution_seconds, samples, counts ו־effective_start: כך האנליסט יכול לראות באיזו רזולוציית זמן נאספו הנתונים ולאיזה פרק זמן בפועל הם זמינים. המפרט מזהיר שמרווחים חסרים אינם ידועים; אין להסיק אוטומטית שמרווח ריק מעיד על זמינות או על תקלה.
איך להפוך תשובה לדוח שניתן לבדוק
לכל רשומה צרו שדות עבור מזהה השירות ושמו, אזור הבקשה, הסטטוס, שעת התצפית, סימון ההתיישנות, שעת קבלת התשובה וקישור למקור הסטטוס הרשמי — אם הצוות בדק אותו. האינטגרציה או המפעיל שלכם ממלאים את השדה האחרון: מפרט UptimeScout אינו מבטיח שהאות כולל סיבה מאומתת או הצהרה של הספק.

חלקו את תהליך העבודה לשלושה מצבים. „התקבל אות” פירושו שהרשומה הופיעה בתוצאה של /v1/incidents. „הסטטוס נמצא בבדיקה” פירושו שביקשתם את המצב הנוכחי ואת ההיסטוריה. שמרו את התווית „אומת” למסקנה הנתמכת בהודעה רשמית חיצונית או בבדיקה פנימית. ההפרדה הפשוטה הזאת מונעת מלוח המחוונים להציג אות מצרפי כעובדה מוכחת.
אם הצוות מכין דוח על כמה אזורים, שלחו בקשות נפרדות עם קודי האזורים הדרושים ושמרו את הפרמטר לצד התוצאה. השדה lang קובע את שפת תיאורי השירותים; הוא אינו משנה את אזור התצפיות. ההפרדה הזאת חשובה כשמשווים, למשל, קטלוג בשפה מקומית למצב אזורי.
היכן מסתיימת המסקנה
התוצאה שניתן לבדוק בתרחיש הזה היא יומן אותות עם סימוני זמן, אזור ועדכניות ברורים, ובצדו בדיקה נפרדת של הסטטוס וההיסטוריה. הוא מסייע לזהות מה דורש תשומת לב ומה הצלחתם לאמת מול המקורות שנבחרו. התשובה של /v1/incidents עצמה מדווחת על אות תצפיתי מוגבר; כדי להכריז על תקלה מאומתת דרושים נתונים תומכים.