מדריך תפעול

אתם צופים במסמכי התיעוד של 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. ממלאים את הדף 'פרטי מוצר' באופן הבא.

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

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

   מאפיין	ערך	תיאור
   שם היעד	מזינים את השם של שירות היעד. לדוגמה: httpbin.org	נקודת הקצה לטירגוט שמוצגת על ידי שרת ה-proxy של Envoy.
   נתיב	מזינים נתיב למשאב בשירות להתאמה. לדוגמה: /headers.	נתיב הבקשה להתאמה בנקודת הקצה של היעד. קריאות ל-proxy ל-API לנתיב הזה יתאימו למוצר ה-API הזה.

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

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

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

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

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

   $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 issuer is not configured" (לא הוגדר מנפיק 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	הדרגות האפשריות: debug, ‏ info, ‏ warn, ‏ error.	משנה את רמת הרישום ביומן. ברירת מחדל: info
   ‫‎-j, ‏--json-log		פלט היומן מופק כרשומות JSON.

   ‫Envoy מספק רישום ביומן. מידע נוסף זמין במאמרי העזרה הבאים בנושא Envoy:

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

   שימוש בשרת 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 זמין במאמר סקירה כללית של שירותי ניתוח נתונים.

   תמיכה בסביבת Multi-tenant

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

   כדי להגדיר תמיכה במספר סביבות, משנים את הערך של tenant:env_name ל-* בקובץ config.yaml. לדוגמה:

   1. פותחים את הקובץ config.yaml בכלי עריכה.
   2. משנים את הערך של 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

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

      kubectl apply -f $CLI_HOME/config.yaml

   כשמגדירים מצב ריבוי סביבות, צריך גם להגדיר את Envoy כך שישלח ערך סביבה מתאים למתאם. לשם כך, מוסיפים את המטא-נתונים הבאים לקטע virtual_hosts:routes בקובץ envoy-config.yaml. לדוגמה:

   1. יוצרים את קובץ envoy-config.yaml באמצעות ה-CLI. לדוגמה:

      $CLI_HOME/apigee-remote-service-cli samples create \
        -t envoy-1.16 -c ./config.yaml --out myconfigs

   2. פותחים את הקובץ שנוצר (השם שלו הוא envoy-config.yaml).
   3. מוסיפים את המטא-נתונים הבאים בקטע 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

   4. חוזרים על השלב האחרון כדי להוסיף עוד סביבות לפי הצורך.
   5. שומרים את הקובץ ומחילים אותו.

   הגדרת mTLS בין המתאם לבין זמן הריצה של Apigee

   אתם יכולים לספק אישורי TLS בצד הלקוח בקטע tenant בקובץ config.yaml של המתאם כדי להשתמש ב-mTLS בין המתאם לבין זמן הריצה של Apigee. השינוי הזה חל על כל פלטפורמות Apigee הנתמכות. הוא גם מאפשר mTLS לניתוח נתונים בפלטפורמת Apigee Edge for Private Cloud. לדוגמה:

   tenant:
     tls:
       ca_file: path/ca.pem
       cert_file: path/cert.pem
       key_file: path/key.pem
       allow_unverified_ssl_cert: false