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

אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.

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

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

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

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

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

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

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

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

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

למטה מוצג קובץ 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":[  
  {  
    "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

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

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

"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