מדריך פעולות

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

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

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

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

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

2. יצירת מפתח

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

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

3. יצירה של מוצר API

פועלים לפי הדוגמה הבאה ליצירת מוצר. עוד באותו הקשר מידע על הגדרת מוצר של API.

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

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

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

    הסבר על המכסות

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

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

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

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

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

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

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

הגדרת מוצר API

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

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

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

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

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

נתיב משאב של API

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

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

מכסה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

במקום להשתמש במפתח API, אפשר להשתמש באסימון JWT כדי לבצע קריאות מאומתות ל-proxy ל-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 עשויות להיראות כך:

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

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

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

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

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

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

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