راهنمای عملیات

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

نحوه دریافت کلید API

مثال زیر نحوه به دست آوردن یک کلید API را توضیح می دهد که می توانید از آن برای اعتبارسنجی تماس های API به یک سرویس هدف پروکسی شده از طریق Apigee Adapter for Envoy استفاده کنید.

1. وارد Apigee شوید

1. رابط کاربری Apigee را در مرورگر باز کنید.
2. هنگامی که وارد رابط کاربری شدید، همان سازمانی را انتخاب کنید که برای پیکربندی Apigee Adapter برای Envoy استفاده کردید.

2. یک توسعه دهنده ایجاد کنید

می‌توانید از یک توسعه‌دهنده موجود برای آزمایش استفاده کنید، یا یک توسعه‌دهنده جدید به شرح زیر ایجاد کنید:

1. در منوی ناوبری کناری ، Publish > Developers را انتخاب کنید.
2. روی + Developer کلیک کنید.
3. برای ایجاد یک توسعه دهنده جدید، کادر گفتگو را پر کنید. می توانید از هر نام یا ایمیل توسعه دهنده ای که می خواهید استفاده کنید.

3. یک محصول API ایجاد کنید

مثال ایجاد محصول ارائه شده در زیر را دنبال کنید. همچنین درباره پیکربندی محصول API رجوع کنید.

1. انتشار > محصولات API را در منوی ناوبری کناری انتخاب کنید.
2. روی + محصول API کلیک کنید.
3. صفحه جزئیات محصول را به صورت زیر پر کنید.

میدان	ارزش
نام	httpbin-product
نام نمایشی	httpbin product
محیط زیست	your_environment این را روی محیطی که هنگام تهیه Apigee Adapter برای Envoy استفاده کردید، تنظیم کنید.
دسترسی داشته باشید	Private
سهمیه	هر 1 دقیقه 5 درخواست همچنین به سهمیه مراجعه کنید.

4. در بخش اهداف سرویس از راه دور Apigee ، روی افزودن یک هدف سرویس راه دور Apigee کلیک کنید.
5. در گفتگوی هدف سرویس راه دور Apigee، مقادیر زیر را اضافه کنید:

   صفت	ارزش	توضیحات
   نام هدف	نام سرویس مورد نظر را وارد کنید. به عنوان مثال: httpbin.org	نقطه پایانی هدف که توسط پراکسی فرستاده روبرو می شود.
   مسیر	مسیر منبعی را برای مطابقت در سرویس وارد کنید. به عنوان مثال: /headers .	مسیر درخواست مطابقت در نقطه پایانی هدف. فراخوانی های پراکسی API به این مسیر با این محصول API مطابقت دارد.

6. روی ذخیره کلیک کنید.

4. یک برنامه توسعه دهنده ایجاد کنید

1. انتشار > برنامه‌ها را در منوی ناوبری کناری انتخاب کنید.
2. روی + برنامه کلیک کنید.
3. صفحه Developer App را به صورت زیر پر کنید. تا زمانی که دستور داده نشده است، ذخیره نکنید.

نام	httpbin-app
نام نمایشی	httpbin app
توسعه دهنده	توسعه‌دهنده‌ای را که قبلاً ایجاد کرده‌اید انتخاب کنید یا هر برنامه‌نویسی را که می‌خواهید از فهرست انتخاب کنید.

4. سپس محصول API را به برنامه اضافه کنید:
   1. در بخش Credentials، روی + Add product کلیک کنید و محصولی را که به تازگی پیکربندی کرده اید انتخاب کنید: httpbin-product .
   2. روی ایجاد کلیک کنید.
   3. در قسمت اعتبارنامه ها، روی نمایش در کنار کلید کلیک کنید.
   4. مقدار Consumer Key را کپی کنید. این مقدار کلید API است که از آن برای برقراری تماس های API با سرویس httpbin استفاده می کنید.

   درباره محصولات API

   محصولات API نقطه کنترل اولیه برای سرویس راه دور Apigee هستند. هنگامی که یک محصول API ایجاد می‌کنید و آن را به یک سرویس هدف متصل می‌کنید، خط‌مشی ایجاد می‌کنید که برای هر درخواستی که آداپتور Apigee خود را برای Envoy پیکربندی می‌کنید اعمال می‌شود.

   تعریف محصول API

   هنگامی که یک محصول API را در Apigee تعریف می کنید، می توانید تعدادی پارامتر را تنظیم کنید که برای ارزیابی درخواست ها استفاده می شود:

   • هدف
   • مسیر درخواست
   • سهمیه
   • دامنه های OAuth

   اهداف خدمات از راه دور

   اگر درخواست با اتصال هدف (مثلا httpbin.org ) و مسیر درخواست (مثلا /httpbin ) مطابقت داشته باشد، تعریف محصول API برای یک درخواست اعمال خواهد شد. لیستی از اهداف بالقوه به عنوان یک ویژگی در محصول API ذخیره می شود.

   به طور پیش‌فرض، سرویس از راه دور Apigee هدر :authority (host) ویژه Envoy را در برابر فهرست اهدافش بررسی می‌کند. با این حال می توان آن را برای استفاده از هدرهای دیگر پیکربندی کرد.

   مسیر منبع API

   مسیر وارد شده طبق قوانین زیر مطابقت دارد:

   • یک اسلش ( / ) به خودی خود با هر مسیری مطابقت دارد.
   • * در هر جایی معتبر است و در یک بخش (بین اسلش) مطابقت دارد.
   • ** در پایان معتبر است و هر چیزی را تا آخر خط مطابقت می دهد.

   سهمیه

   سهمیه تعداد پیام‌های درخواستی را مشخص می‌کند که یک برنامه مجاز است در طول یک ساعت، روز، هفته یا ماه به یک 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 یا توکن JWT به محصولات API مرتبط دسترسی داشته باشد.

   با استفاده از احراز هویت مبتنی بر JWT

   می توانید به جای استفاده از کلید API از یک نشانه JWT برای برقراری تماس های پروکسی API احراز هویت شده استفاده کنید. این بخش نحوه استفاده از دستور apigee-remote-service-cli token برای ایجاد، بازرسی و چرخش توکن های JWT توضیح می دهد.

   نمای کلی

   تأیید و احراز هویت JWT توسط Envoy با استفاده ازفیلتر تأیید اعتبار JWT انجام می شود.

   پس از احراز هویت، فیلتر Envoy ext-authz هدر درخواست و JWT را به apigee-remote-service-envoy ارسال می کند. این درخواست با api_product_list و scope ادعاهای JWT علیه محصولات Apigee Apigee مطابقت دارد تا آن را در برابر هدف درخواست مجاز کند.

   ایجاد توکن های Apigee JWT

   توکن های Apigee JWT را می توان با استفاده از CLI ایجاد کرد:

   $CLI_HOME/apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

   یا با استفاده از نقطه پایانی نشانه OAuth استاندارد. مثال کرل:

   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

   هنگامی که توکن را دریافت کردید، به سادگی آن را در هدر Authorization به Envoy ارسال می کنید. مثال:

   curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

   شکست توکن JWT

   رد فرستاده

   اگر Envoy توکن را رد کند، ممکن است پیامی مانند:

   Jwks remote fetch is failed

   اگر چنین است، مطمئن شوید که پیکربندی Envoy شما دارای یک URI معتبر در بخش remote_jwks است، که توسط Envoy قابل دسترسی است، و هنگام نصب پراکسی Apigee، گواهی ها را به درستی تنظیم کرده اید. باید بتوانید مستقیماً با یک تماس GET با URI تماس بگیرید و یک پاسخ JSON معتبر دریافت کنید.

   مثال:

   curl https://myorg-eval-test.apigee.net/remote-service/certs

   سایر پیام‌های فرستاده ممکن است به شرح زیر باشد:

   • "مخاطبان در 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	سطوح معتبر: اشکال زدایی، اطلاعات، هشدار، خطا.	سطح ثبت را تنظیم می کند. پیش فرض: اطلاعات
   -j، --json-log		خروجی گزارش را به عنوان رکوردهای JSON منتشر می کند.

   فرستاده ورود به سیستم را فراهم می کند. برای اطلاعات بیشتر، به پیوندهای مستندات فرستاده زیر مراجعه کنید:

   • ثبت برنامه
   • گزارش های دسترسی
   • ورود به سیستم Stackdriver با GKE

   استفاده از پروکسی شبکه

   یک پروکسی HTTP را می توان با استفاده از متغیرهای محیطی HTTP_PROXY و HTTPS_PROXY در محیط باینری apigee-remote-service-envoy درج کرد. هنگام استفاده از اینها، متغیر محیطی NO_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

   به یاد داشته باشید که پروکسی باید از طریق apigee-remote-service-envoy قابل دسترسی باشد.

   درباره متریک و تجزیه و تحلیل

   نقطه پایانی متریک پرومتئوس در آدرس :5001/metrics موجود است. شما می توانید این شماره پورت را پیکربندی کنید. فایل پیکربندی را ببینید.

   تجزیه و تحلیل فرستاده

   پیوندهای زیر اطلاعاتی در مورد به دست آوردن داده های تجزیه و تحلیل پروکسی Envoy ارائه می دهند:

   • رابط مدیریت
   • آمار
   • آمار خوشه ای

   تجزیه و تحلیل Istio

   پیوندهای زیر اطلاعاتی در مورد به دست آوردن داده های تجزیه و تحلیل پروکسی Envoy ارائه می دهند:

   • وظایف مشاهده پذیری
   • پیکربندی تله متری

   تجزیه و تحلیل Apigee

   Apigee Remote Service for Envoy آمار درخواست ها را برای پردازش تجزیه و تحلیل به Apigee می فرستد. Apigee این درخواست ها را تحت نام محصول API مرتبط گزارش می کند.

   برای اطلاعات در مورد تجزیه و تحلیل Apigee، به نمای کلی خدمات Analytics مراجعه کنید.

   پشتیبانی از محیط چند مستاجر

   اکنون می توانید آداپتور را برای سرویس دهی به چندین محیط در یک سازمان Apigee فعال کنید. این ویژگی به شما امکان می دهد از یک Apigee Adapter for 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 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