מדריך תפעול

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

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

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

2. יצירת מפתח

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

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

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

פועלים לפי הדוגמה ליצירת מוצר שמופיעה בהמשך. מידע נוסף זמין במאמר בנושא הגדרת מוצר API.

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

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

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

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

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

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

  6. לוחצים על שמירה.

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

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

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

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

איפה המכסות מתעדכנות

המיכסות נשמרות ונבדקות באופן מקומי על ידי תהליך Remote Service, והן נשמרות באופן אסינכרוני ב-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 לבין מוצרי ה-API של Apigee כדי לאשר את הגישה ליעד של הבקשה.

יצירת טוקנים מסוג 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:

  • "אסור להשתמש בקהלים ב-JWT"
  • ‫"Jwt issuer is not configured" (לא הוגדר מנפיק 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 בסביבה של קובץ ה-binary 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

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

ניתוח נתונים ב-Istio

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

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

‫Apigee Remote Service for Envoy שולח נתוני בקשות ל-Apigee לעיבוד לצורך ניתוח. מערכת Apigee מדווחת על הבקשות האלה תחת שם מוצר ה-API המשויך.

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