Table of Contents

19. API

19. API

סקירה

ה־API של Zabbix מאפשר לך באופן תוכנתי למשוך ולשנות את ההגדרות של Zabbix ולספק גישה לנתוני עבר. השימוש הנרחב בו הוא לטובת:

יצירת יישומים חדשים כדי שיעבדו מול Zabbix;
שילוב Zabbix בתוכנות צד־שלישי;
יצירת אוטומציה למשימות מחזוריות.

ה־API של Zabbix עובד במתכונת אתר והוא חלק משירות החזית. הוא משתמש בפרוטוקול JSON-RPC 2.0 שזה אומר שני דברים:

ה־API מורכב מסדרות של מתודות נפרדות;
בקשות ותגובות בין הלקוחות וה־API מוצפנות בתצורת JSON.

אפשר למצוא מידע נוסף על JSON במפרט של JSON-RPC 2.0 ובעמוד הבית של תצורת JSON.

מבנה

ה־API מורכב ממספר מתודות שמקובצות נומינלית למנשקי API נפרדים. כל אחת מהמתודות מבצעת משימה מסוימת אחת. למשל, המתודה host.create שייכת ל־API של host והיא משמשת ליצירת מארחים חדשים. מטעמים היסטורים, מנשקי API נקראים לפעמים „מחלקות”.

רוב מנשקי ה־API מכילים לפחות ארבע מתודות: get, create, update ו־delete למשיכה, יצירה, עדכון ומחיקה של נתונים בהתאמה, אך חלק ממנשקי ה־API עשויים לספק סדרה שונה לגמרי של מתודות.

תצוגה

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

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

רצף עבודה לדוגמה

הסעיף הבא יעבור אתך על מספר דוגמאות שימוש ביתר פירוט.

אימות

כדי לגשת לנתונים כלשהם ב-Zabix, אתה צריך:

השתמש ב-API token (נוצר ב-Zabbix frontend או באמצעות Token API);
השתמש באסימון אימות שהושג בשיטת user.login.

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

{
            "jsonrpc": "2.0",
            "method": "user.login",
            "params": {
                "username": "מנהל",
                "סיסמה": "zabbix"
            },
            "מזהה": 1,
            "auth": null
       }

בואו נסתכל מקרוב על אובייקט הבקשה. יש לו את הדברים הבאים נכסים:

jsonrpc - הגרסה של פרוטוקול JSON-RPC המשמשת את ה-API; ה-API של Zabbix מיישם JSON-RPC גרסה 2.0;
שיטה - שיטת ה-API הנקראת;
params - פרמטרים שיועברו לשיטת ה-API;
id - מזהה שרירותי של הבקשה;
auth - אסימון אימות משתמש; מכיוון שעדיין אין לנו אחד, הוא מוגדר ל'null'.

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

{
            "jsonrpc": "2.0",
            "result": "0424bd59b807674191e7d77572075f33",
            "מזהה": 1
       }

אובייקט התגובה מכיל בתורו את המאפיינים הבאים:

jsonrpc - שוב, הגרסה של פרוטוקול JSON-RPC;
תוצאה - הנתונים המוחזרים על ידי השיטה;
מזהה - מזהה של הבקשה המתאימה.

Authorization methods

By "Authorization" header

All API requests require an authentication or an API token. You can provide the credentials by using the "Authorization" request header:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

By "auth" property

An API request can be authorized by the "auth" property.

Note that the "auth" property is deprecated. It will be removed in the future releases.

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).

מאחזר מארחים

כעת יש לנו אסימון אימות משתמש חוקי שניתן להשתמש בו כדי לגשת הנתונים ב-Zabix. לדוגמה, בואו נשתמש ב- שיטת host.get כדי לאחזר את המזהים, שמות מארחים וממשקים של כל המוגדרים מארחים:

{
            "jsonrpc": "2.0",
            "method": "host.get",
            "params": {
                "פלט": [
                    "hostid",
                    "מנחה"
                ],
                "selectInterfaces": [
                    "interfaceid",
                    "ip"
                ]
            },
            "מזהה": 2,
            "auth": "0424bd59b807674191e7d77572075f33"
       }

::: הערה חשוב שימו לב שהמאפיין 'auth' מוגדר כעת ל- אסימון אימות שהשגנו בהתקשרות user.login. :::

אובייקט התגובה יכיל את הנתונים המבוקשים על המארחים:

{
            "jsonrpc": "2.0",
            "תוצאה": [
                {
                    "hostid": "10084",
                    "host": "שרת Zabbix",
                    "ממשקים": [
                        {
                            "interfaceid": "1",
                            "ip": "127.0.0.1"
                        }
                    ]
                }
            ],
            "מזהה": 2
       }

מטעמי ביצועים אנו ממליצים לרשום תמיד את מאפייני אובייקט שברצונך לאחזר ולהימנע מאחזור הכל.

יצירת פריט חדש

בואו ניצור פריט חדש ב-Zabbix server" באמצעות הנתונים שהשגנו מה-host.get הקודם בַּקָשָׁה. ניתן לעשות זאת על ידי שימוש ב- שיטת item.create:

{
            "jsonrpc": "2.0",
            "method": "item.create",
            "params": {
                "name": "שטח דיסק פנוי ב-/home/joe/",
                "key_": "vfs.fs.size[/home/joe/,free]",
                "hostid": "10084",
                "סוג": 0,
                "ערך_סוג": 3,
                "interfaceid": "1",
                "עיכוב": 30
            },
            "auth": "0424bd59b807674191e7d77572075f33",
            "מזהה": 3
       }

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

{
            "jsonrpc": "2.0",
            "תוצאה": {
                "itemids": [
                    "24759"
                ]
            },
            "מזהה": 3
       }

שיטת 'item.create' כמו גם שיטות יצירה אחרות יכול גם לקבל מערכים של אובייקטים וליצור מספר פריטים עם API אחד שִׂיחָה.

יצירת טריגרים מרובים

אז אם יצירת שיטות יקבלו מערכים, נוכל להוסיף מרובים triggers כך:

{
            "jsonrpc": "2.0",
            "method": "trigger.create",
            "פארמים": [
                {
                    "description": "עומס המעבד גבוה מדי ב-{HOST.NAME}",
                    "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
                },
                {
                    "description": "יותר מדי תהליכים ב-{HOST.NAME}",
                    "expression": "avg(/Linux server/proc.num[],5m)>300",
                }
            ],
            "auth": "0424bd59b807674191e7d77572075f33",
            "מזהה": 4
       }

תגובה מוצלחת תכיל את המזהים של הקוד החדש שנוצר טריגרים:

{
            "jsonrpc": "2.0",
            "תוצאה": {
                "טריגרידים": [
                    "17369",
                    "17370"
                ]
            },
            "מזהה": 4
       }

עדכון פריט

אפשר פריט, כלומר, הגדר את הסטטוס שלו ל-"0":

{
            "jsonrpc": "2.0",
            "method": "item.update",
            "params": {
                "itemid": "10092",
                "סטטוס": 0
            },
            "auth": "0424bd59b807674191e7d77572075f33",
            "מזהה": 5
       }

תגובה מוצלחת תכיל את המזהה של הפריט המעודכן:

{
            "jsonrpc": "2.0",
            "תוצאה": {
                "itemids": [
                    "10092"
                ]
            },
            "מזהה": 5
       }

שיטת 'item.update' כמו גם שיטות עדכון אחרות יכול גם לקבל מערכים של אובייקטים ולעדכן מספר פריטים עם API אחד שִׂיחָה.

עדכון של מספר טריגרים

אפשר מספר טריגרים, כלומר, הגדר את הסטטוס שלהם ל-0:

{
            "jsonrpc": "2.0",
            "method": "trigger.update",
            "פארמים": [
                {
                    "triggerid": "13938",
                    "סטטוס": 0
                },
                {
                    "triggerid": "13939",
                    "סטטוס": 0
                }
            ],
            "auth": "0424bd59b807674191e7d77572075f33",
            "מזהה": 6
       }

תגובה מוצלחת תכיל את המזהים של הטריגרים המעודכנים:

{
            "jsonrpc": "2.0",
            "תוצאה": {
                "טריגרידים": [
                    "13938",
                    "13939"
                ]
            },
            "מזהה": 6
       }

זוהי שיטת העדכון המועדפת. איזה API שיטות כמו host.massupdate מאפשרות לכתוב קוד פשוט יותר, אבל זה כן לא מומלץ להשתמש בשיטות אלה, מכיוון שהן יוסרו ב- מהדורות עתידיות.

טיפול בשגיאות

עד לנקודה זו כל מה שניסינו עבד מצוין. אבל מה קורה אם ננסה לבצע קריאה לא נכונה ל-API? בואו ננסה צור מארח נוסף על ידי התקשרות host.create אך השמטת ה- פרמטר 'קבוצות' חובה.

{
            "jsonrpc": "2.0",
            "method": "host.create",
            "params": {
                "host": "שרת לינוקס",
                "ממשקים": [
                    {
                        "סוג 1,
                        "ראשי": 1,
                        "useip": 1,
                        "ip": "192.168.3.1",
                        "dns": "",
                        "port": "10050"
                    }
                ]
            },
            "מזהה": 7,
            "auth": "0424bd59b807674191e7d77572075f33"
       }

התגובה תכיל אז הודעת שגיאה:

{
            "jsonrpc": "2.0",
            "שגיאה": {
                "קוד": -32602,
                "message": "פרמטרים לא חוקיים.",
                "data": "אין קבוצות עבור מארח \"שרת לינוקס\"."
            },
            "מזהה": 7
       }

אם אירעה שגיאה, במקום המאפיין 'result', התגובה אובייקט יכיל מאפיין 'שגיאה' עם הנתונים הבאים:

קוד - קוד שגיאה;
הודעה - סיכום שגיאה קצר;
נתונים - הודעת שגיאה מפורטת יותר.

שגיאות יכולות להתרחש במקרים שונים, כגון שימוש בקלט שגוי ערכים, פסק זמן של הפעלה או ניסיון לגשת לאובייקטים לא קיימים. שֶׁלְךָ האפליקציה אמורה להיות מסוגלת לטפל בחן מסוג זה של שגיאות.

גרסאות API

כדי לפשט את גירסאות ה-API, מאז Zabbix 2.0.4, הגרסה של ה-API תואם את הגרסה של Zabbix עצמה. אתה יכול להשתמש ב apiinfo.version למצוא להוציא את גרסת ה-API שאיתה אתה עובד. זה יכול להיות שימושי עבור התאמת האפליקציה שלך לשימוש בתכונות ספציפיות לגרסה.

אנו מבטיחים תאימות לאחור בתוך הגרסה העיקרית. כאשר מבצעים שינויים לא תואמים לאחור בין מהדורות גדולות, אנחנו בדרך כלל משאירים את התכונות הישנות כפי שהוצאו משימוש במהדורה הבאה, ו הסר אותם רק לאחר מכן במהדורה. מדי פעם, אנו עשויים להסיר תכונות בין מהדורות עיקריות מבלי לספק לאחור תְאִימוּת. חשוב שלעולם לא תסתמך על שום הוצאה משימוש תכונות והגר לחלופות חדשות יותר בהקדם האפשרי.

אתה יכול לעקוב אחר כל השינויים שבוצעו ב-API ב- לוג שינויים ב-API.

חומר נוסף לקריאה

עכשיו צברת מספיק ידע כדי להתחיל לעבוד עם ה־API של Zabbix, אבל למה לעצור שם. כדי להתעמק יותר אנו ממליצים לך לעיין ברשימת מנשקי ה־API הזמינים.

Documentation