מדריך פעולות

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

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

4. בקטע יעדי שירות מרוחק של Apigee, לוחצים על הוספת יעד שירות מרוחק של Apigee.
5. בתיבת הדו-שיח 'יעד שירות מרוחק של Apigee', מוסיפים את הערכים הבאים:

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

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

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

1. בתפריט הניווט שבצד, בוחרים באפשרות פרסום > אפליקציות.
2. לוחצים על + אפליקציה.
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 ל-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:

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

   שימוש בשרת 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. לדוגמה:

   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

   כדי להשתמש ב-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