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

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

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

يوضّح المثال التالي كيفية الحصول على مفتاح واجهة برمجة تطبيقات يمكنك استخدامه للتحقّق من صحة طلبات واجهة برمجة التطبيقات إلى خدمة مستهدفة يتم تمثيلها من خلال محوِّل 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 باستخدام apigee-remote-service-cli.

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

    اطّلِع أيضًا على فهم الحصص.

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

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

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

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

    منتجات واجهة برمجة التطبيقات هي نقطة التحكّم الأساسية في خدمة Apigee Remote Service. عند إنشاء منتج واجهة برمجة تطبيقات وربطه بأحد خدمات الوجهة، يتم إنشاء سياسة سيتم تطبيقها على أي طلبات يتم ضبط محوِّل Apigee لـ Envoy من أجل معالجتها.

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

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

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

    استهدافات الخدمة البعيدة

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

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

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

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

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

    الحصة

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

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

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

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

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

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

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

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

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

    نطاقات OAuth

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

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

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

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

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

    نظرة عامة

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

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

    إنشاء الرموز المميّزة لبروتوكول JWT في Apigee

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

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

    أو باستخدام نقطة نهاية رمز OAuth المميّز العادية. مثال على التجاعيد:

    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 تحتوي على عنوان URL صالح في القسم remote_jwks، ومن أنّه يمكن الوصول إليه من خلال Envoy، ومن أنّك أعددت الشهادات بشكل صحيح عند تثبيت خادم Apigee الوكيل. من المفترض أن تتمكّن من طلب عنوان URL مباشرةً باستخدام طلب GET والحصول على استجابة JSON صالحة.

    مثال:

    curl https://myorg-eval-test.apigee.net/remote-service/certs

    قد تبدو الرسائل الأخرى الواردة من Envoy على النحو التالي:

    • "لا يُسمح بالجماهير في Jwt"
    • "لم يتم إعداد جهة إصدار Jwt"

    هذه هي المتطلّبات الواردة في إعدادات Envoy التي قد تحتاج إلى تعديلها.

    فحص رمز مميّز

    يمكنك استخدام واجهة برمجة التطبيقات لفحص الرمز المميّز. مثال

    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 باستخدام متغيّري البيئة 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.