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

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

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

يوضّح المثال التالي كيفية الحصول على مفتاح واجهة برمجة تطبيقات يمكنك استخدامه للتحقّق من صحة طلبات البيانات من واجهة برمجة التطبيقات لخدمة هدف يتم إرسالها عبر خادم وكيل من خلال Apigee Adapter for 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.
    الخادم الوكيل لواجهة برمجة التطبيقات remote-service الخادم الوكيل remote-service الذي تم توفيره على Apigee أثناء تثبيت محوِّل Envoy.
    المسار أدخِل /resource_path لمطابقة مسار محدّد. على سبيل المثال: /httpbin. مسار الطلب المطلوب مطابقته على نقطة النهاية المستهدفة. إنّ طلبات الخادم الوكيل لواجهة برمجة التطبيقات لهذا المسار ستتطابق مع هذا المنتج من واجهة برمجة التطبيقات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الحصة

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

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

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

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

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

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

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

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

يتم الاحتفاظ بالحصص والتحقّق منها محليًا من خلال عملية "الخدمة عن بُعد" وتتم صيانتها بشكل غير متزامن من خلال "وقت تشغيل Apigee". وهذا يعني أن الحصص غير محددة ومن المحتمل أن يتم تجاوزها إذا كان لديك أكثر من خدمة عن بُعد تحتفظ بالحصة. في حال تعطُّل الاتصال بـ 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 باستخدام واجهة سطر الأوامر:

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 تحتوي على معرّف موارد منتظم (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 المستويات الصالحة: تصحيح الأخطاء والمعلومات والتحذير والخطأ. لضبط مستوى التسجيل. الإعدادات التلقائية: معلومات
-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 لمعالجة الإحصاءات. تُبلغ Apigee عن هذه الطلبات ضمن اسم المنتج المرتبط في واجهة برمجة التطبيقات.

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