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

أنت الآن بصدد الاطّلاع على مستندات 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. انقر على + منتج API.
3. املأ صفحة "تفاصيل المنتج" على النحو التالي. لا تنقر على حفظ إلا عند توجيهك بذلك.

الحقل	القيمة
الاسم	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.	مسار الطلب الذي يجب مطابقته في نقطة النهاية المستهدَفة. ستتطابق طلبات البيانات من واجهة برمجة التطبيقات الوكيلة إلى هذا المسار مع منتج واجهة برمجة التطبيقات هذا.

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

   

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

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

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

الاسم	httpbin-app
الاسم المعروض	httpbin app
المطوِّر	اختَر المطوِّر الذي أنشأته سابقًا أو أي مطوِّر تريده من القائمة.

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

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

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

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

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

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

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

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

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

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

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

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

الحصة

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

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

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

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

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

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

نطاقات OAuth

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

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

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

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

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

نظرة عامة

تتولّى Envoy عملية التحقّق من صحة رموز JWT والمصادقة عليها باستخدام JWT Authentication Filter.

بعد المصادقة، يرسل فلتر 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 الرمز المميّز، قد تظهر لك رسالة مثل:

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.

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

• تسجيل التطبيقات
• سجلّات الوصول
• تسجيل Stackdriver باستخدام GKE

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

يمكن إدراج وكيل 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 لمعالجة الإحصاءات. تسجّل Apigee هذه الطلبات ضمن اسم "منتج واجهة برمجة التطبيقات" المرتبط.

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