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

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

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

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

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

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

2. إنشاء حساب مطوِّر

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

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

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

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

  1. انقر على نشر > منتجات واجهة برمجة التطبيقات في قائمة التنقّل الجانبية.
  2. انقر على + منتج واجهة برمجة التطبيقات.
  3. املأ صفحة "تفاصيل المنتج" على النحو التالي. لا تنقر على حفظ إلى أن يُطلب منك ذلك.
    4. الحقل القيمة
    الاسم httpbin-product
    الاسم المعروض httpbin product
    البيئة your_environment

    اضبط هذا الخيار على البيئة التي استخدمتها عند توفير Apigee Adapter for Envoy باستخدام apigee-remote-service-cli.

    إمكانية الوصول Private
    Quota 5 طلبات كل دقيقة

    اطّلِع أيضًا على التعرّف على الحصص.

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

    السحابة الإلكترونية العامة أو الخاصة في Edge: تعرض لقطة الشاشة التالية إعدادات مربّع الحوار التي تم ضبطها بشكل صحيح للهدف httpbin.org، وهو إعداد مناسب للسحابة الإلكترونية العامة أو الخاصة في Apigee Edge.

  6. انقر على حفظ.

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

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

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

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

تعريف المنتج الذي يوفّره API

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

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

أهداف الخدمة البعيدة

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

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

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

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

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

الحصة

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

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

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

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

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

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

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

مواضع الاحتفاظ بالحِصص

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

نطاقات 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 باستخدام واجهة سطر الأوامر (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 المميّز

بعد الحصول على الرمز المميّز، ما عليك سوى تمريره إلى Envoy في عنوان Authorization. مثال:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

تعذُّر الحصول على رمز JWT

رفض Envoy

إذا رفضت 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 قد تحتاج إلى تعديلها.

فحص رمز مميّز

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

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 المستويات الصالحة: debug وinfo وwarn وerror. يضبط مستوى التسجيل. القيمة التلقائية: 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 for Envoy إحصاءات الطلبات إلى Apigee لمعالجتها في "إحصاءات Google". تسجّل Apigee هذه الطلبات ضِمن اسم "منتج واجهة برمجة التطبيقات" المرتبط بها.

للحصول على معلومات حول إحصاءات Apigee، راجِع نظرة عامة على خدمات الإحصاءات.