מדריך פעולות

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

איך מקבלים מפתח API

בדוגמה הבאה מוסבר איך לקבל מפתח API שאפשר להשתמש בו כדי לאמת קריאות API לשירות יעד שמוגדר לו שרת proxy דרך Apigee Adapter for Envoy.

1. התחברות ל-Apigee

  1. פותחים את ממשק המשתמש של Apigee בדפדפן.
  2. בממשק המשתמש, בוחרים את אותו ארגון שבו השתמשתם כדי להגדיר את Apigee Adapter ל-Envoy.

2. יצירת מפתח

אפשר להשתמש בחשבון פיתוח קיים לצורך בדיקה, או ליצור חשבון חדש באופן הבא:

  1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > מפתחים.
  2. לוחצים על + מפתח.
  3. ממלאים את תיבת הדו-שיח כדי ליצור מפתח חדש. אפשר להשתמש בכל שם או כתובת אימייל של מפתח שתרצו.

3. יצירת מוצר API

פועלים לפי הדוגמה ליצירת מוצר שמפורטת בהמשך. אפשר לעיין גם במאמר מידע על הגדרת המוצר של ה-API.

  1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > מוצרי API.
  2. לוחצים על + API Product.
  3. ממלאים את דף פרטי המוצר באופן הבא. אין ללחוץ על שמירה עד שמקבלים הוראה לעשות זאת.
    4. שדה ערך
    שם httpbin-product
    השם המוצג httpbin product
    סביבה your_environment

    מגדירים את הסביבה שבה השתמשתם כשהקציתם את Apigee Adapter for Envoy באמצעות apigee-remote-service-cli.

    גישה Private
    מכסה 5 בקשות בכל דקה

    אפשר לעיין גם במאמר הסבר על מכסות.

  4. בקטע יעדי שירות מרוחקים של Apigee, לוחצים על הוספת יעד שירות מרוחק של Apigee.
  5. בתיבת הדו-שיח של היעד של שירות מרוחק ב-Apigee, מוסיפים את הערכים הבאים:
    מאפיין ערך תיאור
    שם היעד מזינים את השם של שירות היעד. לדוגמה: httpbin.org נקודת הקצה (endpoint) של היעד שמוגנת על ידי שרת ה-proxy של Envoy.
    נתיב צריך להזין /resource_path כדי להתאים לנתיב ספציפי. לדוגמה: /httpbin. נתיב הבקשה שצריך להתאים לנקודת הקצה היעד. קריאות API proxy לנתיב הזה יתאימו למוצר ה-API הזה.
  6. לוחצים על שמירה.

4. יצירת אפליקציה למפתחים

  1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > אפליקציות.
  2. לוחצים על + אפליקציה.
  3. ממלאים את דף האפליקציה למפתחים באופן הבא. אין לשמור עד שמקבלים הוראה לעשות זאת.
    4. שם httpbin-app
    השם המוצג httpbin app
    מפתח/ת בוחרים את המפתח שיצרתם קודם, או בוחרים מפתח אחר מתוך הרשימה.
  4. בשלב הבא, מוסיפים שני מוצרים לאפליקציה:
    1. בקטע Credentials (פרטי כניסה), לוחצים על + Add product (הוספת מוצר) ובוחרים את המוצר שהגדרתם זה עתה: httpbin-product.
    2. לוחצים על יצירה.
    3. בקטע Credentials (פרטי כניסה), לוחצים על Show (הצגה) לצד Key (מפתח).
    4. מעתיקים את הערך של מפתח הצרכן. הערך הזה הוא מפתח ה-API שבו תשתמשו כדי לבצע קריאות API לשירות httpbin.

    מידע על מוצרי API

    מוצרי API הם נקודת הבקרה הראשית של השירות מרחוק של Apigee. כשיוצרים מוצר API ומקשרים אותו לשירות יעד, יוצרים מדיניות שתחול על כל הבקשות שתגדירו לטיפול על ידי Apigee Adapter for Envoy.

    הגדרת מוצר API

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

    • יעד
    • נתיב הבקשה
    • מכסה
    • היקפי ההרשאות של OAuth

    יעדים של שירותים מרוחקים

    ההגדרה של מוצרי ה-API תחול על בקשה אם היא תואמת גם לקישור היעד (לדוגמה, httpbin.org) וגם לנתיב הבקשה (לדוגמה, /httpbin). רשימת היעדים הפוטנציאליים מאוחסנת כמאפיין במוצר ה-API.

    כברירת מחדל, השירות המרוחק של Apigee בודק את הכותרת המיוחדת :authority (host) של Envoy מול רשימת היעדים שלו. עם זאת, אפשר להגדיר אותו כך שישתמש בכותרות אחרות.

    נתיב המשאב של ה-API

    הנתיב שהוזן תואם לפי הכללים הבאים:

    • קו נטוי יחיד (/) תואם לכל נתיב.
    • הערך * תקף בכל מקום והוא מתאים לפלח (בין קווים נטויים).
    • הפונקציה ** תקפה בסוף ומבצעת התאמה של כל דבר עד לסוף השורה.

    מכסה

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

    תרחישים לדוגמה לשימוש במכסות

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

    המכסה מוגדרת במוצר API

    אפשר להגדיר את הפרמטרים של המכסות ב'מוצרי API'. לדוגמה, כשיוצרים מוצר API, אפשר להגדיר את מגבלת המכסה המותרת, יחידת הזמן והמרווח.

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

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

    איפה נשמרות המכסות

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

    היקפי הרשאות OAuth

    אם אתם משתמשים באסימוני JWT, תוכלו להגביל את האסימונים לקבוצות משנה של היקפי ההרשאות המותרים של OAuth. ההיקפים שהוקצו לאסימון ה-JWT שהונפקה ייבדקו בהשוואה להיקפים של מוצר ה-API.

    מידע על אפליקציות למפתחים

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

    שימוש באימות מבוסס-JWT

    אפשר להשתמש באסימון JWT כדי לבצע קריאות proxy מאומתות ל-API במקום להשתמש במפתח API. בקטע הזה מוסבר איך להשתמש בפקודה apigee-remote-service-cli token כדי ליצור, לבדוק ולבצע רוטציה של אסימוני JWT.

    סקירה כללית

    האימות והאימות של JWT מטופל על ידי Envoy באמצעות מסנן האימות של JWT.

    אחרי האימות, המסנן ext-authz של Envoy שולח את כותרות הבקשה ואת ה-JWT אל apigee-remote-service-envoy. הוא מתאים את ההצהרות api_product_list ו-scope של ה-JWT למוצרים של Apigee API כדי לאשר אותו מול היעד של הבקשה.

    יצירת אסימוני JWT ב-Apigee

    אפשר ליצור אסימוני JWT של Apigee באמצעות ה-CLI:

    apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

    לחלופין, אפשר להשתמש בנקודת הקצה הרגילה של אסימון OAuth. דוגמה ל-Curl:

    curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

    שימוש באסימון JWT

    אחרי שמקבלים את האסימון, פשוט מעבירים אותו ל-Envoy בכותרת Authorization. דוגמה:

    curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

    כשל באסימון JWT

    דחייה של Envoy

    אם Envoy דוחה את האסימון, עשויה להופיע הודעה כמו:

    Jwks remote fetch is failed

    אם כן, צריך לוודא שהגדרת Envoy מכילה URI תקין בקטע remote_jwks, ש-Envoy יכול לגשת אליו ושהגדרתם את האישורים בצורה נכונה כשהתקנתם את שרת ה-proxy של Apigee. אמורה להיות אפשרות להפעיל את ה-URI ישירות באמצעות קריאת GET ולקבל תגובת JSON תקינה.

    דוגמה:

    curl https://myorg-eval-test.apigee.net/remote-service/certs

    הודעות אחרות מ-Envoy עשויות להיראות כך:

    • "Audiences in Jwt are not allowed"
    • "מנפיק ה-Jwt לא מוגדר"

    הפרטים האלה נובעים מדרישות בהגדרות האישיות של Envoy שצריך לשנות.

    בדיקת טוקן

    אפשר להשתמש ב-CLI כדי לבדוק את האסימון. דוגמה

    apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

    או 

    apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

    ניפוי באגים

    ראו מפתח API תקין נכשל.

    רישום ביומן

    אפשר לשנות את רמת הרישום ביומן בשירות $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. כל הרישום ביומן נשלח אל stderr.

    רכיב חובה תיאור
    -l, --log-level רמות חוקיות: debug, ‏ info, ‏ warn, ‏ error. התאמת רמת הרישום ביומן. ברירת מחדל: info
    -j, --json-log הפונקציה פולטת את פלט היומן כרשומות JSON.

    Envoy מספק רישום ביומן. מידע נוסף זמין בקישור הבא למסמכי העזרה של Envoy:

    שימוש בשרת proxy ברשת

    אפשר להכניס שרת proxy של HTTP באמצעות משתני הסביבה HTTP_PROXY ו-HTTPS_PROXY בסביבה הבינארית apigee-remote-service-envoy. כשמשתמשים בהם, אפשר להשתמש גם במשתנה הסביבה NO_PROXY כדי להחריג מארחים ספציפיים שלא יישלחו דרך שרת ה-proxy.

    HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

    חשוב לזכור שצריך להיות אפשרות לגשת לשרת ה-proxy מ-apigee-remote-service-envoy.

    מידע על מדדים וניתוח נתונים

    נקודת קצה של מדדי Prometheus זמינה ב-:5001/metrics. אפשר להגדיר את מספר היציאה. ראו קובץ תצורה.

    ניתוח נתונים של Envoy

    בקישורים הבאים תוכלו לקרוא מידע על קבלת נתוני ניתוח נתונים של שרת proxy של Envoy:

    ניתוח נתונים של Istio

    בקישורים הבאים תוכלו לקרוא מידע נוסף על קבלת נתוני ניתוח נתונים של שרת proxy של Envoy:

    ניתוח נתונים של Apigee

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

    למידע נוסף על ניתוח נתונים של Apigee, קראו את המאמר סקירה כללית של שירותי Analytics.