מבוא
בדף הזה נסביר איך להשתמש ב-Service Control API v2 לדיווחי טלמטריה של שירותים מנוהלים המשולבים עם Service Infrastructure. דף זה מיועד לבעלים של שירותים מנוהלים שרוצים לשלב בצורה עמוקה את השירותים שלהם ב-Google Cloud.
Service Infrastructure היא פלטפורמה בסיסית למפתחים ליצירה, לניהול, לאבטחה ולצריכה של ממשקי API ושירותים. נעשה בה שימוש במודל פשוט וגנרי של שימוש בשירות: הצרכן צורך שירות שמנוהל על ידי בעלים. המודל הזה משמש בכל Google APIs ו-Google Cloud APIs, מאחר שגם הם מבוססים על Service Infrastructure.
כשצרכן ניגש לשירות, השירות מדַווח לפלטפורמה את נתוני הטלמטריה הרלוונטיים וכך גם הצרכן וגם הבעלים יכולים לצפות בגישה. התהליך הזה ב-Service Infrastructure נקרא 'דיווח טלמטריה', והוא כולל ניתוח נתונים, בקרה, חיוב, רישום ביומן ומעקב.
Service Control API v2
ב-Service Control API v2 מוצע method פשוט של services.report, שמספק דיווחי טלמטריה לכל השירותים שמשולבים עם Service Infrastructure. בעזרתו תוכלו לבצע את הפעולות הבאות בהפעלת method אחת:
- ניתוח נתונים
- ביצוע בקרה
- חיוב
- רישום ביומן
- מעקב
כששירות מדווח על נתוני טלמטריה ל-Service Control API, הנתונים מופצים לצרכן, לבעלים, או לשניהם בהתאם להגדרת השירות. למידע נוסף על הגדרת טלמטריה, כדאי לעיין בקטעים לגבי רישום ביומן ומעקב ב-google.api.Service.
כדי ששירות יבצע קריאה ל-Service Control API, הבעלים צריך להפעיל את Service Control API בפרויקט של הבעלים. למי שביצע את הקריאה צריכות להיות הרשאות מתאימות בשירות. מידע נוסף זמין במאמר תחילת השימוש ב-Cloud APIs ובמאמר בקרת גישה ל-Service Control API.
מאפייני הבקשות
כשלקוח נכנס לשירות, השירות צריך לתכנן את הכניסה בהתאם לקבוצה של בקשות API, ולתאר כל בקשה באמצעות AttributeContext.
כדי לדווח על מדדי API באמצעות Service Control API, השירות צריך להפעיל method services.report לכל בקשה עם המאפיינים שמפורטים בהמשך. ה-Service Control API ייצור את מדדי ה-API וישלח אותם אל Cloud Monitoring.
| מאפיין | תיאור | דוגמה |
|---|---|---|
origin.ip |
כתובת ה-IP של מבצע הקריאה. | "1.2.3.4" |
api.service |
שם השירות של ה-API. | "endpointsapis.appspot.com" |
api.operation |
שם ה-method של ה-API. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
המחרוזת של גרסת ה-API. | "v1" |
api.protocol |
שם הפרוטוקול של ה-API. | "https" |
request.id |
מזהה בקשה ייחודי. | "123e4567-e89b-12d3-a456-426655440000" |
request.time |
חותמת הזמן של הבקשה. | "2019-07-31T05:20:00Z" |
request.method |
שם ה-method של ה-HTTP. | "POST" |
request.scheme |
הסכימה של כתובת ה-URL. | "https" |
request.host |
הכותרת של מארח ה-HTTP. | "endpointsapis.appspot.com" |
request.path |
נתיב כתובת ה-URL. | "/v1/hello" |
response.code |
קוד הסטטוס של התשובה. | 200 |
response.size |
גודל התשובה בבייטים. | 100 |
response.time |
חותמת הזמן של התשובה. | "2019-07-31T05:20:02Z" |
response.backend_latency |
זמן האחזור של הקצה העורפי. | "0.007s" |
דיווח על נתוני טלמטריה
אחרי שפורסים את הגדרת השירות ל-Service Management API והשירות מוכן למלא בקשות מלקוחות, אפשר להתחיל לבצע קריאות ל-services.report עבור השירות שנפרס. צריך להפעיל את services.report כדי לבצע דיווחי טלמטריה בכל פעם שהשירות מקבל בקשה.
כדי להתנסות במהירות בדיווחי טלמטריה, תוכלו להשתמש בפקודה gcurl כדי להפעיל את method services.report. מידע על שלבי ההגדרה הראשונית מופיע במאמר תחילת השימוש ב-Service Control API.
בדוגמה הבאה מוצגת המחשה לשימוש בפקודה gcurl כדי להפעיל את services.report על גבי HTTP:
gcurl -d '{
"service_config_id": "latest",
"operations": [{
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
"version": "v1",
"protocol": "https"
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"size": 50,
"time": "2019-07-31T05:20:00Z",
},
"response": {
"size": 100,
"code": 200,
"time": "2019-07-31T05:20:02Z",
"backend_latency": "0.007s"
},
"destination": {
"region_code": "us-central1"
}
"resource": {
"name": "projects/123/locations/us-central1/workspaces/default"
}
}]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report
אם הפעולה בוצעה ללא שגיאות, התשובה מ-method services.report אמורה להיות ריקה. אם הפעולה נכשלה, שגיאת ה-API אמורה לכלול מידע מפורט לגבי השגיאה.
מידע נוסף על טיפול בשגיאות זמין במאמר מדריך לעיצוב API > שגיאות.
בשירותים בסביבת ייצור, צריך להשתמש באחת מספריות הלקוח ש-Google מספקת כדי לקרוא ל-Service Control API. הספריות האלה נוחות לשימוש ובעזרתן אפשר לטפל באופן אוטומטי בפעולות נפוצות כמו אימות. מידע נוסף זמין במאמר הסבר על ספריות לקוח.