שימוש בממשק API אסינכרוני של דוחות מותאמים אישית

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

עם זאת, הזמן הקצוב לתפוגה של בקשות לניתוח נתונים עשוי להימשך זמן רב מדי. אם בקשת שאילתה צריכה לעבד כמות גדולה של נתונים (לדוגמה, 100GB), יכול להיות שהיא תיכשל בגלל שתם הזמן הקצוב לתפוגה.

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

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

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

השוואה בין ה-API לדוחות לממשק המשתמש

במאמר יצירה וניהול של דוחות מותאמים אישית מוסבר איך להשתמש בממשק המשתמש של Edge כדי ליצור ולהפעיל דוחות בהתאמה אישית. אפשר להריץ את הדוחות האלה באופן סינכרוני או אסינכרוני.

רוב המושגים ליצירת דוחות בהתאמה אישית באמצעות ממשק המשתמש רלוונטיים לשימוש ב-API. כלומר, כשיוצרים דוחות מותאמים אישית באמצעות ה-API, מציינים metrics, מאפיינים ומסננים שמובְנים ב-Edge, וכל מדד מותאם אישית שנוצר באמצעות המדיניותStatStatsCollector.

ההבדלים העיקריים בין הדוחות שנוצרים בממשק המשתמש לבין ה-API הם שדוחות שנוצרים באמצעות ה-API נכתבים בקובצי CSV או בקובצי JSON (בשורה חדשה) במקום בדוח חזותי שמוצג בממשק המשתמש.

מגבלות באפליקציה היברידית של Apigee

הכלי המשולב של Apigee אוכף מגבלת גודל של 30MB על קבוצת הנתונים של התוצאות.

איך ליצור שאילתת ניתוח אסינכרונית

יש שלושה שלבים לביצוע שאילתות ניתוח אסינכרוניות:

1. שולחים את השאילתה.

2. מקבלים את סטטוס השאילתה.

3. מאחזרים את תוצאות השאילתה.

שלב 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, עליך לציין את metrics, המאפיינים והמסננים שמגדירים את הדוח.

לפניכם קובץ 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 כלול בתשובה. בנוסף לסטטוס 201 של HTTP, המשמעות של 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, עליכם ללחוץ על הלחצן 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":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

תחביר של ביטוי סינון

בקטע העזר הזה מתוארים האסימונים שבהם אפשר להשתמש כדי ליצור ביטויי סינון בגוף הבקשה. לדוגמה, הביטוי הבא משתמש באסימון "ge" (גדול מ- או שווה ל-):

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

מגבלות וברירות מחדל

בהמשך מופיעה רשימה של אילוצים וברירות מחדל של תכונת עיבוד השאילתות האסינכרוניות.

מידע על תוצאות השאילתה

התוצאה הבאה היא תוצאה בפורמט 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: העברת ביטוי בפרמטר המדדים

שאילתה עם ביטוי שמועבר כחלק מפרמטר המדדים. ניתן להשתמש רק בביטויים פשוטים של אופרטור אחד.

שאילתה

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 זהים לשלבים 2 ו-3 של שאילתות ניתוח אסינכרוניות. למידע נוסף, ראה כיצד ליצור שאילתת ניתוח אסינכרונית.

כדי לשלוח שאילתה לדוח מונטיזציה אסינכרוני, יש לשלוח בקשת POST אל /mint/organizations/org_id/async-reports.

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

/mint/organizations/org_id/async-reports?environment=prod

בגוף הבקשה, מציינים את קריטריוני החיפוש הבאים.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

לדוגמה, הבקשה הבאה תיצור דוח מונטיזציה אסינכרוני לחודש יוני 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