העלאת נתוני תנועה לממשק API ל-Apigee – גרסת בטא

Edge for Private Cloud גרסה 4.16.09

כל הלקוחות של Edge for Private Cloud נדרשים לשלוח ל-Apigee נתונים סטטיסטיים על תנועת הנתונים בשרתי proxy ל-API. אנחנו ממליצים ללקוחות להעלות את המידע הזה פעם ביום, למשל באמצעות יצירת משימת cron.

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

כדי לעזור בהעלאת הנתונים האלה, Apigee מספקת את גרסת הבטא של כלי שורת הפקודה apigee-analytics-collector. הכלי הזה שולח את דוח נפח הקריאות ל-API בחזרה ל-Apigee. בכל התקנה של Edge for Private Cloud אפשר להשתמש בכלי הזה כדי לאחזר נתוני תנועה ולדווח עליהם ל-Apigee.

מידע נוסף על תהליך ההעלאה של נתוני תנועה ל-Apigee זמין בשאלות הנפוצות.

בסרטון הקצר הזה אפשר לראות איך הכלי עובד.

התקנת apigee-analytics-collector

הכלי apigee-analytics-collector הוא מודול Node.js שמתקינים באמצעות npm.

דרישות התקנה

כדי להשתמש בכלי apigee-analytics-collector צריך:

  • ‫npm 2.x ואילך
  • ‫Node.js 4.x.

איפה מתקינים

הצומת שבו מתקינים את הכלי apigee-analytics-collector יכול להיות כל צומת שיכול לגשת ל-Edge management API ב-Edge Management Server. אפשר להתקין אותו ישירות בשרת הניהול, בצומת אחר של התקנת Edge או בצומת נפרד, כל עוד הצומת הזה יכול לשלוח בקשות API לשרת הניהול.

דרישות לגבי גישה לאינטרנט

מתקינים את הכלי apigee-analytics-collector במכונה עם גישה לאינטרנט חיצונית. לאחר מכן, הכלי apigee-analytics-collector יכול להעלות נתונים ישירות ל-Apigee.

אם אין צומת עם גישה ל-Edge management API ב-Edge Management Server ועם גישה חיצונית לאינטרנט, אתם יכולים להשתמש ב-Edge management API כדי לשמור את נתוני התנועה באופן מקומי. לאחר מכן, צריך להעביר את הנתונים למכונה עם גישה לאינטרנט כדי להעלות אותם ל-Apigee. בתרחיש הזה, אתם לא צריכים להשתמש בכלי apigee-analytics-collector. למידע נוסף, ראו העלאה ידנית של נתונים ל-Apigee בהמשך.

התקנה

משתמשים בפקודה הבאה כדי להתקין את הכלי apigee-analytics-collector:

> npm install apigee-analytics-collector -g

הפעלת apigee-analytics-collector

בקטע הזה מוסבר איך להריץ את הכלי apigee-analytics-collector.

המידע שנדרש כדי להריץ את apigee-analytics-collector

כדי להריץ את הפקודה apigee-analytics-collector ולהעביר נתונים ל-Apigee, צריך את הפרטים הבאים:

  • ‫apigee_mgmt_api_uri: כתובת ה-URL הבסיסית של Edge API בשרת הניהול. הפורמט של כתובת ה-URL הזו הוא בדרך כלל:
    http://ms_IP:8080/v1

    כאשר ms_IP היא כתובת ה-IP או שרת הניהול, ו-8080 היא היציאה שמשמשת את Edge API. אם יצרתם רשומת DNS ל-Edge API, כתובת ה-URL תהיה בפורמט הבא:
    http://ms_DNS/v1

    אם הפעלתם TLS ב-Edge Management API, כתובת ה-URL תהיה בפורמט הבא:
    https://ms_IP:8080/v1
    https://ms_DNS/v1
  • ‫apigee_mgmt_api_email: כתובת האימייל של חשבון עם גישה לממשקי ה-API של Edge /stats. בדרך כלל זו תהיה כתובת האימייל של מנהל המערכת של Edge, או כתובת האימייל של מנהל חשבון ארגוני של הארגונים בסביבת הייצור.
  • ‫apigee_mgmt_api_password: הסיסמה ב-Edge לחשבון שצוין ב-apigee_mgmt_api_email.
  • ‫apigee_analytics_client_id ו-apigee_analytics_secret: פרטי הכניסה שלכם להעלאת נתונים ל-Apigee. כדי לקבל את apigee_analytics_client_id ואת apigee_analytics_secret, צריך לשלוח כרטיס תמיכה לתמיכה של Apigee.

פקודות לדוגמה

הפקודה הבאה היא דוגמה לאחזור נתוני תנועה לכל הארגונים והסביבות בהתקנת Edge, ולהעלאת הנתונים האלה ל-Apigee:

> apigee-analytics-collector export traffic \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

שימו לב שהפקודה מכילה את כל המידע הנדרש, כמו apigee_analytics_client_id ו-apigee_analytics_secret.

התוצאות אמורות להופיע בפורמט הבא:

[
  {
    "org": "myOrg",
    "env": "prod",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  },
  {
    "org": "VALIDATE",
    "env": "test",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  }
]

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

  • ‎-i, --include_orgs <רשימה מופרדת בפסיקים של פריטים>‎
  • ‎-x, --exclude_orgs <רשימה מופרדת בפסיקים של פריטים>‎
  • ‎-n, --include_envs <רשימה מופרדת בפסיקים של פריטים>‎
  • ‎-e, --exclude_envs <רשימה מופרדת בפסיקים של פריטים>‎

לדוגמה, כדי לציין רק את הארגונים והסביבות של הייצור, משתמשים באפשרויות ‎-i (או ‎--include_orgs) ו-‎-n (או ‎--include_envs):

> apigee-analytics-collector export traffic -i myOrg -n prod \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

בדוגמה הזו, אתם אוספים נתונים רק מסביבת הייצור של myOrg.

כדי להציג את הנתונים במסך ולבדוק אותם לפני ששולחים אותם ל-Apigee, משתמשים באפשרות ‎-S:

> apigee-analytics-collector export traffic -i myOrg -n prod -S \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret 

האפשרות ‎-S משמיטה את העלאת הנתונים ל-Apigee. לאחר מכן, אפשר להריץ מחדש את הפקודה בלי האפשרות ‎-S כדי לשלוח את הנתונים ל-Apigee.

אחת מהסיבות להשתמש באפשרות ‎-S היא כדי להציג סוגים שונים של נתונים באופן מקומי. ב-Apigee צריך להעלות רק נתוני תנועה של API, אבל האפשרות ‎-D מאפשרת להציג נתונים על מוצרי API, מפתחים, אפליקציות או שרתי proxy ל-API. בדוגמה הבאה נעשה שימוש באפשרויות ‎-D ו-‎-S כדי להציג את נתוני המפתח באופן מקומי:

> apigee-analytics-collector export traffic -i myOrg -n prod -S -D devs \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret 

כדי לקבל פלט מפורט, צריך לכלול את האפשרות ‎-v, וכדי לראות את פקודות ה-curl שנוצרו על ידי apigee-analytics-collector, צריך לכלול את האפשרות ‎-R:

 > apigee-analytics-collector export traffic -i myOrg -n prod -S -R -v \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret 

בקטע הבא מופיעה רשימה מלאה של אפשרויות שורת הפקודה.

פרמטרים של פקודות

בטבלה הבאה מפורטות כל האפשרויות של הכלי apigee-analytics-collector:

Command

שימוש

‎-h, --help

נתוני שימוש בפלט

‎-D, --dimension <dimension>

מאפיין התנועה שרוצים לאסוף. מאפיינים תקינים: apiproducts, ‏ devs, ‏ apps, ‏ apiproxy (ברירת המחדל)

-d, --days <days>

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

אם מציינים את ‎-d, לא מציינים גם את ‎-s ואת ‎-z כדי להגדיר טווח זמן.

-m, --apigee_mgmt_api_uri <apigee_mgmt_api_uri>

כתובת ה-URL של ממשק ה-API לניהול של Edge.

-u, --apigee_mgmt_api_email <apigee_mgmt_api_email>

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

-p, --apigee_mgmt_api_password <apigee_mgmt_api_password>

הסיסמה שמשויכת לחשבון האימייל של Edge management API שצוין באמצעות ‎-u.

-i, --include_orgs <items>

רשימה מופרדת בפסיקים של ארגונים שצריך לכלול בפלט.

-x, --exclude_orgs <items>

רשימה מופרדת בפסיקים של ארגונים שרוצים להחריג מהפלט.

-n, --include_envs <items>

רשימה מופרדת בפסיקים של סביבות שרוצים לכלול בפלט.

-e, --exclude_envs <items>

רשימה מופרדת בפסיקים של סביבות שרוצים לכלול בפלט.

-o, --output <path>

הנתיב ושם הקובץ לשמירת הפלט.

-s, --time_range_start <time_range_start>

טווח תאריכים להתחלת שליחת שאילתות לגבי נתוני תנועה, בפורמט: "03/01/2016 00:00".

אם מציינים את הפרמטר ‎-d, לא צריך לציין גם את הפרמטרים ‎-s ו-‎-z כדי להגדיר טווח תאריכים.

-z, --time_range_end <time_range_end>

סוף טווח תאריכים לשליחת שאילתות לגבי נתוני תנועה, בפורמט: "04/01/2016 24:00".

אם מציינים את הפרמטר ‎-d, לא צריך לציין גם את הפרמטרים ‎-s ו-‎-z כדי להגדיר טווח תאריכים.

-t, --time_unit <time_unit>

יחידת הזמן של נתוני התנועה. שבוע ברירת המחדל. יחידות ברירת המחדל לפי שעה. יחידות זמן חוקיות: שנייה, דקה, שעה, יום, שבוע.

‎-S, --standard_output

כתיבת פלט למסוף (stdout), במקום להעלות אותו ל-Apigee.

-c, --apigee_analytics_client_id <apigee_analytics_client_id>

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

-r, --apigee_analytics_secret <apigee_analytics_secret>

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

‎-R, --include_curl_commands

כדי לנפות באגים, צריך לכלול בפלט את פקודות ה-cURL שנוצרו.

-v, --verbose

הצגת פלט מפורט.

העלאה ידנית של נתונים ל-Apigee

מומלץ להתקין את הכלי apigee-analytics-collector במכונה עם גישה לאינטרנט החיצוני. לאחר מכן, הכלי apigee-analytics-collector יכול להעלות נתונים ישירות ל-Apigee.

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

כדי לאסוף נתוני תנועה של ארגון וסביבה ספציפיים במרווח זמן מסוים, משתמשים בפקודת ה-cURL הבאה:

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://<ms_IP>:8080/v1/organizations/{org_name}/environments/{env_name}/stats/?select=sum(message_count)&timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM"

הפקודה הזו משתמשת ב-API של Edge Get API message count. בפקודה הזו:

  • ‫apigee_mgmt_api_email:apigee_mgmt_api_password מציין את כתובת האימייל של חשבון עם גישה לממשקי ה-API של Edge /stats.
  • ‫<ms_IP> היא כתובת ה-IP או שם ה-DNS של שרת הניהול של Edge.
  • ‫{org_name} ו-{env_name} מציינים את הארגון והסביבה.
  • ‫MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM מציין את טווח התאריכים של הנתונים הסטטיסטיים שרוצים לאסוף. שימו לב שבפקודת ה-cURL נעשה שימוש בקוד ההקסדצימלי %20 במקום הרווחים בטווח הזמן.

לדוגמה, כדי לאסוף נתונים סטטיסטיים לתקופה של 24 שעות, משתמשים בפקודה הבאה:

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://192.168.56.103:8080/v1/organizations/myOrg/environments/prod/stats/?select=sum(message_count)&timeRange=08/29/2016%2000:00~08/30/2016%2000:00"

אתם אמורים לראות תגובה בפורמט הבא:

{
  "environments" : [ {
    "metrics" : [ {
      "name" : "sum(message_count)",
      "values" : [ "42.0" ]
    } ],
    "name" : "prod"
  } ],
  "metaData" : {
    "errors" : [ ],
    "notices" : [ "query served by:53dab80c-e811-4ba6-a3e7-b96f53433baa", "source pg:6b7bab33-e732-405c-a5dd-4782647ce096", "Table used: myorg.prod.agg_api" ]
  }
}

כדי להעלות את הנתונים האלה ל-Apigee ממכונה עם גישה לאינטרנט, משתמשים בפקודת ה-cURL הבאה:

curl -X POST -H 'Content-Type:application/json' \
-u apigee_analytics_client_id:apigee_analytics_secret \
https://nucleus-api-prod.apigee.com/v1/apigee-analytics-cli-api/traffic/orgs/{org_name}/apis -d '{"environments"...}'

כאשר:

  • ‫apigee_analytics_client_id:apigee_analytics_secret: פרטי הכניסה להעלאת נתונים ל-Apigee, שקיבלתם מהתמיכה של Apigee.
  • ‫{org_name} מציין את הארגון.
  • ‫{"environments"...} מכיל את התוצאות של פקודת ה-cURL שבה השתמשתם כדי לאסוף את הנתונים הסטטיסטיים שלמעלה.