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

يتم الآن عرض مستندات 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.

    الوصول Private
    الحصة 5 طلبات كل دقيقة

    راجِع أيضًا الحصة.

  5. في قسم أهداف خدمة Apigee عن بُعد، انقر على إضافة هدف خدمة عن بُعد في Apigee.
  6. في مربع حوار هدف الخدمة البعيدة لـ Apigee، أضِف القيم التالية:
    السمة القيمة الوصف
    اسم الهدف أدخِل اسم الخدمة المستهدفة. مثال: httpbin.org نقطة النهاية المستهدفة التي يقدمها الخادم الوكيل Envoy.
    المسار أدخِل مسار مورد في الخدمة لمطابقته. على سبيل المثال: /headers. مسار الطلب المطلوب مطابقته على نقطة النهاية المستهدفة. إنّ طلبات الخادم الوكيل لواجهة برمجة التطبيقات لهذا المسار ستتطابق مع هذا المنتج من واجهة برمجة التطبيقات.
  7. انقر على حفظ.

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

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

    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 للنظام الأساسي للسحابة الإلكترونية الخاصة. مثلاً:

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