אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.
הכלי Edge Analytics כולל קבוצה עשירה של מרכזי בקרה אינטראקטיביים, מחוללי דוחות בהתאמה אישית ויכולות קשורות. עם זאת, התכונות האלה מיועדות להיות אינטראקטיביות: אתם שולחים בקשת API או ממשק משתמש, והבקשה חסומה עד ששרת ניתוח הנתונים מספק תשובה.
עם זאת, הזמן הקצוב לתפוגה של בקשות לניתוח נתונים עשוי להימשך זמן רב מדי. אם בבקשת שאילתה נדרש עיבוד כמויות גדולות של נתונים (לדוגמה, 100GB), יכול להיות שהזמן הקצוב לתפוגה יתארך.
עיבוד שאילתות אסינכרוני מאפשר להריץ שאילתות על קבוצות נתונים גדולות מאוד ולאחזר את התוצאות במועד מאוחר יותר. כדאי לשקול להשתמש בשאילתה אופליין כדי לאתר את הזמן של השאילתות האינטראקטיביות. מצבים מסוימים שבהם עיבוד שאילתות אסינכרוני עשוי להיות חלופה טובה:
- ניתוח ויצירה של דוחות שמתפרסים על פני מרווחי זמן גדולים.
- ניתוח נתונים עם מגוון של מאפייני קיבוץ ומגבלות אחרות שמוסיפות מורכבות לשאילתה.
- ניהול שאילתות כאשר אתם מגלים שנפח הנתונים גדל באופן משמעותי עבור משתמשים או ארגונים מסוימים.
במסמך הזה מוסבר איך להפעיל שאילתות אסינכרוניות על ידי שימוש ב-API. תוכלו גם להשתמש בממשק המשתמש, כפי שמתואר במאמר הרצת דוח בהתאמה אישית.
השוואה בין רכיבי ה-API של דוחות לממשק המשתמש
במאמר יצירה וניהול של דוחות בהתאמה אישית מוסבר איך להשתמש בממשק המשתמש של Edge כדי ליצור ולהפיק דוחות בהתאמה אישית. אפשר להריץ את הדוחות האלה באופן סינכרוני או אסינכרוני.
רוב המושגים ליצירת דוחות מותאמים אישית בממשק המשתמש חלים על השימוש ב-API. כלומר, כשיוצרים דוחות בהתאמה אישית באמצעות ה-API, צריך לציין מדדים, מאפיינים ומסננים מובנים ב-Edge, וכל מדד מותאם אישית שיצרתם באמצעות המדיניות בנושא נתונים סטטיסטיים.
ההבדלים העיקריים בין הדוחות שנוצרו בממשק המשתמש לבין ממשק ה-API הם שדוחות שנוצרים באמצעות ממשק ה-API נכתבים בקובצי CSV או JSON (מופרדים בתו שורה חדשה) במקום בדוח ויזואלי שמוצג בממשק המשתמש.
מגבלות ברכב היברידי ב-Apigee
מודעה היברידית ב-Apigee אוכפת מגבלת גודל של 30MB על קבוצת נתוני התוצאות.
איך ליצור שאילתה של ניתוח נתונים אסינכרוני
כשאתם מריצים שאילתות ניתוח אסינכרוניות בשלושה שלבים:
שלב 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
, אפשר להשתמש ב-Get results API כדי לאחזר את התוצאות, כאשר מזהה השאילתה הוא שוב 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 אם דפוס המחרוזת תואם לדפוס שסופק.
הדוגמה שמשמאל מתאימה באופן הבא: - ערך כלשהו שיש לו את המילה 'קנייה' - ערך כלשהו המסתיים ב-'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) |
מגבלות וברירות מחדל
בהמשך מפורטת רשימת אילוצים וברירות מחדל לתכונה 'עיבוד אסינכרוני' של השאילתה.
המגבלה | ברירת המחדל | תיאור |
---|---|---|
מגבלת שיחות בשאילתה | הצגת התיאור | כדי לבצע דוח אסינכרוני, ניתן לבצע עד שבע קריאות בשעה לממשק ה-API לניהול של /queries. אם תחרגו ממכסת השיחות, ה-API יחזיר תגובת HTTP 429. |
מגבלת שאילתות פעילות | 10 | בארגון או סביבה יכולות להיות עד 10 שאילתות פעילות. |
סף זמן לביצוע שאילתה | 6 שעות | שאילתות שנמשכות יותר מ-6 שעות ייסגרו. |
טווח זמן של שאילתה | הצגת התיאור | הטווח המקסימלי לשאילתה הוא 365 ימים. |
מגבלת מאפיינים ומדדים | 25 | המספר המקסימלי של מאפיינים ומדדים שאפשר לציין במטען הייעודי (payload) של השאילתה. |
מידע על תוצאות השאילתה
התוצאה הבאה היא בפורמט 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 from 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: עסקאות לדקה
שאילתה לגבי המדד, לעסקאות של דקות לדקה.
שאילתה
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: העברת ביטוי בפרמטר המדדים
שאילתה עם ביטוי שמועבר כחלק מהפרמטר של המדדים. ניתן להשתמש רק בביטויים פשוטים עם אופרטור אחד.
שאילתה
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
גוף הבקשה מ-MetricsReression.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 |
חודש החיוב של הדוח, כגון יולי. | לא רלוונטי | כן |
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