دليل العمليات

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

كيفية الحصول على مفتاح واجهة برمجة التطبيقات

يوضّح المثال التالي كيفية الحصول على مفتاح واجهة برمجة تطبيقات يمكنك استخدامه للتحقق من صحة الرمز. طلبات البيانات من واجهة برمجة التطبيقات إلى خدمة مستهدَفة تم إنشاؤها باستخدام خادم وكيل من خلال محوّل Apigee لتطبيق Envoy.

1. تسجيل الدخول إلى Apigee

  1. افتح واجهة مستخدم Apigee في متصفّح.
  2. بعد الانتقال إلى واجهة المستخدم، اختَر المؤسسة نفسها التي استخدمتها لإعداد مهايئ Apigee لتطبيق Envoy.

2. إنشاء مطوّر برامج

يمكنك استخدام مطوِّر حالي للاختبار أو إنشاء مطوّر جديد على النحو التالي:

  1. اختَر نشر >. المطوّرون في قائمة التنقّل الجانبية
  2. انقر على + مطوّر برامج.
  3. املأ مربّع الحوار لإنشاء مطوِّر جديد. يمكنك استخدام أي اسم أو عنوان بريد إلكتروني تريده للمطوِّر.

3- إنشاء منتج واجهة برمجة تطبيقات

اتبع مثال إنشاء المنتج الموضح أدناه. يمكن أيضًا مراجعة لمحة عن إعدادات منتج واجهة برمجة التطبيقات

  1. اختَر نشر >. منتجات واجهة برمجة التطبيقات في قائمة التنقل الجانبية
  2. انقر على + منتج واجهة برمجة التطبيقات.
  3. املأ صفحة تفاصيل المنتج على النحو التالي.
    4. الحقل القيمة
    الاسم httpbin-product
    الاسم المعروض httpbin product
    البيئة your_environment

    عليك ضبط هذا الإعداد على البيئة التي استخدمتها عند توفير محوّل Apigee في Envoy.

    الوصول Private
    النسبة 5 طلبات كل دقيقة واحدة

    راجِع أيضًا الحصة.

  4. في قسم أهداف خدمة Apigee عن بُعد، انقر على إضافة هدف خدمة Apigee عن بُعد.
  5. في مربّع الحوار هدف الخدمة عن بُعد في Apigee، أضِف القيم التالية:
    السمة القيمة الوصف
    اسم الاستهداف يُرجى إدخال اسم الخدمة المستهدفة. مثلاً: httpbin.org نقطة النهاية المستهدفة التي يواجهها الخادم الوكيل Envoy.
    المسار أدخِل مسار مورد في الخدمة من أجل مطابقته. بالنسبة مثال: /headers مسار الطلب المطلوب مطابقته على نقطة النهاية المستهدفة. طلبات بيانات من خادم وكيل واجهة برمجة التطبيقات إلى هذا المسار سيطابق منتج واجهة برمجة التطبيقات هذا.
  6. انقر على حفظ.

4. إنشاء تطبيق مطوِّر

  1. اختَر نشر >. التطبيقات في قائمة التنقّل الجانبية.
  2. انقر على + تطبيق.
  3. املأ صفحة تطبيق المطوِّر على النحو التالي. يُرجى عدم الحفظ حتى يُطلب منك ذلك.
    4. الاسم httpbin-app
    الاسم المعروض httpbin app
    المطوّر اختر المطوِّر الذي أنشأته في السابق أو اختَر أيّ مطوّر برامج تريده من القائمة.
  4. بعد ذلك، أضِف منتج واجهة برمجة التطبيقات إلى التطبيق:
    1. في قسم Credentials (بيانات الاعتماد)، انقر على + Add product (+ إضافة منتج) واختَر المنتج الذي تريد التي تم إعدادها للتو: httpbin-product.
    2. انقر على إنشاء.
    3. ضمن بيانات الاعتماد، انقر على عرض بجانب المفتاح.
    4. انسخ قيمة مفتاح العميل. هذه القيمة هي مفتاح واجهة برمجة التطبيقات الذي ستستخدمه لإجراء طلبات بيانات من واجهة برمجة التطبيقات إلى خدمة httpbin.

    لمحة عن منتجات واجهة برمجة التطبيقات

    منتجات واجهة برمجة التطبيقات هي عنصر التحكّم الأساسي لخدمة Apigee عن بُعد. عند إنشاء منتج واجهة برمجة تطبيقات وربطه خدمة مستهدفة، فأنت تنشئ سياسة تم تطبيقه على أي طلبات لإعداد محوّل Apigee for Envoy للتعامل معها.

    تعريف منتج واجهة برمجة التطبيقات

    عند تعريف منتج واجهة برمجة تطبيقات في Apigee، يمكنك تحديد عدد من المعلمات لتقييم الطلبات:

    • الهدف
    • مسار الطلب
    • الحصة
    • نطاقات OAuth

    أهداف الخدمة عن بُعد

    سيتم تطبيق تعريف منتج واجهة برمجة التطبيقات على طلب في حال تطابق الطلب مع كلٍّ من الهدف الربط (مثل httpbin.org) ومسار الطلب (مثل /httpbin). يتم تخزين قائمة بالأهداف المحتملة كسمة في منتج واجهة برمجة التطبيقات.

    تتحقق خدمة Apigee Remote Service تلقائيًا من عنوان :authority (host) الخاص في Envoy مقابل قائمة أهدافها ولكن يمكن تكوينها لاستخدام رؤوس أخرى.

    مسار مورد واجهة برمجة التطبيقات

    يتطابق المسار الذي تم إدخاله وفقًا للقواعد التالية:

    • تتطابق شرطة مائلة واحدة (/) بمفردها مع أي مسار.
    • تكون السمة * صالحة في أي مكان وتطابق داخل مقطع (بين الشرطات المائلة).
    • تكون السمة ** صالحة في النهاية وتتطابق مع أي نص في نهاية السطر.

    الحصة

    تحدد الحصة عدد رسائل الطلبات التي يُسمح للتطبيق بإرسالها إلى على مدار ساعة أو يوم أو أسبوع أو شهر. عندما يصل أحد التطبيقات إلى الحد الأقصى لحصته، يتم رفض طلبات البيانات اللاحقة من واجهة برمجة التطبيقات.

    حالات استخدام الحصة

    تسمح لك الحصص بفرض عدد الطلبات التي يمكن للعميل تقديمها إلى إحدى الخدمات في لفترة زمنية معينة. غالبًا ما يتم استخدام الحصص لفرض عقود الأعمال أو اتفاقيات مستوى الخدمة مع والمطورين والشركاء، بدلاً من إدارة عدد الزيارات التشغيلية. على سبيل المثال، لتحديد حركة البيانات لإحدى الخدمات المجانية، مع السماح بالوصول الكامل إلى العملاء الذين يدفعون رسومًا.

    يتم تحديد الحصة في منتج واجهة برمجة التطبيقات

    يتم ضبط مَعلمات الحصة في منتجات واجهات برمجة التطبيقات. على سبيل المثال، عند إنشاء واجهة برمجة تطبيقات المنتج، يمكنك اختياريًا ضبط الحدّ الأقصى للحصة المسموح بها والوحدة الزمنية والفاصل الزمني.

    نظرًا لتعيين مفاتيح واجهة برمجة التطبيقات مرة أخرى إلى منتجات واجهة برمجة التطبيقات، فإنه في كل مرة يتم فيها التحقق من مفتاح واجهة برمجة التطبيقات يمكن إنقاص عدّاد الحصص المناسب (إذا تم تحديد حصة في المنتج المرتبط).

    على عكس بيئة تشغيل Apigee، تكون الحصص التي يتم إدخالها في تعريف المنتج هي يتم فرضها تلقائيًا بواسطة خدمة Apigee عن بُعد. إذا كان الطلب مسموحًا به، سيتم احتساب الطلب من الحصة المسموح بها.

    أماكن الاحتفاظ بالحصص

    يتم الاحتفاظ بالحصص وفحصها محليًا من خلال عملية الخدمة عن بُعد وبشكل غير متزامن باستخدام Apigee Runtime. وهذا يعني أن الحصص غير دقيقة ومن المحتمل أن يكون لها إذا كان لديك أكثر من خدمة عن بُعد تحتفظ بحصّة المساحة المحددة. إذا كانت انقطع الاتصال بـ Apigee Runtime، فستستمرّ الحصة المحلية كحصة مستقلة إلى حين إعادة الاتصال ببيئة تشغيل Apigee.

    نطاقات OAuth

    في حال استخدام رموز JWT المميزة، يمكنك حصر الرموز المميّزة بمجموعات فرعية من نطاقات OAuth المسموح بها. سيتم التحقّق من النطاقات المخصَّصة لرمز JWT المميز الذي تم إصداره مقابل نطاقات منتج واجهة برمجة التطبيقات.

    لمحة عن تطبيقات المطوّرين

    بعد ضبط منتجات واجهة برمجة التطبيقات، عليك إنشاء تطبيق مرتبط بمطوّر. التطبيق يسمح ذلك للعميل بالوصول إلى منتجات واجهة برمجة التطبيقات المرتبطة باستخدام مفتاح واجهة برمجة التطبيقات أو رمز JWT.

    استخدام المصادقة المستندة إلى JWT

    يمكنك استخدام رمز JWT المميز لإجراء استدعاءات لخادم وكيل واجهة برمجة التطبيقات التي تمت مصادقتها بدلاً من استخدام مفتاح واجهة برمجة التطبيقات. هذا النمط كيفية استخدام الأمر apigee-remote-service-cli token إنشاء رموز JWT وفحصها وتدويرها.

    نظرة عامة

    تعالج خدمة Envoy عملية التحقق من JWT والمصادقة عليها باستخدام فلتر مصادقة JWT

    بعد المصادقة، يرسل فلتر Envoy ext-authz عناوين الطلب وJWT إلى apigee-remote-service-envoy تطابق هذه النتيجة مطالبتَي api_product_list وscope من JWT. مقابل منتجات Apigee API من أجل السماح لها بتنفيذ الهدف من الطلب.

    إنشاء رموز Apigee JWT

    يمكن إنشاء رموز Apigee JWT باستخدام واجهة سطر الأوامر:

    $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 المميز

    وبعد الحصول على الرمز المميز، يمكنك تمريره إلى 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_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. يتم إرسال كل التسجيل إلى Stderr وstdout.

    العنصر مطلوب الوصف
    -l, --log-level المستويات الصالحة: تصحيح الأخطاء والمعلومات والتحذير والخطأ. لضبط مستوى التسجيل. الإعدادات التلقائية: معلومات
    -j، --json-log يصدر مخرجات السجلّ كسجلات JSON.

    يوفر Envoy إمكانية التسجيل. لمزيد من المعلومات، يُرجى الاطّلاع على الروابط التالية في مستندات Envoy:

    استخدام خادم وكيل للشبكة

    يمكن إدراج خادم وكيل 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.

    لمحة عن المقاييس والإحصاءات

    تتوفّر نقطة نهاية Prometheus لمقاييس الأداء على :5001/metrics. يمكنك ضبط رقم المنفذ هذا. راجِع ملف الإعداد.

    إحصاءات Envoy

    تقدّم الروابط التالية معلومات حول الحصول على إحصاءات خادم وكيل Envoy. البيانات:

    إحصاءات Istio

    تقدّم الروابط التالية معلومات حول الحصول على إحصاءات خادم وكيل Envoy. البيانات:

    إحصاءات Apigee

    ترسل Apigee Remote Service في Envoy إحصاءات الطلبات إلى Apigee لمعالجة الإحصاءات. تُبلغ Apigee عن هذه الطلبات ضمن اسم منتج واجهة برمجة التطبيقات المرتبط.

    للحصول على معلومات حول Apigee analytics يُرجى الاطّلاع على نظرة عامة على خدمات "إحصاءات Google".

    توفير بيئة تشغيل متعدد النزلاء

    يمكنك الآن تفعيل المحوّل لخدمة متعددة البيئات في مؤسسة 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 Platform على سبيل المثال: 

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