מדריך פעולות

כרגע מוצג התיעוד של 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. שדה Value
    שם httpbin-product
    שם לתצוגה httpbin product
    סביבה your_environment

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

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

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

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

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

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

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

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

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

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

הגדרת מוצר API

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

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

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

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

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

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

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

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

מכסה

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

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

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

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

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

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

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

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

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

היקפי OAuth

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

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

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

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

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

סקירה כללית

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

לאחר האימות, מסנן 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 Analytics

בקישורים הבאים מוסבר איך לקבל נתונים של ניתוח נתוני שרת proxy של Envoy:

Istio Analytics

בקישורים הבאים מוסבר איך לקבל נתונים של ניתוח נתוני שרת proxy של Envoy:

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

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

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