يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات
Apigee X. المعلومات
كيفية الحصول على مفتاح واجهة برمجة التطبيقات
يوضّح المثال التالي كيفية الحصول على مفتاح واجهة برمجة تطبيقات يمكنك استخدامه للتحقّق من صحة طلبات البيانات من واجهة برمجة التطبيقات لخدمة هدف يتم إرسالها عبر خادم وكيل من خلال Apigee Adapter for Envoy.
1- تسجيل الدخول إلى Apigee
- افتح واجهة مستخدم Apigee في متصفّح.
- بعد الانتقال إلى واجهة المستخدم، اختَر المؤسسة نفسها التي استخدمتها لضبط محوّل Apigee لخدمة Envoy.
2. إنشاء مطور
يمكنك الاستعانة بأحد المطوّرين الحاليين للاختبار أو إنشاء مطوّر جديد على النحو التالي:
- اختَر نشر > المطوّرون في قائمة التنقّل الجانبية.
- انقر على + مطوّر برامج.
- املأ مربّع الحوار لإنشاء مطوّر جديد. يمكنك استخدام أي اسم مطوّر أو عنوان بريد إلكتروني تريده.
3. إنشاء منتج واجهة برمجة التطبيقات
اتّبِع مثال إنشاء المنتج الوارد أدناه. يمكنك الاطّلاع أيضًا على مقالة لمحة عن إعدادات منتجات واجهة برمجة التطبيقات.
- اختر النشر > منتجات واجهة برمجة التطبيقات في قائمة التنقّل الجانبية.
- انقر على + منتج واجهة برمجة التطبيقات.
- املأ صفحة "تفاصيل المنتج" على النحو التالي.
- في قسم أهداف خدمة Apigee عن بُعد، انقر على إضافة هدف خدمة عن بُعد في Apigee.
- في مربع حوار هدف الخدمة البعيدة لـ Apigee، أضِف القيم التالية:
السمة القيمة الوصف اسم الهدف أدخِل اسم الخدمة المستهدفة. مثال: httpbin.org
نقطة النهاية المستهدفة التي يقدمها الخادم الوكيل Envoy. المسار أدخِل مسار مورد في الخدمة لمطابقته. على سبيل المثال: /headers
.مسار الطلب المطلوب مطابقته على نقطة النهاية المستهدفة. إنّ طلبات الخادم الوكيل لواجهة برمجة التطبيقات لهذا المسار ستتطابق مع هذا المنتج من واجهة برمجة التطبيقات. - انقر على حفظ.
الحقل | القيمة |
---|---|
الاسم | httpbin-product
|
الاسم المعروض | httpbin product
|
البيئة | your_environment
اضبط هذا الإعداد على البيئة التي استخدمتها عند توفير محوّل Apigee لتطبيق Envoy. |
الوصول | Private
|
الحصة | 5 طلبات كل دقيقة
راجِع أيضًا الحصة. |
4. إنشاء تطبيق مطوِّر
- اختَر نشر > التطبيقات في قائمة التنقّل الجانبية.
- انقر على + تطبيق.
- املأ صفحة "تطبيق المطوِّر" على النحو التالي. يُرجى عدم الحفظ إلا بعد تلقّي تعليمات بذلك.
- بعد ذلك، أضِف منتج واجهة برمجة التطبيقات إلى التطبيق:
- في قسم "بيانات الاعتماد"، انقر على + إضافة منتج واختَر المنتج الذي ضبطته للتو: httpbin-product.
- انقر على إنشاء.
- ضمن "بيانات الاعتماد"، انقر على عرض بجانب المفتاح.
- انسخ قيمة مفتاح العميل. هذه القيمة هي مفتاح واجهة برمجة التطبيقات
الذي ستستخدمه لإجراء طلبات بيانات من واجهة برمجة التطبيقات إلى خدمة
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 باستخدام واجهة سطر الأوامر:
$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
إذا رفض 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. يتم إرسال جميع عمليات التسجيل إلى stdout و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".
دعم بيئة الألعاب المتعددة المستأجرين
ويمكنك الآن تفعيل المحوِّل لخدمة بيئات متعددة في مؤسسة Apigee. تسمح لك هذه الميزة باستخدام محوِّل Apigee واحد لخدمة Envoy مرتبط بمؤسسة واحدة من Apigee لخدمة بيئات متعدّدة. وقبل إجراء هذا التغيير، كان يتم ربط محوّل واحد دائمًا ببيئة Apigee واحدة.
لضبط توافق عدة بيئات، عليك تغيير القيمة
tenant:env_name
إلى*
في الملفconfig.yaml
. مثلاً:- افتح ملف
config.yaml
في محرِّر. - غيِّر قيمة
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
- احفظ الملف.
- طبِّق الملف:
kubectl apply -f $CLI_HOME/config.yaml
عند ضبط وضع البيئات المتعدّدة، عليك أيضًا ضبط Envoy لإرسال قيمة بيئة مناسبة إلى المحوِّل عن طريق إضافة البيانات الوصفية التالية في قسم
virtual_hosts:routes
من ملفenvoy-config.yaml
. مثلاً:- أنشِئ ملف
envoy-config.yaml
باستخدام واجهة سطر الأوامر. مثلاً:$CLI_HOME/apigee-remote-service-cli samples create \ -t envoy-1.16 -c ./config.yaml --out myconfigs
- افتح الملف الذي تم إنشاؤه (يسمى
envoy-config.yaml
). - أضِف البيانات الوصفية التالية إما إلى القسم
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
- كرِّر الخطوة الأخيرة لإضافة بيئات إضافية حسب الحاجة.
- احفظ الملف وطبّقه.
ضبط mTLS بين المحوِّل ووقت تشغيل Apigee
يمكنك توفير شهادات بروتوكول أمان طبقة النقل (TLS) من جهة العميل في القسم
tenant
من ملفconfig.yaml
الخاص بالمحوِّل لاستخدام mTLS بين المحوِّل ووقت تشغيل Apigee. ينطبق هذا التغيير على جميع منصات Apigee المتوافقة. ويتيح أيضًا استخدام mTLS لإجراء الإحصاءات لخدمة Apigee Edge للنظام الأساسي للسحابة الإلكترونية الخاصة. مثلاً:tenant: tls: ca_file: path/ca.pem cert_file: path/cert.pem key_file: path/key.pem allow_unverified_ssl_cert: false
الاسم | httpbin-app
|
الاسم المعروض | httpbin app
|
مطوّر البرامج | حدد المطور الذي أنشأته سابقًا، أو اختر أي مطوّر برامج تريده من القائمة. |