מדריך פעולות

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

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

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

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

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

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

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

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

4. בשלב הבא, מוסיפים את מוצר ה-API לאפליקציה:
   1. בקטע 'פרטי כניסה', לוחצים על + הוספת מוצר ובוחרים את המוצר שרוצים להוסיף. הוגדר עכשיו: httpbin-product.
   2. לוחצים על יצירה.
   3. בקטע 'פרטי כניסה', לוחצים על הצגה לצד המפתח.
   4. מעתיקים את הערך של מפתח הצרכן. הערך הזה הוא מפתח ה-API שישמשו אותך כדי לבצע קריאות ל-API לשירות httpbin.

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

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

   הגדרת מוצר API

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

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

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

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

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

   נתיב משאב של API

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

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

   מכסה

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

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

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

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

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

   

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

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

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

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

   היקפי הרשאות OAuth

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

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

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

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

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

   סקירה כללית

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

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

   בקישורים הבאים מפורט מידע על קבלת ניתוח נתונים של Envoy לשרת proxy נתונים:

   • ממשק ניהול
   • נתונים סטטיסטיים
   • נתונים סטטיסטיים של אשכול

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

   בקישורים הבאים מפורט מידע על קבלת ניתוח נתונים של Envoy לשרת proxy נתונים:

   • משימות של ניראות
   • הגדרת הטלמטריה

   ניתוח נתונים של 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

   אפשר לספק אישורי TLS בצד הלקוח בקטע tenant של הקובץ config.yaml של המתאם, שמאפשר להשתמש ב-mTLS בין המתאם לבין זמן הריצה של Apigee. הזה השינוי יחול על כל פלטפורמות 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