SmartSense מספקת מערך של נקודות קצה לאיסוף נתוני נכסים וחיישנים באמצעות תכנות. SmartSense מארגנת מכשירים, חיישנים והקריאות שלהם ליחידות לוגיות המכונות "נכסים". נסקור להלן כמה הגדרות.

ממשק ה-API של SmartSense Data מגדיר את הסוגים הבאים:

​תאריכים

פרמטרים מסוג תאריך יש לשלוח לשירות (והם נשלחים ממנו) כצירוף של תאריך ושעה בפורמט ISO 8601. יש לכלול מידע על אזור הזמן, אחרת תוצאות קריאת ה-API אינן מוגדרות.
​
​

הערה: כל התאריכים שהשירות מחזיר הם ב-UTC.

​תאריך הקריאה

readingDate מציין את הרגע שבו נרשמה קריאה על ידי חיישן או מכשיר; לדוגמה, חיישן טמפרטורה רשם טמפרטורה של 32.45°F ביום שישי, 15 בינואר, בשעה 15:17, לפי שעון UTC.
​
​

תאריך העיבוד

processedDate מציין את הרגע שבו הקריאה עובדה על ידי SmartSense.
​
דוגמה: חיישן טמפרטורה חיצוני, המחובר למכשיר, רושם טמפרטורה של 32.45°F ביום שישי, 15 בינואר, בשעה 15:17, UTC. עקב הפרעה בשירות הסלולרי, המכשיר אינו מסוגל לשלוח את הקריאה ל-SmartSense במשך חמש דקות. לפיכך, לקריאה יהיה valueDate של 15:17, אך processedDate של 15:22.
​
יישומים המשתמשים ב-API זה כדי ללכוד את כל הקריאות שעובדו על ידי SmartSense צריכים להשתמש במסנן processedAfterDate כדי לבקש קריאות חדשות מאז הבקשה האחרונה.
​
​

תאריך הפעילות האחרונה

lastActivityDate מציין את המועד שבו המכשיר או החיישן יצרו קשר עם SmartSense בפעם האחרונה. אם המכשיר מעולם לא יצר קשר עם SmartSense, שדה זה יהיה ריק.

מספרים
​

מזהה המכשיר

השדה deviceId הוא מספר בן 20 ספרות שמומר למחרוזת תווים ומועבר. הוא מומר למחרוזת תווים כדי להקל על תאימות בין מערכות.
​
​

ערכי קריאה של הספק

סוג הקריאה "Power" (הספק) מציין את מצב מקור הכוח של המכשיר. הערכים נעים בין 0 ל-10 עבור מכשירים המופעלים באמצעות סוללה בלבד (לדוגמה, חיישן אלחוטי Z-Point). עבור מכשירים המופעלים באמצעות זרם חילופין (AC) עם גיבוי סוללה, הערכים נעים בין 16 ל-26 כאשר המכשיר מחובר לחשמל ובין 0 ל-10 כאשר אינו מחובר לחשמל. ערך של 16 מציין אספקת חשמל מרשת החשמל בלבד, בעוד שערך גבוה מ-16 מציין אספקת חשמל מרשת החשמל בתוספת גיבוי סוללה כלשהו.
​
​

ערכי קריאת עוצמת האות

סוג הקריאה "עוצמת אות" של מכשיר הוא מדד מנורמל של עוצמת האות האלחוטי של המכשיר. הערכים נעים בין 1 ל-10.
​
​

חומרת האירוע

"חומרת האירוע" מתארת את מידת החומרה של אירוע או התראה. חומרת האירוע תמיד שווה לחומרה הגבוהה ביותר של כל התראה הקשורה לאירוע. חומרת ההתראה תמיד שווה לחומרה שהוגדרה בהתראה שהוגדרה שיצרה אותה. לסוג זה יש 5 ערכים:

1: הנמוך ביותר

2: נמוך

3: בינוני

4: גבוה

5: הגבוה ביותר
​
​

סטטוס האירוע

"IncidentStatus" מתאר את מצב האירוע. ערכים אלה עשויים להתעדכן על ידי המערכת עם קבלת נתונים חדשים המביאים לסיום האזעקות או מפעילים אותן מחדש, או על ידי משתמשים הפועלים על האירועים בממשק המשתמש. לסוג זה יש 4 ערכים:

0: חדש

1: פעיל

2: בהמתנה

99: סגור
​
הסטטוס "חדש" פירושו שהמערכת יצרה את האירוע, אך לא בוצעה כל פעולה מצד המשתמש. הסטטוס "פעיל" מציין שמשתמש הוקצה לאירוע. הסטטוס "בהמתנה" זהה מבחינה תפקודית לסטטוס "פעיל", אך בנוסף לכך המשתמש בחר להציב את האירוע בהמתנה בממשק המשתמש. הסטטוס "סגור" פירושו שהאירוע נפתר והמערכת לא תשתמש בו עוד; משמעות הדבר היא שהפרות קריאה חדשות יובילו ליצירת אירועים חדשים.
​
​

מצב האזעקה

AlarmStatus מתאר את מצב האזעקה. לאירוע יכולות להיות אזעקות רבות, ולכן מצבן מתועד בנפרד עבור כל אזעקה. לסוג זה יש 4 ערכים:

0: סגור

1: פתוח

2: אושר

3: נפתר

הסטטוס "סגור" פירושו שהמערכת לא תבצע עוד פעולות כלשהן בנוגע להתראה. חריגות חדשות בערכים יגרמו להתראות חדשות. הסטטוס "פתוח" פירושו שההתראה פעילה. הערך הנוכחי נמצא מחוץ לטווח, וההתראה זמינה לפעולה מצד המשתמש. הסטטוס "אושר" זהה ל"פתוח", אך בנוסף מציין שהמשתמש אישר את ההתראה בממשק המשתמש. התראה "נפתרה" פירושה שהערכים חזרו לטווח.
​
​

מפעיל הפרה

ViolationOperator מתאר את האופרטור היחסי המשמש להשוואת קריאה נכנסת לסף אזעקה. כל האירועים והאזעקות נוצרים על ידי המערכת באמצעות השוואת הקריאות שנאספו על ידי החיישנים לספי האזעקה שהוגדרו. ספים אלה מורכבים מערך ומאופרטור השוואה, אשר מתועדים גם הם במופע האזעקה. לסוג זה יש 3 ערכים:

-1: פחות מ-

0: שווה ל-

1: גדול מ-
​
​

סוג הסף

ThresholdType מתאר את סוג הקריאות שעבורן מוגדרת או מופעלת התראה. כל אירוע יעקוב רק אחר התראות עבור סוג קריאה אחד. לדוגמה, נניח שיש נכס המצויד בחיישני טמפרטורה ולחות, שעבורו הוגדרו שתי התראות: אחת לטמפרטורה ואחת ללחות. אם שני החיישנים חורגים מהטווח שהוגדר עבור ההתראה המתאימה לכל אחד מהם, ייווצרו שני אירועים (אחד לכל סוג קריאה). סוג הקריאה שעבורו אחראי כל אירוע מתועד באמצעות סיווג ה-ThresholdType. הערכים האפשריים לסוג זה הם:

1: טמפרטורה

2: דוח שלא הוגש

3: לחות

4: כוח

5: מהירות הרוח

6: לחות הקרקע

7: שיטפון

8: מתח

9: לחץ

10: לחץ – פסקל

11: לחות העלים

12: משקעים

13: אחוז CO₂

14: אחוז חמצן (O₂)

15: לחץ OLPHC

16: מגע יבש

17: לחץ בסנטי-פסל

18: סוללה חלשה

20: לחץ "סטארווטש"

21: רמת "תצפית בכוכבים"

23: לחץ בקילופסקל

24: מילי-אמפר זרם

25: אמפר זרם

26: חיוב

27: רמה

28: קיבול בפיקופאראד

99: אימות

סוגי ספירה

Enums הם סוגי משתנים בעלי קבוצה מוגבלת של ערכים, ושדות מסוג Enum מוחזרים כמחרוזות ב-JSON. ערך המחרוזת יוגבל לערכי ה-Enum האפשריים, כפי שהוגדרו עבור הסוג. לכל סוגי ה-Enum יש אפשרות להיות null.
​
​

סוג קריאה

מציין את סוג הקריאה.

ערכים:

יחידה

מציין את יחידת המדידה של הערך הנמדד.

ערכים:

סוג המכשיר

מציין את סוג המכשיר.

ערכים:

סוג חיישן

מציין את סוג החיישן.

ערכים:

עיון בתוצאות

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

אם קיים דף נוסף, קישור לדף הבא מצוין בכותרת התגובה HTTP הנקראת next. כותרת זו עשויה לכלול ערכיברירת מחדל עבור פרמטרים GET שאינם חובה, שלא צוינו בבקשה המקורית; לפיכך, עדיףלהשתמש בכותרת זו על פני יצירת ה-URI לדף הבא באופן ידני, כדי להבטיח תוצאות נכונות.
​
​ניתן לעקוף את ערך ברירת המחדל של pageSize על ידי הגדרת פרמטר השאילתה pageSize:

לקוחות המעוניינים לקבל עותק משלהם של קריאות החיישנים או המכשירים יכולים להשתמש בפרמטר השאילתה processedAfterDate כדי להישאר מעודכנים עם SmartSense. בכל פעם שה-"דף" האחרון של התוצאות מוחזר משאילתה המכילה ערך processedAfterDate, נכלל בתגובה כותרת (nextProcessedAfterDate) המציינת את ערך processedAfterDate שיש להשתמש בו בשאילתה הבאה.

דוגמה: הלקוחה אליס מעוניינת לקבל את כל קריאות החיישנים החל מה-1 במרץ 2021 (UTC), וכן את כל הקריאות שיגיעו לאחר מועד זה. אליס תבצע סריקה של SmartSense כל 15 דקות באמצעות פרמטר השאילתה processedAfterDate.
​
​כדי להתחיל, אליס מבצעת את הבקשה הבאה:
​
GET /v1/data/asset/4146/sensorpoint/55689?processedAfterDate="2021-03-01T00:00:00.00Z"
​
​התגובה מהשרת עשויה להכיל מספר "דפים" של נתונים. לכל "דף" (למעט האחרון) יהיה כותרת בתגובה עם קישור ל"דף" הבא. ה"דף" האחרון יכיל כותרת nextProcessedAfterDate עם ערך תאריךושעה. אליס שומרת ערך זה כ-X.
​
​לאחר שאליס קיבלה את כל ה"דפים", יש לה כעת עותק של כל קריאות החיישנים מהחשבון עד וכולל התאריך והשעה X.
​

לאחר שחלפו 15 דקות, אליס מבקשת מ-SmartSense את ערכי המדידה ומשתמשת בערך חדש עבור processedAfterDate: ליתר דיוק, בערך nextProcessedAfterDate X מה-"עמוד" האחרון של הבקשה הקודמת. SmartSense ישיב עם כל ערכי המדידה החדשים שהתקבלו מאז השאילתה האחרונה של אליס.
​
​אליס חוזרת על תהליך זה כל 15 דקות כדי להישאר מעודכנת עם SmartSense.

לתיעוד מפורט של נקודות הקצה וליכולת לבדוק קריאות API באופן ישיר, בקרו בתיעוד Swagger שלנו:

Swagger UI

ממשק Swagger מספק: