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

أنت الآن بصدد الاطّلاع على مستندات 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" لـ Envoy.
إمكانية الوصول	Private
Quota	5 طلبات كل دقيقة اطّلِع أيضًا على Quota.

4. في قسم أهداف الخدمة البعيدة في Apigee، انقر على إضافة هدف خدمة بعيدة في Apigee.
5. في مربّع الحوار "استهداف الخدمة البعيدة في Apigee"، أضِف القيم التالية:

   السمة	القيمة	الوصف
   اسم الهدف	أدخِل اسم الخدمة المستهدَفة. مثلاً: httpbin.org	نقطة النهاية المستهدَفة التي يسبقها الخادم الوكيل Envoy
   المسار	أدخِل مسار مورد على الخدمة لمطابقته. على سبيل المثال: /headers.	مسار الطلب الذي يجب مطابقته في نقطة النهاية المستهدَفة. ستتطابق طلبات البيانات من واجهة برمجة التطبيقات الوكيلة إلى هذا المسار مع منتج واجهة برمجة التطبيقات هذا.

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

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

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

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

4. بعد ذلك، أضِف منتج واجهة برمجة التطبيقات إلى التطبيق:
   1. في قسم "بيانات الاعتماد"، انقر على + إضافة منتج واختَر المنتج الذي أعددته للتو: httpbin-product.
   2. انقر على إنشاء.
   3. ضمن "بيانات الاعتماد"، انقر على عرض بجانب المفتاح.
   4. انسخ قيمة "مفتاح المستهلك". هذه القيمة هي مفتاح واجهة برمجة التطبيقات الذي ستستخدمه لإجراء طلبات البيانات من واجهة برمجة التطبيقات إلى خدمة 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) باتّباع الخطوات التالية:

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

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

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

   فحص رمز مميّز

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

   $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	المستويات الصالحة: debug وinfo وwarn وerror.	يضبط مستوى التسجيل. القيمة التلقائية: info
   ‎-j, --json-log		تعرض هذه السمة ناتج السجلّ على شكل سجلّات JSON.

   توفّر 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، راجِع نظرة عامة على خدمات الإحصاءات.

   إتاحة بيئة متعددة المستأجرين

   يمكنك الآن تفعيل المحوّل لخدمة بيئات متعدّدة في مؤسسة Apigee. تتيح لك هذه الميزة استخدام محوّل Apigee واحد لـ Envoy مرتبط بمؤسسة Apigee واحدة لخدمة بيئات متعدّدة. قبل هذا التغيير، كان محوّل واحد مرتبطًا دائمًا ببيئة Apigee واحدة.

   لضبط إعدادات إتاحة بيئات متعددة، غيِّر قيمة tenant:env_name إلى * في الملف config.yaml. على سبيل المثال:

   1. افتح ملف config.yaml في محرِّر.
   2. غيِّر قيمة 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

   3. احفظ الملف.
   4. تطبيق الملف:

      kubectl apply -f $CLI_HOME/config.yaml

   عند إعداد وضع البيئات المتعدّدة، يجب أيضًا إعداد Envoy لإرسال قيمة بيئة مناسبة إلى المحوّل عن طريق إضافة البيانات الوصفية التالية في القسم virtual_hosts:routes من ملف envoy-config.yaml. على سبيل المثال:

   1. أنشئ ملف envoy-config.yaml باستخدام واجهة سطر الأوامر. على سبيل المثال:

      $CLI_HOME/apigee-remote-service-cli samples create \
        -t envoy-1.16 -c ./config.yaml --out myconfigs

   2. افتح الملف الذي تم إنشاؤه (يُسمى envoy-config.yaml).
   3. أضِف البيانات الوصفية التالية في القسم 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

   4. كرِّر الخطوة الأخيرة لإضافة بيئات إضافية حسب الحاجة.
   5. احفظ الملف وطبِّقه.

   إعداد بروتوكول mTLS بين المحوّل ووقت تشغيل Apigee

   يمكنك تقديم شهادات بروتوكول أمان طبقة النقل (TLS) من جهة العميل في القسم tenant من ملف config.yaml الخاص بالمحوّل لاستخدام بروتوكول أمان طبقة النقل المتبادل (mTLS) بين المحوّل ووقت تشغيل Apigee. ينطبق هذا التغيير على جميع منصات Apigee المتوافقة. يتيح ذلك أيضًا استخدام بروتوكول mTLS للإحصاءات في منصة Apigee Edge Private Cloud. على سبيل المثال:

   tenant:
     tls:
       ca_file: path/ca.pem
       cert_file: path/cert.pem
       key_file: path/key.pem
       allow_unverified_ssl_cert: false