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

درحال مشاهده اسناد 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» با apigee-remote-service-cli استفاده کرده‌اید.

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

    همچنین درک سهمیه‌ها را ببینید.

  4. در بخش هدف‌های سرویس راه دور Apigee، روی افزودن هدف سرویس راه دور Apigee کلیک کنید.
  5. در کادر گفتگوی هدف سرویس راه دور Apigee، مقادیر زیر را اضافه کنید:
    مشخصه مقدار شرح
    نام هدف نام سرویس مقصد را وارد کنید. برای مثال: httpbin.org نقطه پایان هدف که با پراکسی Envoy مواجه است.
    کارگزار نیابتی میانای برنامه‌سازی کاربردی remote-service کارگزار remote-service که درطول نصب «وقث‌دهنده Envoy» در Apigee تدارک دیده شده است.
    مسیر برای مطابقت با مسیر خاص، /resource_path را وارد کنید. برای مثال: /httpbin. مسیر درخواست برای مطابقت با نقطه پایانی هدف. فراخوانی‌های پراکسی میانای برنامه‌سازی کاربردی به این مسیر با این محصول میانای برنامه‌سازی کاربردی مطابقت خواهد داشت.

    ابر عمومی یا خصوصی Edge: نماگرفت زیر تنظیمات کادر گفتگوی پیکربندی‌شده صحیح را برای هدف httpbin.org نشان می‌دهد، پیکربندی مناسب برای ابر عمومی یا خصوصی Apigee Edge.

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

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

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

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

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

curl https://org-env.apigee.net/remote-service/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 برای بازرسی کردن نشان خود استفاده کنید. مثال

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

یا 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

اشکال‌زدایی

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

ثبت

می‌توانید سطح گزارش‌گیری را در سرویس $REMOTE_SERVICE_HOME/apigee-remote-service-envoy تنظیم کنید. همه گزارش‌های ثبت‌شده به 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 مراجعه کنید.