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

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

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

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

۱. وارد Apigee شوید

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

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

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

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

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

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

  1. در منوی ناوبری کناری، گزینه انتشار > محصولات API را انتخاب کنید.
  2. روی + محصول API کلیک کنید.
  3. صفحه جزئیات محصول را به شرح زیر پر کنید. تا زمانی که دستورالعمل ذخیره سازی داده نشده است، روی آن کلیک نکنید.
    4. میدان ارزش
    نام httpbin-product
    نام نمایشی httpbin product
    محیط زیست your_environment

    این را روی محیطی تنظیم کنید که هنگام تهیه آداپتور Apigee برای Envoy باapigee-remote-service-cli از آن استفاده کردید.

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

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

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

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

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

۴. یک اپلیکیشن توسعه‌دهنده ایجاد کنید

  1. در منوی ناوبری کناری، گزینه‌ی انتشار > برنامه‌ها را انتخاب کنید.
  2. روی + برنامه کلیک کنید.
  3. صفحه برنامه توسعه‌دهندگان را به شرح زیر پر کنید. تا زمانی که دستورالعملی برای ذخیره داده نشده، آن را ذخیره نکنید.
    4. نام httpbin-app
    نام نمایشی httpbin app
    توسعه‌دهنده توسعه‌دهنده‌ای که قبلاً ایجاد کرده‌اید را انتخاب کنید، یا هر توسعه‌دهنده‌ای را که می‌خواهید از لیست انتخاب کنید.
  4. سپس، دو محصول به برنامه اضافه کنید:
    1. ابتدا، در بخش اعتبارنامه‌ها، روی + افزودن محصول کلیک کنید و محصولی را که پیکربندی کرده‌اید انتخاب کنید: httpbin-product .
    2. سپس، محصول سرویس از راه دور را اضافه کنید. این محصول به طور خودکار هنگام تهیه Apigee ایجاد شده است.
  5. روی ایجاد کلیک کنید.
  6. در قسمت اعتبارنامه‌ها، روی نمایش (Show) در کنار کلید (Key) کلیک کنید.
  7. مقدار Consumer Key را کپی کنید. این مقدار، کلید API است که برای برقراری تماس‌های API به سرویس httpbin از آن استفاده خواهید کرد.

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

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

تعریف محصول API

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

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

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

تعریف محصول API در صورتی برای یک درخواست اعمال می‌شود که درخواست هم با اتصال هدف (مثلاً httpbin.org ) و هم با مسیر درخواست (مثلاً /httpbin ) مطابقت داشته باشد. فهرستی از اهداف بالقوه به عنوان یک ویژگی در محصول 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 API Products مطابقت دارد تا آن را در برابر هدف درخواست تأیید کند.

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

توکن‌های JWT آپیجی را می‌توان با استفاده از رابط خط فرمان (CLI) ایجاد کرد:

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

وقتی توکن را داشتید، کافیست آن را در هدر 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، گواهی‌ها را به درستی تنظیم کرده‌اید. شما باید بتوانید URI را مستقیماً با یک فراخوانی 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

اشکال‌زدایی

به خطای کلید API معتبر مراجعه کنید.

ثبت وقایع

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

عنصر مورد نیاز توضیحات
-l، --سطح گزارش سطوح معتبر: اشکال‌زدایی، اطلاعات، هشدار، خطا. سطح ثبت وقایع را تنظیم می‌کند. پیش‌فرض: 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 قابل دسترسی باشد.

درباره معیارها و تحلیل‌ها

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

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

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

تحلیل‌های ایستیو

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

تحلیل‌های آپیجی

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

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