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

شما در حال مشاهده مستندات 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 استفاده کردید، تنظیم کنید.

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

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

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

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

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

    $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

    وقتی توکن را داشتید، کافیست آن را در هدر 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) برای بررسی توکن خود استفاده کنید. مثال

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

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

    اکنون می‌توانید آداپتور را برای سرویس‌دهی به چندین محیط در یک سازمان 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 برای Private Cloud فعال می‌کند. به عنوان مثال: 

    tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false