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

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

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

مثال زیر توضیح می‌دهد که چگونه کلید میانای برنامه‌سازی کاربردی را دریافت کنید که می‌توانید از آن برای اعتبارسنجی فراخوانی‌های میانای برنامه‌سازی کاربردی به سرویس هدف که ازطریق «آداپتور Apigee برای Envoy» پراکسی شده است استفاده کنید.

۱. وارد سیستم Apigee شوید

  1. «میانای کاربری Apigee» را در مرورگر باز کنید.
  2. پس‌از ورود به واسط کاربر، همان سازمانی را که برای پیکربندی «وقث‌دهنده Apigee برای Envoy» استفاده کرده‌اید انتخاب کنید.

۲. ایجاد توسعه‌دهنده

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

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

۳. ایجاد محصول میانای برنامه‌سازی کاربردی

از نمونه «ساخت محصول» که در زیر ارائه شده است پیروی کنید. همچنین درباره پیکربندی محصول API را ببینید.

  1. در منو پیمایش کناری، انتشار > محصولات API را انتخاب کنید.
  2. روی + محصول API کلیک کنید.
  3. صفحه «جزئیات محصول» را به‌صورت زیر تکمیل کنید.
    4. فیلد مقدار
    نام httpbin-product
    نام نمایشی httpbin product
    محیط your_environment

    این را روی محیطی تنظیم کنید که هنگام آماده‌سازی «وقث‌دهنده Apigee برای Envoy» استفاده کرده‌اید.

    دسترسی Private
    Quota ‫۵ درخواست در هر ۱ دقیقه

    همچنین Quota را ببینید.

  4. در بخش هدف‌های سرویس راه دور Apigee، روی افزودن هدف سرویس راه دور Apigee کلیک کنید.
  5. در کادر گفتگوی هدف سرویس راه دور Apigee، مقادیر زیر را اضافه کنید:
    مشخصه مقدار شرح
    نام هدف نام سرویس مقصد را وارد کنید. برای مثال: httpbin.org نقطه پایان هدف که با پراکسی Envoy مواجه است.
    مسیر مسیر منبعی را در سرویس وارد کنید تا مطابقت داده شود. برای مثال: /headers. مسیر درخواست برای مطابقت با نقطه پایانی هدف. فراخوانی‌های پراکسی میانای برنامه‌سازی کاربردی به این مسیر با این محصول میانای برنامه‌سازی کاربردی مطابقت خواهد داشت.
  6. روی ذخیره کلیک کنید.

۴. ایجاد برنامه توسعه‌دهندگان

  1. در منو پیمایش کناری، انتشار > برنامه‌ها را انتخاب کنید.
  2. روی + برنامه کلیک کنید.
  3. صفحه «برنامه توسعه‌دهنده» را به‌صورت زیر تکمیل کنید. تا زمانی که دستورالعمل ذخیره کردن را دریافت نکرده‌اید، «ذخیره» نکنید.
    4. نام httpbin-app
    نام نمایشی httpbin app
    توسعه‌دهنده توسعه‌دهنده‌ای را که قبلاً ساخته‌اید انتخاب کنید یا توسعه‌دهنده موردنظرتان را از فهرست انتخاب کنید.
  4. سپس، محصول میانای برنامه‌سازی کاربردی را به برنامه اضافه کنید:
    1. در بخش «اطلاعات اعتباری»، روی + افزودن محصول کلیک کنید و محصولی را که به‌تازگی پیکربندی کرده‌اید انتخاب کنید: httpbin-product.
    2. روی ایجاد کردن کلیک کنید.
    3. در بخش «اطلاعات اعتباری»، روی نمایش در کنار کلید کلیک کنید.
    4. مقدار «کلید مصرف‌کننده» را کپی کنید. این مقدار کلید میانای برنامه‌سازی کاربردی است که برای فراخوانی میانای برنامه‌سازی کاربردی سرویس httpbin استفاده خواهید کرد.

    درباره محصولات میانای برنامه‌سازی کاربردی

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

    تعریف محصول میانای برنامه‌سازی کاربردی

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

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

    هدف‌های سرویس ازراه‌دور

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

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

    مسیر منبع میانای برنامه‌سازی کاربردی

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

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

    سهمیه

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

    کاربردهای سهمیه

    سهمیه‌ها به شما امکان می‌دهند تعداد درخواست‌هایی را که یک کارخواه می‌تواند در یک مدت زمان مشخص به یک سرویس ارسال کند، اعمال کنید. از سهمیه‌ها اغلب برای اجرای قراردادهای کسب‌وکار یا «قراردادهای سطح خدمات» با توسعه‌دهندگان و شرکا استفاده می‌شود، نه برای مدیریت ترافیک عملیاتی. برای مثال، از سهمیه می‌توان برای محدود کردن ترافیک سرویس رایگان استفاده کرد، درحالی‌که به مشتریان پولی دسترسی کامل داده می‌شود.

    سهمیه در «محصول میانای برنامه‌سازی کاربردی» تعریف شده است

    پارامترهای سهمیه در «محصولات میانای برنامه‌سازی کاربردی» پیکربندی می‌شوند. برای مثال، وقتی «محصول» API ایجاد می‌کنید، می‌توانید به‌صورت اختیاری حد سهمیه مجاز، واحد زمان، و فاصله را تنظیم کنید.

    ازآنجایی‌که کلیدهای API به «محصولات API» برمی‌گردند، هر بار که کلید API درستی‌سنجی می‌شود، شمارنده سهمیه مناسب می‌تواند کاهش یابد (اگر «سهمیه» در «محصول» منسوب تعریف شده باشد).

    برخلاف زمان اجرای Apigee، سهمیه‌های واردشده در تعریف «محصول» به‌طور خودکار توسط «خدمات از دور Apigee» اعمال می‌شوند. اگر درخواست مجاز باشد، درخواست در مقابل سهمیه مجاز محاسبه خواهد شد.

    مکان‌هایی که سهمیه‌ها در آن‌ها حفظ می‌شوند

    سهمیه‌ها به‌صورت محلی توسط فرایند «خدمات از دور» حفظ و بررسی می‌شوند و به‌صورت ناهمزمان با «زمان اجرای Apigee» حفظ می‌شوند. این یعنی سهمیه‌ها دقیق نیستند و اگر بیش‌از یک «سرویس ازراه‌دور» داشته باشید که سهمیه را حفظ می‌کند، احتمالاً مقداری از سهمیه فراتر می‌رود. اگر اتصال به «زمان اجرای Apigee» مختل شود، سهمیه محلی تا زمانی که بتواند دوباره به «زمان اجرای Apigee» متصل شود، به‌عنوان سهمیه مستقل ادامه خواهد یافت.

    دوربین تفنگ OAuth

    اگر از نشان‌های JWT استفاده می‌کنید، می‌توانید نشان‌ها را به زیرمجموعه‌های دامنه‌های OAuth مجاز محدود کنید. محدوده‌های اختصاص‌یافته به کد JWT صادرشده شما با محدوده‌های «محصول API» مقایسه خواهد شد.

    درباره برنامه‌های توسعه‌دهنده

    پس‌از پیکربندی «محصولات API»، «برنامه‌ای» مرتبط با «توسعه‌دهنده» ایجاد خواهید کرد. این برنامه به مشتری اجازه می‌دهد با «کلید میانای برنامه‌سازی کاربردی» یا «کد JWT» به «محصولات میانای برنامه‌سازی کاربردی» مرتبط دسترسی داشته باشد.

    استفاده از اصالت‌سنجی مبتنی بر JWT

    می‌توانید به‌جای استفاده از کلید میانای برنامه‌سازی کاربردی، از یک کد 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 JWT

    «نشان‌های Apigee JWT» را می‌توان بااستفاده از «میانای خط فرمان» ایجاد کرد:

    $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 ارسال کنید. مثال:

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

    خطای کد JWT

    رد کردن Envoy

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

    Jwks remote fetch is failed

    اگر این‌طور است، مطمئن شوید که پیکربندی Envoy شما حاوی یک نشانی وب معتبر در بخش remote_jwks است، Envoy می‌تواند به آن دسترسی داشته باشد، و هنگام نصب پراکسی Apigee، گواهینامه‌ها را به‌درستی تنظیم کرده‌اید. باید بتوانید با تماس 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

    اشکال‌زدایی

    کلید میانای برنامه‌سازی کاربردی معتبر کار نمی‌کند را ببینید.

    ثبت

    می‌توانید سطح گزارش‌گیری را در سرویس $REMOTE_SERVICE_HOME/apigee-remote-service-envoy تنظیم کنید. همه گزارش‌های ثبت‌شده به stdout و stderr ارسال می‌شود.

    عنصر الزامی شرح
    ‫-l،‏ ‎--log-level سطوح معتبر: اشکال‌زدایی، اطلاعات، هشدار، خطا. سطح گزارش‌گیری را تنظیم می‌کند. پیش‌فرض: info
    ‫-j،‏ --json-log برونداد گزارش را به‌صورت سوابق JSON منتشر می‌کند.

    ‫Envoy گزارش‌گیری ارائه می‌دهد. برای کسب اطلاعات بیشتر، پیوندهای اسناد Envoy زیر را ببینید:

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

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

    درباره سنجه‌ها و Analytics

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

    تجزیه‌وتحلیل Envoy

    پیوندهای زیر اطلاعاتی درباره دریافت داده‌های تجزیه‌وتحلیل Envoy proxy ارائه می‌دهند:

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

    پیوندهای زیر اطلاعاتی درباره دریافت داده‌های تجزیه‌وتحلیل Envoy proxy ارائه می‌دهند:

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

    «خدمات از دور Apigee برای Envoy» آمار درخواست را برای پردازش تجزیه‌وتحلیل به Apigee ارسال می‌کند. ‫Apigee این درخواست‌ها را تحت نام «محصول API» مرتبط گزارش می‌کند.

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

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

    اکنون می‌توانید آداپتور را فعال کنید تا چندین محیط را در سازمان 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_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