כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
איך מקבלים מפתח API
בדוגמה הבאה מוסבר איך מקבלים מפתח API שבו אפשר להשתמש כדי לאמת קריאות ל-API לשירות יעד שעובר דרך שרת proxy באמצעות Apigee Adapter ל-Envoy.
1. התחברות ל-Apigee
- פותחים את ממשק המשתמש של Apigee בדפדפן.
- לאחר הכניסה לממשק המשתמש, בוחרים את הארגון שבו השתמשתם כדי להגדיר את Apigee Adapter ל-Envoy.
2. יצירת מפתח
ניתן להשתמש במפתח קיים לבדיקה, או ליצור מפתח חדש באופן הבא:
- בתפריט הניווט שבצד, בוחרים פרסום > מפתחים.
- לוחצים על + מפתח.
- מלאו את תיבת הדו-שיח כדי ליצור מפתח חדש. אפשר להשתמש בכל שם או כתובת אימייל של מפתח שרוצים.
3. יצירת מוצר API
פועלים לפי הדוגמה ליצירת מוצר שמופיעה בהמשך. למידע נוסף, ראו מידע על הגדרת המוצר של API.
- בתפריט הניווט שבצד, בוחרים פרסום > מוצרי API.
- לוחצים על + מוצר API.
- ממלאים את דף פרטי המוצר באופן הבא.
- בקטע יעדי שירות מרוחק של Apigee, לוחצים על הוספת יעד שירות מרוחק של Apigee.
- בתיבת הדו-שיח 'יעד שירות מרוחק של Apigee', מוסיפים את הערכים הבאים:
מאפיין Value התיאור שם היעד מזינים את השם של שירות היעד. לדוגמה: httpbin.org
נקודת הקצה (endpoint) של היעד שבחזיתה שרת ה-proxy של Envoy. נתיב מזינים את נתיב המשאב בשירות להתאמה. לדוגמה: /headers
.נתיב הבקשה להתאמה בנקודת הקצה של היעד. קריאות לשרת proxy של API לנתיב הזה יתאימו למוצר ה-API הזה. - לוחצים על שמירה.
שדה | Value |
---|---|
שם | httpbin-product
|
שם לתצוגה | httpbin product
|
סביבה | your_environment
צריך להגדיר את ההגדרה הזו לסביבה שבה השתמשת כשהקצית את Apigee Adapter ל-Envoy. |
גישה | Private
|
מכסה | 5 בקשות כל דקה
מידע נוסף זמין גם בקטע מכסה. |
4. יצירת אפליקציה למפתחים
- בתפריט הניווט שבצד, בוחרים באפשרות פרסום > אפליקציות.
- לוחצים על + אפליקציה.
- ממלאים את הדף של האפליקציה למפתחים באופן הבא. אין לשמור עד לקבלת הנחייה לעשות זאת.
- בשלב הבא, מוסיפים את מוצר ה-API לאפליקציה:
- בקטע Credentials, לוחצים על + Add product (הוספת מוצר) ובוחרים את המוצר שהגדרתם כרגע: httpbin-product.
- לוחצים על יצירה.
- בקטע Credentials (פרטי כניסה), לוחצים על Show (הצגה) ליד Key (מפתח).
- מעתיקים את הערך של מפתח הצרכן. הערך הזה הוא מפתח ה-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:
$CLI_HOME/apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET
לחלופין, באמצעות נקודת הקצה הרגילה של אסימון OAuth. דוגמה ל-Curl:
curl https://org-env.apigee.net/remote-token/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 כדי לבדוק את האסימון שלכם. דוגמה
$CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect -f path/to/file
או
$CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN
ניפוי באגים
לפרטים, קראו את המאמר מפתח API תקין נכשל.רישום ביומן
אפשר לשנות את רמת הרישום ביומן בשירות $REMOTE_SERVICE_Home/apigee-remote-service-envoy. כל הרישום ביומן נשלח אל stdout ו-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.
תמיכה בסביבה מרובת דיירים (multi-tenant)
עכשיו אפשר להפעיל את המתאם כדי לתת שירות לסביבות מרובות בארגון Apigee. התכונה הזו מאפשרת להשתמש במתאם Apigee אחד ל-Envoy שמשויך לארגון Apigee אחד, כדי לספק שירות בסביבות מרובות. לפני השינוי הזה, מתאם אחד תמיד היה מקושר לסביבת Apigee אחת.
כדי להגדיר תמיכה בכמה סביבות, צריך לשנות את הערך של
tenant:env_name
ל-*
בקובץconfig.yaml
. לדוגמה:- פותחים את הקובץ
config.yaml
בעורך. - יש לשנות את הערך של
tenant.env_name
ל-*
. לדוגמה:apiVersion: v1 kind: ConfigMap metadata: name: apigee-remote-service-envoy namespace: apigee data: config.yaml: | tenant: remote_service_api: https://myorg-myenv.apigee.net/remote-service org_name: apigee-docs-hybrid-a env_name: * allow_unverified_ssl_cert: true analytics: collection_interval: 10s auth: jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token
- שומרים את הקובץ.
- מחילים את הקובץ:
kubectl apply -f $CLI_HOME/config.yaml
כשמגדירים מצב ריבוי סביבות, צריך גם להגדיר ל-Envoy לשלוח ערך סביבה מתאים למתאם על ידי הוספת המטא-נתונים הבאים בקטע
virtual_hosts:routes
של הקובץenvoy-config.yaml
. לדוגמה:- יוצרים את הקובץ
envoy-config.yaml
באמצעות ה-CLI. לדוגמה:$CLI_HOME/apigee-remote-service-cli samples create \ -t envoy-1.16 -c ./config.yaml --out myconfigs
- פותחים את הקובץ שנוצר (השם הוא
envoy-config.yaml
). - מוסיפים את המטא-נתונים הבאים בקטע
virtual_host
או בקטעroutes
של הקובץ:typed_per_filter_config: envoy.filters.http.ext_authz: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute check_settings: context_extensions: apigee_environment: test
הדוגמה הבאה ממחישה הגדרה של
virtual_host
עם כמה מסלולים, שבהם כל מסלול שולח תנועה לסביבה ספציפית:filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http route_config: virtual_hosts: - name: default domains: "*" routes: - match: { prefix: /test } route: cluster: httpbin typed_per_filter_config: envoy.filters.http.ext_authz: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute check_settings: context_extensions: apigee_environment: test - match: { prefix: /prod } route: cluster: httpbin typed_per_filter_config: envoy.filters.http.ext_authz: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute check_settings: context_extensions: apigee_environment: prod
- חוזרים על השלב האחרון כדי להוסיף עוד סביבות לפי הצורך.
- שומרים את הקובץ ומחילים אותו.
הגדרת mTLS בין המתאם לבין זמן הריצה של Apigee
כדי להשתמש ב-mTLS בין המתאם לבין זמן הריצה של Apigee, אפשר לספק אישורי TLS בצד הלקוח בקטע
tenant
בקובץconfig.yaml
של המתאם. השינוי הזה יחול על כל הפלטפורמות הנתמכות של Apigee. היא גם מפעילה mTLS לניתוח נתונים בפלטפורמת Apigee Edge לענן פרטי. לדוגמה:tenant: tls: ca_file: path/ca.pem cert_file: path/cert.pem key_file: path/key.pem allow_unverified_ssl_cert: false
שם | httpbin-app
|
שם לתצוגה | httpbin app
|
מפתח | בוחרים את המפתח שיצרתם בעבר או בוחרים מפתח כלשהו מהרשימה. |