אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info
Edge Analytics מספק קבוצה עשירה של מרכזי בקרה אינטראקטיביים, גנרטורים של דוחות בהתאמה אישית ויכולות קשורות. עם זאת, התכונות האלה נועדו להיות אינטראקטיביות: שולחים בקשת API או בקשת UI, והבקשה חסומה עד ששרת הניתוח מספק תשובה.
עם זאת, אם הבקשות לניתוח נתונים נמשכות יותר מדי זמן, הן עשויות לפוג. אם בקשת שאילתה צריכה לעבד כמות גדולה של נתונים (לדוגמה, מאות ג'יגה-בייט), יכול להיות שהיא תיכשל בגלל זמן קצוב לתפוגה.
עיבוד שאילתות אסינכרוני מאפשר לבצע שאילתות על מערכים גדולים מאוד של נתונים ולאחזר את התוצאות במועד מאוחר יותר. אם חל הזמן הקצוב לשאילתות האינטראקטיביות, כדאי לשקול להשתמש בשאילתה אופליין. יש כמה מצבים שבהם עיבוד שאילתות אסינכרוני יכול להיות חלופה טובה, למשל:
- ניתוח יצירת דוחות שמתפרסים על פני מרווחי זמן ארוכים.
- ניתוח נתונים באמצעות מגוון מאפייני קיבוץ ואילוצים אחרים שמוסיפים מורכבות לשאילתה.
- ניהול שאילתות כשאתם מגלים שהנפח של הנתונים גדל באופן משמעותי אצל משתמשים או ארגונים מסוימים.
במסמך הזה נסביר איך להפעיל שאילתות אסינכררוניות באמצעות ה-API. אפשר גם להשתמש בממשק המשתמש, כפי שמתואר בקטע הרצת דוח בהתאמה אישית.
השוואה בין ה-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, צריך ללחוץ על הלחצן Save and Download (שמירה והורדה). במקרה כזה, מתבצע הורדה של קובץ 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
Request Body מ-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