מדריך תפעול

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

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

2. יצירת מפתח

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

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

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

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

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

שדה	ערך
שם	httpbin-product
שם לתצוגה	httpbin product
סביבה	your_environment צריך להגדיר את הערך הזה לסביבה שבה השתמשתם כשסיפקתם את Apigee Adapter ל-Envoy עם apigee-remote-service-cli.
גישה	Private
Quota	5 בקשות בכל דקה אפשר לעיין גם במאמר מידע על הגדרת מוצר API.

4. בקטע Apigee remote service targets (יעדים של שירותים מרוחקים ב-Apigee), לוחצים על Add an Apigee remote service target (הוספת יעד של שירות מרוחק ב-Apigee).
5. בתיבת הדו-שיח של יעד השירות המרוחק של Apigee, מוסיפים את הערכים הבאים:

   מאפיין	ערך	תיאור
   שם היעד	מזינים את השם של שירות היעד. לדוגמה: httpbin.org	נקודת הקצה של היעד שמוצגת על ידי שרת ה-proxy של Envoy.
   שרת proxy ל-API	remote-service	ה-proxy של remote-service שהוקצה ב-Apigee במהלך ההתקנה של Envoy Adapter.
   נתיב	מזינים /resource_path כדי להתאים נתיב ספציפי. לדוגמה: /httpbin.	נתיב הבקשה שצריך להתאים לנקודת הקצה של היעד. קריאות ל-proxy ל-API לנתיב הזה יתאימו למוצר ה-API הזה.

6. לוחצים על Save.

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

1. בתפריט הניווט הצדדי, בוחרים באפשרות פרסום > אפליקציות.
2. לוחצים על + App (הוספת אפליקציה).
3. ממלאים את הדף Developer App (אפליקציית מפתח) באופן הבא. לא לוחצים על Save (שמירה) עד שמקבלים הוראה לעשות זאת.

שם	httpbin-app
שם לתצוגה	httpbin app
מפתח	בוחרים את המפתח שיצרתם קודם או בוחרים מפתח אחר מהרשימה.

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

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

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

הגדרת מוצר API

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

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

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

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

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

API Resource Path

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

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

מכסה

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

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

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

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

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

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

בניגוד לזמן הריצה של Apigee, מכסת השימוש שמוזנת בהגדרת המוצר נאכפת באופן אוטומטי על ידי Apigee 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, לבדוק אותם ולבצע רוטציה שלהם. בסביבה היברידית של Apigee, אפשר להשתמש בפקודה הזו כדי ליצור סוד של Kubernetes שיכיל את אסימוני ה-JWT.

סקירה כללית

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

אחרי האימות, המסנן ext-authz של Envoy שולח את כותרות הבקשה ואת ה-JWT אל apigee-remote-service-envoy. הוא משווה בין טענות ה-JWT‏ api_product_list ו-scope לבין מוצרי ה-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"

הערה: הכותרת Content-type היא חובה.

שימוש בטוקן 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 גישה ל-URI ושהגדרתם את האישורים בצורה נכונה כשביצעתם את ההתקנה של ה-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:

• רישום ביומן של אפליקציות
• יומני גישה
• Stackdriver logging with GKE

שינוי השם של סוד המדיניות

סוד (Secret) של Kubernetes שנפרס באשכול מכיל פרטי כניסה שהמתאם צריך כדי לאמת את התקשורת עם שרת ה-proxy של השירות המרוחק. כדי להשתמש ב-Secret הזה צריך נקודת טעינה של נפח, שאפשר להגדיר. כברירת מחדל, נקודת הטעינה היא /policy-secret. כדי לשנות את נקודת הטעינה, פועלים לפי השלבים הבאים:

1. מריצים את הפקודה הבאה:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   לדוגמה:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. פותחים את $CLI_HOME/samples/apigee-envoy-adapter.yaml בעורך.
3. משנים את שם נקודת הטעינה לשם החדש:

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. שומרים את הקובץ ומחילים אותו על רשת השירותים:

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

שימוש בשרת 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 Remote Service for Envoy שולח נתונים סטטיסטיים של בקשות ל-Apigee לצורך עיבוד אנליטי. ‫Apigee מדווח על הבקשות האלה תחת שם מוצר ה-API המשויך.

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