אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע
Edge Analytics מספקת מגוון רחב של מרכזי בקרה אינטראקטיביים, מחוללי דוחות בהתאמה אישית ויכולות קשורות. עם זאת, התכונות האלה מיועדות להיות אינטראקטיביות: אתם שולחים בקשת API או בקשת ממשק משתמש, והבקשה נחסמת עד ששרת הניתוח מספק תגובה.
עם זאת, יכול להיות שיתרחש פסק זמן בבקשות ניתוח נתונים אם השלמתן תימשך יותר מדי זמן. אם בקשת שאילתה צריכה לעבד כמות גדולה של נתונים (לדוגמה, מאות ג'יגה-בייט), יכול להיות שהיא תיכשל בגלל פסק זמן.
עיבוד שאילתות אסינכרוניות מאפשר לכם להריץ שאילתות על מערכי נתונים גדולים מאוד ולאחזר את התוצאות במועד מאוחר יותר. כדאי להשתמש בשאילתה אופליין אם אתם מגלים ששאילתות אינטראקטיביות נכשלות בגלל פסק זמן. הנה כמה מצבים שבהם עיבוד אסינכרוני של שאילתות יכול להיות חלופה טובה:
- ניתוח ויצירה של דוחות שכוללים מרווחי זמן גדולים.
- ניתוח נתונים עם מגוון של מאפייני קיבוץ ומגבלות אחרות שמסבכות את השאילתה.
- ניהול שאילתות כשמגלים שנפחי הנתונים גדלו באופן משמעותי אצל חלק מהמשתמשים או הארגונים.
במאמר הזה מוסבר איך להפעיל שאילתות אסינכרוניות באמצעות ה-API. אפשר גם להשתמש בממשק המשתמש, כמו שמתואר במאמר הפעלת דוח בהתאמה אישית.
השוואה בין Reports API לבין ממשק המשתמש
במאמר יצירה וניהול של דוחות בהתאמה אישית מוסבר איך להשתמש בממשק המשתמש של Edge כדי ליצור ולהריץ דוחות בהתאמה אישית. אפשר להריץ את הדוחות האלה באופן סינכרוני או אסינכרוני.
רוב המושגים שקשורים ליצירת דוחות בהתאמה אישית באמצעות ממשק המשתמש רלוונטיים גם לשימוש ב-API. כלומר, כשיוצרים דוחות בהתאמה אישית באמצעות ה-API, מציינים מדדים, מאפיינים ומסננים שמוטמעים ב-Edge, וגם מדדים מותאמים אישית שיצרתם באמצעות מדיניות StatisticsCollector.
ההבדלים העיקריים בין הדוחות שנוצרים בממשק המשתמש לבין הדוחות שנוצרים באמצעות ה-API הם שהדוחות שנוצרים באמצעות ה-API נכתבים לקובצי CSV או JSON (עם תווי מעבר שורה), במקום לדוח חזותי שמוצג בממשק המשתמש.
מגבלות ב-Apigee Hybrid
ב-Apigee Hybrid יש מגבלת גודל של 30MB על מערך נתוני התוצאות.
איך מבצעים שאילתת ניתוח אסינכרונית
כדי לבצע שאילתות אסינכרוניות של נתוני Analytics, צריך לבצע שלושה שלבים:
שלב 1. שליחת השאילתה
צריך לשלוח בקשת POST ל-API /queries. ה-API הזה אומר ל-Edge לעבד את הבקשה ברקע. אם השליחה של השאילתה תצליח, ה-API יחזיר סטטוס 201 ומזהה שבו תשתמשו כדי להתייחס לשאילתה בשלבים הבאים.
לדוגמה:
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file -u orgAdminEmail:password
גוף הבקשה הוא תיאור של השאילתה ב-JSON. בגוף ה-JSON, מציינים את המדדים, המאפיינים והמסננים שמגדירים את הדוח.
קובץ json-query-file לדוגמה:
{
"metrics": [
{
"name": "message_count",
"function": "sum",
"alias": "sum_txn"
}
],
"dimensions": ["apiproxy"],
"timeRange": "last24hours",
"limit": 14400,
"filter":"(message_count ge 0)"
}
בקטע 'מידע על גוף הבקשה' שבהמשך מופיע תיאור מלא של תחביר גוף הבקשה.
דוגמה לתשובה:
שימו לב שמזהה השאילתה 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd כלול בתשובה. בנוסף לקוד הסטטוס HTTP 201, הערך state של enqueued מציין שהבקשה הצליחה.
HTTP/1.1 201 Created
{
"self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
"created":"2018-05-10T07:11:10Z",
"state":"enqueued",
"error":"false",
}
שלב 2. קבלת סטטוס השאילתה
מבצעים קריאת GET כדי לבקש את הסטטוס של השאילתה. אתם מספקים את מזהה השאילתה שהוחזר מקריאת ה-POST. לדוגמה:
curl -X GET -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd -u email:password
תשובות לדוגמה:
אם השאילתה עדיין בתהליך, תקבלו תשובה כמו זו, שבה state הוא running:
{
"self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
"state": "running",
"created": "2018-02-23T14:07:27Z",
"updated": "2018-02-23T14:07:54Z"
}
אחרי שהשאילתה תושלם בהצלחה, תופיע תגובה כמו זו, שבה הערך של state הוא completed:
{
"self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
"state": "completed",
"result": {
"self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
"expires": "2017-05-22T14:56:31Z"
},
"resultRows": 1,
"resultFileSize": "922KB",
"executionTime": "11 sec",
"created": "2018-05-10T07:11:10Z",
"updated": "2018-05-10T07:13:22Z"
}
שלב 3. אחזור תוצאות השאילתה
אחרי שהסטטוס של השאילתה יהיה completed, תוכלו להשתמש ב-API של get results כדי לאחזר את התוצאות. מזהה השאילתה יהיה שוב 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.
curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result -u email:password
כדי לאחזר את הקובץ שהורדתם, אתם צריכים להגדיר את הכלי שבו אתם משתמשים כך שישמור קובץ שהורדתם במערכת. לדוגמה:
אם אתם משתמשים ב-cURL, אתם יכולים להשתמש באפשרויות
-O -J, כמו שמוצג למעלה.אם אתם משתמשים ב-Postman, אתם צריכים ללחוץ על הלחצן שמירה והורדה. במקרה כזה, קובץ ZIP בשם
responseיורד.אם משתמשים בדפדפן Chrome, ההורדה מאושרת באופן אוטומטי.
אם הבקשה מצליחה ויש קבוצת תוצאות לא ריקה, התוצאה מורדת ללקוח כקובץ JSON (מופרד בשורות חדשות) דחוס. השם של הקובץ שהורדתם יהיה:
OfflineQueryResult-<query-id>.zip
לדוגמה:
OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
קובץ ה-ZIP מכיל קובץ ארכיון .gz של תוצאות ה-JSON. כדי לגשת לקובץ ה-JSON, צריך לבטל את הדחיסה של קובץ ההורדה ואז להשתמש בפקודה gzip כדי לחלץ את קובץ ה-JSON:
unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gzמידע על גוף הבקשה
בקטע הזה מתואר כל אחד מהפרמטרים שאפשר להשתמש בהם בגוף הבקשה בפורמט JSON לשאילתה. פרטים על המדדים והמאפיינים שבהם אפשר להשתמש בשאילתה זמינים במאמר הפניה ל-Analytics.
{ "metrics":[ { "name":"metric_name", "function":"aggregation_function", "alias":"metric_dispaly_name_in_results", "operator":"post_processing_operator", "value":"post_processing_operand" }, ... ], "dimensions":[ "dimension_name", ... ], "timeRange":"time_range", "limit":results_limit, "filter":"filter", "groupByTimeUnit": "grouping", "outputFormat": "format", "csvDelimiter": "delimiter" }
| נכס | תיאור | חובה? |
|---|---|---|
metrics
|
מערך של מדדים. אפשר לציין מדד אחד או יותר לשאילתה, כאשר כל מדד כולל: צריך להזין רק את שם המדד:
המאפיינים "metrics":[
{
"name":"response_processing_latency",
"function":"avg",
"alias":"average_response_time_in_seconds",
"operator":"/",
"value":"1000"
}
]מידע נוסף זמין במאמר הפניה למדדים, למאפיינים ולמסננים ב-Analytics. |
לא |
dimensions
|
מערך של מאפיינים לקבוץ המדדים. מידע נוסף זמין ברשימת המאפיינים הנתמכים. אפשר לציין כמה מאפיינים. | לא |
timeRange
|
טווח הזמן של השאילתה.
אפשר להשתמש במחרוזות המוגדרות מראש הבאות כדי לציין את טווח הזמן:
אפשר גם לציין את "timeRange": {
"start": "2018-07-29T00:13:00Z",
"end": "2018-08-01T00:18:00Z"
} |
כן |
limit
|
המספר המקסימלי של שורות שאפשר להחזיר בתוצאה. | לא |
filter
|
ביטוי בוליאני שאפשר להשתמש בו לסינון נתונים. אפשר לשלב בין ביטויי סינון באמצעות המונחים AND/OR, וצריך להוסיף סוגריים לכל הביטוי כדי למנוע דו-משמעות. מידע נוסף על השדות שאפשר לסנן לפי זמין במאמר הפניה למדדים, למאפיינים ולמסננים של Analytics. מידע נוסף על הטוקנים שבהם משתמשים כדי ליצור ביטויי סינון זמין במאמר תחביר של ביטויי סינון. | לא |
groupByTimeUnit
|
יחידת הזמן שמשמשת לקיבוץ של מערך התוצאות. הערכים התקפים כוללים: second, minute, hour, day, week או month.
אם שאילתה כוללת את |
לא |
outputFormat
|
פורמט הפלט. הערכים התקפים כוללים: csv או json. ברירת המחדל היא json
שמתאימה ל-JSON שמופרד בתו שורה חדשה.
הערה: כדי להגדיר את התו שמפריד בין הערכים בקובץ CSV, צריך להשתמש במאפיין |
לא |
csvDelimiter
|
התו המפריד שמשמש בקובץ ה-CSV, אם הערך של outputFormat הוא csv. ברירת המחדל היא התו , (פסיק). תווי המפריד הנתמכים כוללים פסיק (,), קו אנכי (|) וטאב (\t).
|
לא |
תחביר של ביטוי סינון
בקטע הזה מוסבר על האסימונים שאפשר להשתמש בהם כדי ליצור ביטויי סינון בגוף הבקשה. לדוגמה, בביטוי הבא נעשה שימוש בטוקן ge (גדול או שווה ל):
"filter":"(message_count ge 0)"
| אסימון | תיאור | דוגמאות |
|---|---|---|
in
|
הכללה ברשימה | (apiproxy in 'ethorapi','weather-api') (apiproxy in 'ethorapi') (apiproxy in 'Search','ViewItem') (response_status_code in 400,401,500,501) הערה: מחרוזות חייבות להיות במירכאות. |
notin
|
החרגה מהרשימה | (response_status_code notin 400,401,500,501) |
eq
|
שווה ל- (==)
|
(response_status_code eq 504) (apiproxy eq 'non-prod') |
ne
|
לא שווה לערך (!=)
|
(response_status_code ne 500) (apiproxy ne 'non-prod') |
gt
|
גדול מ->)
|
(response_status_code gt 500) |
lt
|
פחות מ-<)
|
(response_status_code lt 500) |
ge
|
גדול מ- או שווה ל- (>=)
|
(target_response_code ge 400) |
le
|
קטן מהערך <=) או שווה לו
|
(target_response_code le 300) |
like
|
הפונקציה מחזירה את הערך True אם מחרוזת התבנית תואמת לתבנית שצוינה.
הדוגמה משמאל מתאימה באופן הבא: – כל ערך שמכיל את המילה buy - כל ערך שמסתיים ב-item – כל ערך שמתחיל ב-Prod – כל ערך שמתחיל ב-4, שימו לב ש-response_status_code הוא מספרי
|
(apiproxy like '%buy%') (apiproxy like '%item') (apiproxy like 'Prod%') |
not like
|
הפונקציה מחזירה false אם דפוס המחרוזת תואם לדפוס שצוין. | (apiproxy not like '%buy%') (apiproxy not like '%item') (apiproxy not like 'Prod%') |
and
|
מאפשר להשתמש בלוגיקת 'וגם' כדי לכלול יותר מביטוי סינון אחד. המסנן כולל נתונים שעומדים בכל התנאים. | (target_response_code gt 399) and (response_status_code ge 400) |
or
|
מאפשר להשתמש בלוגיקה של 'או' כדי להעריך ביטויים שונים של מסננים. המסנן כולל נתונים שעומדים לפחות באחד מהתנאים. | (response_size ge 1000) or (response_status_code eq 500) |
מגבלות וערכי ברירת מחדל
בהמשך מפורטות מגבלות וערכי ברירת מחדל של התכונה לעיבוד שאילתות אסינכרוני.
| מגבלה | ברירת מחדל | תיאור |
|---|---|---|
| מגבלת שאילתות לשיחה | הצגת התיאור | אפשר לבצע עד שבע קריאות בשעה ל-Management API /queries כדי להפעיל דוח אסינכרוני. אם חורגים ממכסת השיחות, ה-API מחזיר תגובה מסוג HTTP 429. |
| מגבלת שאילתות פעילות | 10 | אפשר להפעיל עד 10 שאילתות פעילות לארגון או לסביבה. |
| סף של זמן ביצוע שאילתה | 6 שעות | שאילתות שנמשכות יותר מ-6 שעות יופסקו. |
| טווח הזמן של השאילתות | הצגת התיאור | טווח הזמן המקסימלי שמותר להגדיר בשאילתה הוא 365 ימים. |
| מגבלת המאפיינים והמדדים | 25 | המספר המקסימלי של מאפיינים ומדדים שאפשר לציין במטען הייעודי למטען של השאילתה. |
מידע על תוצאות השאילתה
הנה דוגמה לתוצאה בפורמט JSON. הפלט מורכב משורות JSON שמופרדות באמצעות תו מפריד שורה חדשה:
{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}
…
אפשר לאחזר את התוצאות מכתובת ה-URL עד שתוקף הנתונים במאגר יפוג. מגבלות וערכי ברירת מחדל
דוגמאות
דוגמה 1: סיכום של מספר ההודעות
שאילתה לחישוב סכום מספרי ההודעות ב-60 הדקות האחרונות.
שאילתה
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
גוף הבקשה מתוך last60minutes.json
{
"metrics":[
{
"name":"message_count",
"function":"sum"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":"last60minutes"
}
דוגמה 2: טווח תאריכים בהתאמה אישית
אפשר להריץ שאילתה באמצעות טווח תאריכים מותאם אישית.
שאילתה
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
תוכן הבקשה מתוך last60minutes.json
{
"metrics":[
{
"name":"message_count",
"function":"sum"
},
{
"name":"total_response_time",
"function":"avg",
"alias":"average_response_time"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-11-01T11:00:00Z",
"end":"2018-11-30T11:00:00Z"
}
}
דוגמה 3: עסקאות לדקה
שאילתה על המדד של עסקאות בדקה (tpm).
שאילתה
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @tpm.json -u orgAdminEmail:password
גוף הבקשה מ-tpm.json
{
"metrics":[
{
"name":"tpm"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-07-01T11:00:00Z",
"end":"2018-07-30T11:00:00Z"
}
}
תוצאה לדוגמה
קטע מקובץ התוצאות:
{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...דוגמה 4: שימוש בביטוי סינון
שאילתה עם ביטוי סינון שמשתמש באופרטור בוליאני.
שאילתה
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @filterCombo.json -u orgAdminEmail:password
גוף הבקשה מ-filterCombo.json
{
"metrics":[
{
"name":"message_count",
"function":"sum"
},
{
"name":"total_response_time",
"function":"avg",
"alias":"average_response_time"
}
],
"filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-11-01T11:00:00Z",
"end":"2018-11-30T11:00:00Z"
}
}
דוגמה 5: העברת ביטוי בפרמטר metrics
שאילתה עם ביטוי שמועבר כחלק מפרמטר המדדים. אפשר להשתמש רק בביטויים פשוטים עם אופרטור אחד.
שאילתה
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @metricsExpression.json -u orgAdminEmail:password
תוכן הבקשה מ-metricsExpression.json
{
"metrics":[
{
"name":"message_count",
"function":"sum",
"operator":"/",
"value":"7"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":10,
"timeRange":"last60minutes"
}
איך מבצעים שאילתה אסינכרונית בדוח מונטיזציה
אפשר לתעד את כל עסקאות המונטיזציה שהושלמו בטווח זמן מסוים לפי קבוצה ספציפית של קריטריונים באמצעות השלבים שמתוארים בקטע הזה.
בדומה לשאילתות אסינכרוניות של ניתוח נתונים, גם שאילתות אסינכרוניות של דוחות מונטיזציה מתבצעות בשלושה שלבים: (1) שליחת השאילתה, (2) קבלת סטטוס השאילתה ו-(3) אחזור תוצאות השאילתה.
שלב 1, שליחת השאילתה, מתואר בהמשך.
שלבים 2 ו-3 זהים בדיוק לאלה של שאילתות ניתוח אסינכרוניות. מידע נוסף זמין במאמר איך מבצעים שאילתת ניתוח נתונים אסינכרונית.
כדי לשלוח שאילתה לדוח מונטיזציה אסינכרוני, שולחים בקשת POST אל /mint/organizations/org_id/async-reports.
אפשר גם לציין את הסביבה באמצעות הפרמטר environment של השאילתה. אם לא מציינים את הפרמטר של השאילתה, ערך ברירת המחדל הוא prod. לדוגמה:
/mint/organizations/org_id/async-reports?environment=prod
בגוף הבקשה, מציינים את קריטריוני החיפוש הבאים.
| שם | תיאור | ברירת מחדל | חובה? |
appCriteria |
המזהה והארגון של אפליקציה ספציפית שרוצים לכלול בדוח. אם לא מציינים את הנכס הזה, כל האפליקציות נכללות בדוח. | לא רלוונטי | לא |
billingMonth |
חודש החיוב של הדוח, כמו JULY. | לא רלוונטי | כן |
billingYear |
שנת החיוב של הדוח, למשל 2015. | לא רלוונטי | כן |
currencyOption |
המטבע שמוצג בדוח. הערכים התקפים כוללים:
אם בוחרים EUR, GBP או USD, הדוח יציג את כל העסקאות במטבע הזה, על סמך שער החליפין שהיה בתוקף בתאריך העסקה. |
לא רלוונטי | לא |
devCriteria
|
מזהה המפתח או כתובת האימייל ושם הארגון של מפתח ספציפי שרוצים לכלול בדוח. אם לא מציינים את המאפיין הזה, כל המפתחים נכללים בדוח. לדוגמה: "devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"my_org"}
] |
לא רלוונטי | לא |
fromDate
|
תאריך ההתחלה של הדוח בפורמט UTC. | לא רלוונטי | כן |
monetizationPakageIds |
מזהה של חבילת API אחת או יותר שרוצים לכלול בדוח. אם לא מציינים את הנכס הזה, כל חבילות ה-API נכללות בדוח. | לא רלוונטי | לא |
productIds
|
מזהה של מוצר API אחד או יותר שרוצים לכלול בדוח. אם לא מציינים את המאפיין הזה, כל מוצרי ה-API נכללים בדוח. | לא רלוונטי | לא |
ratePlanLevels |
סוג תוכנית התמחור שייכלל בדוח. הערכים התקפים כוללים:
אם לא מציינים את המאפיין הזה, גם תוכניות מחירים ספציפיות למפתחים וגם תוכניות מחירים רגילות נכללות בדוח. |
לא רלוונטי | לא |
toDate
|
תאריך הסיום של הדוח לפי שעון UTC. | לא רלוונטי | כן |
לדוגמה, הבקשה הבאה יוצרת דוח אסינכרוני על מונטיזציה לחודש יוני 2017 עבור מוצר ה-API ומזהה המפתח שצוינו. התאריכים והשעות בדוחות fromDate ו-toDate הם ב-UTC/GMT ויכולים לכלול שעות.
curl -H "Content-Type:application/json" -X POST -d \
'{
"fromDate":"2017-06-01 00:00:00",
"toDate":"2017-06-30 00:00:00",
"productIds": [
"a_product"
],
"devCriteria": [{
"id": "AbstTzpnZZMEDwjc",
"orgId": "myorg"
}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password