שימוש ב-API Explorer

במדריך הזה מוסבר איך להשתמש ב-APIs Explorer כדי להתנסות ב-methods של Cloud Monitoring API. APIs Explorer הוא ווידג'ט שמצורף לדף הפניית API בארכיטקטורת REST עבור method. הוא מופיע כחלונית עם הכותרת ניסיון של ה-API הזה. בצילום המסך הבא אפשר לראות את החלונית כפי שהיא מוצגת למתודה עם פרמטר אחד בלבד, name:

הכלי APIs Explorer הוא דרך מצוינת לנסות שיטות ב-Cloud Monitoring API בלי לכתוב קוד. בווידג'ט מוצג טופס עם הפרמטרים של כל שיטה. ממלאים את הטופס, לוחצים על הלחצן הפעלה ורואים את התוצאות.

אפשר גם להסתיר את הווידג'ט בלחיצה על הלחצן , או להרחיב את הווידג'ט למסך מלא בלחיצה על הלחצן .

הערה: אם מרחיבים את API Explorer למסך מלא, אפשר לראות את הבקשה כפקודת curl, כבקשת HTTP וכקוד JavaScript.

כפתורים לניסיון

בתיעוד, יכול להיות שתראו לחצנים של Try It! כמו אלה:

רוצים לנסות?

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

מידע על מניעת שגיאות ותיקון שלהן זמין במאמר פתרון בעיות.

גישה ל-API Explorer

‫API Explorer מצורף לדף העיון של כל method של API בארכיטקטורת REST. כדי למצוא את הווידג'ט, אפשר לעיין בדף העזר של שיטה מסוימת, למשל metricDescriptors.list.

ביצוע בקשה

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

השיטה metricDescriptors.list מחזירה תיאורים של כל סוגי המדדים שזמינים בפרויקט. הפרמטר היחיד שחובה לציין הוא הפרמטר name.

כדי להפעיל את השיטה metricDescriptors.list:

1. לוחצים על אני רוצה לנסות.
2. בפרמטר name, מזינים את מזהה הפרויקט בפורמט projects/PROJECT_ID. חשוב להחליף את PROJECT_ID במזהה הפרויקט.
3. לוחצים על Execute. כדי להריץ את הפקודה, ל-APIs Explorer צריכה להיות גישה לחשבון שלכם. כשמופיעה בקשה, בוחרים חשבון ולוחצים על אישור. הגישה היא לתקופה מוגבלת ומוגבלת לשיטת ה-API שאתם מפעילים.

תוצאות ההפעלה של המתודה מופיעות בתיבה עם כותרת ירוקה או אדומה. אם הבקשה מצליחה, התיבה כוללת כותרת ירוקה עם קוד הסטטוס 200 של HTTP. תוצאות ההפעלה מופיעות בתיבה:

אם הכותרת אדומה, היא מכילה קוד שגיאה של HTTP, והתיבה מכילה את הודעת השגיאה. מידע על פתרון שגיאות זמין במאמר פתרון בעיות.

הערה: אחרי שמגדירים את APIs Explorer ולוחצים על Execute, כתובת ה-URL של הדף משתנה. אפשר להוסיף לסימנייה את כתובת ה-URL המעודכנת. כשרוצים להפעיל את השיטה שוב, לוחצים על הסימנייה כדי לפתוח את הדף עם הטופס שכבר מאוכלס בבחירות הקודמות.

הוספת פרמטרים

רשימת הפרמטרים שמוצגת תלויה בשיטה שאליה מצורף הווידג'ט של כלי ה-APIs Explorer. לדוגמה, לשיטה metricDescriptors.list יש יותר מהפרמטר name, אבל name הוא הפרמטר היחיד שנדרש.

אם מציינים רק את שם הפרויקט, מקבלים את כל תיאורי המדדים שזמינים בפרויקט, ויש הרבה כאלה. כדי להגביל את השליפה לקבוצה קטנה יותר, משתמשים בפרמטר filter.

לדוגמה, כדי להציג רק את סוגי המדדים שהשם שלהם מסתיים ב-utilization, מבצעים את הפעולות הבאות:

1. לוחצים על אני רוצה לנסות.

2. בפרמטר name, מזינים את מזהה הפרויקט בפורמט projects/PROJECT_ID. חשוב להחליף את PROJECT_ID במזהה הפרויקט.

3. צריך לוודא שהערך של הפרמטר filter הוא metric.type=ends_with("utilization")

4. לוחצים על Execute (הפעלה) ומשלימים את תיבות הדו-שיח של ההרשאה.

פרמטרים רגילים

כברירת מחדל, קבוצת הפרמטרים שמוצגת ב-APIs Explorer תואמת לפרמטרים של השיטה המשויכת. עם זאת, לווידג'ט APIs Explorer יש גם קבוצה של פרמטרים נוספים שלא נכללים בשיטה עצמה. כדי להציג את הפרמטרים הנוספים, לוחצים על הצגת פרמטרים רגילים:

כדי להסתיר את הפרמטרים הנוספים מהתצוגה, לוחצים על הסתרת פרמטרים רגילים.

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

לדוגמה, גם אם מפרטים את השמות של מדדים שמסתיימים ב-utilization, עדיין מתקבלות הרבה תוצאות. אם אתם רוצים לדעת רק את השם של סוג המדד והתיאור שלו, אתם יכולים לציין את ההגבלה הזו באמצעות הפרמטר fields.

כדי לראות את התוצאה של הגדרת הפרמטר fields, מבצעים את הפעולות הבאות:

1. לוחצים על אני רוצה לנסות.

2. בפרמטר name, מזינים את מזהה הפרויקט בפורמט projects/PROJECT_ID. חשוב להחליף את PROJECT_ID במזהה הפרויקט.

3. צריך לוודא שהערך של הפרמטר filter הוא metric.type=ends_with("utilization")

4. לוחצים על הצגת פרמטרים רגילים ומוודאים שלפרמטר fields יש את הערך metricDescriptors.type,metricDescriptors.description

5. לוחצים על Execute (הפעלה) ומשלימים את תיבות הדו-שיח של ההרשאה.

הפעלת הבקשה הזו מחזירה רק את type (השם המקוצר) של כל מדד ואת description שלו.

פתרון בעיות

בקטע הזה מתוארות בעיות נפוצות בשימוש ב-APIs Explorer.

מידע נוסף על שימוש ב-Cloud Monitoring API זמין במאמר בנושא פתרון בעיות ב-Cloud Monitoring API.

תחביר מסנן לא תקין

אתם מעתיקים ביטוי רב-שורה ומדביקים אותו בשדה שמוצג ב-APIs Explorer, אבל ב-APIs Explorer מוצגת הודעת שגיאה.

כן: מוודאים שהמחרוזות נמצאות בשורה אחת.

"query": "sum by (instance_name) (rate({\"compute.googleapis.com/instance/disk/read_bytes_count\", monitored_resource=\"gce_instance\"}[5m]))"

לא: להעתיק ולהדביק תווים של המשך שורה או שורה חדשה.

מזהה הפרויקט לא תקין

אם מזהה הפרויקט לא תקין, בקשת ה-API נכשלת עם שגיאת HTTP‏ 400.

כדי לפתור את הבעיה הזו, צריך לוודא שהטקסט PROJECT_ID הוחלף במזהה הפרויקט.

הערכים בטופס לא תקינים

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

הפרמטרים של הכלי APIs Explorer צריכים להיות בפורמט ספציפי. טעויות בעיצוב יכולות לגרום לשגיאות, או שהן יתקבלו אבל יטופלו כמו שגיאות איות בשיטת ה-API:

• אסור להשתמש במירכאות סביב ערכי פרמטרים מכל סוג.

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

  לדוגמה, הדוגמה הבאה היא לשיטה ב-API שבה מזינים את התוכן כ-JSON, במקום להשלים פרמטרים נפרדים בטופס. מכיוון שהערך של filter הוא מחרוזת, מחרוזת המשנה k8s_cluster מוגנת על ידי לוכסנים הפוכים:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

• מחרוזות במירכאות שמופיעות בתוך מסננים. משתמשים במירכאות כפולות (") ולא בגרשיים ('). דוגמה מופיעה במאמר הוספת פרמטרים נוספים.

• אל תשתמשו בקידוד כתובות URL בטופס. אם שיטת API דורשת קידוד URL, הווידג'ט מבצע את ההמרה כשמריצים את השיטה.

מוחזרים יותר מדי נתונים

כדי להגביל את מספר התוצאות שמוחזרות, בפרמטר pageSize, מזינים ערך, כמו 2. הפרמטר pageSize מגדיר את המספר המקסימלי של התוצאות שמוחזרות, והוא זמין לרוב שיטות ה-API.

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

אימות

בדף API Explorer יש קטע Credentials. מומלץ להשאיר את ערכי ברירת המחדל בשדות האלה. מנגנון האימות שמוגדר כברירת מחדל הוא Google OAuth 2.0.

כדי לראות אילו היקפי הרשאות של API נדרשים לשיטה, לוחצים על Show scopes (הצגת היקפי הרשאות). כברירת מחדל, כל היקפי ההרשאות הנדרשים ניתנים.

למידע נוסף על המושגים האלה, אפשר לקרוא את המאמר בקרת גישה באמצעות ניהול זהויות והרשאות גישה.