سياسة ExtensionCallout

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

استخدِم سياسة ExtensionCallout لدمج إضافة في خادم وكيل لواجهة برمجة التطبيقات.

توفّر الإضافة إمكانية الوصول إلى مرجع معيّن خارج Apigee Edge. يمكن أن يكون المرجع خدمات Google Cloud Platform، مثل Cloud Storage أو Cloud Speech-to-Text. ولكن يمكن أن يكون المرجع أي مرجع خارجي يمكن الوصول إليه عبر HTTP أو HTTPS.

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

قبل الوصول إلى إضافة من سياسة ExtensionCallout، يجب إضافة الإضافة وضبطها ونشرها من حزمة إضافة مثبَّتة مسبقًا في مؤسسة Apigee Edge.

نماذج

في ما يلي مثال على سياسة لاستخدامها مع إضافة Cloud Logging:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

راجِع البرنامج التعليمي: استخدام الإضافات للحصول على برنامج تعليمي كامل حول استخدام إضافة Cloud Logging.

للاطّلاع على أمثلة لجميع الإضافات المتاحة، يُرجى الانتقال إلى نظرة عامة على مرجع الإضافات.

لمحة عن سياسة ExtensionCallout

استخدِم سياسة ExtensionCallout عندما تريد استخدام إضافة تم ضبطها للوصول إلى مصدر خارجي من داخل خادم وكيل لواجهة برمجة التطبيقات.

قبل استخدام هذه السياسة، يجب توفُّر ما يلي:

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

استخدام سياسة ExtensionCallout في PostClientFlow

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

إذا كنت تريد استخدام سياسة ExtensionCallout لاستدعاء إضافة Google Cloud Logging من PostClientFlow، تأكَّد من ضبط العلامة features.allowExtensionsInPostClientFlow على true في مؤسستك.

• إذا كنت من عملاء Apigee Edge for Public Cloud، يتم ضبط العلامة features.allowExtensionsInPostClientFlow على true تلقائيًا.

• إذا كنت من عملاء "Apigee Edge للسحابة الخاصة"، استخدِم واجهة برمجة التطبيقات تعديل خصائص المؤسسة لضبط العلامة features.allowExtensionsInPostClientFlow على true.

تنطبق جميع القيود المفروضة على استدعاء سياسة MessageLogging من PostClientFlow أيضًا على سياسة ExtensionCallout. اطّلِع على ملاحظات الاستخدام لمزيد من المعلومات.

مرجع العنصر

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

سمات <ConnectorCallout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة name لتصنيف السياسة في إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

العنصر <Action>

الإجراء الذي تعرضه الإضافة والذي يجب أن تستدعيه السياسة.

<Action>action-exposed-by-extension</Action>

تعرض كل إضافة مجموعة من الإجراءات التي تتيح الوصول إلى وظائف المورد الذي تمثله الإضافة. يمكنك اعتبار الإجراء دالة تستدعيها باستخدام هذه السياسة، وذلك باستخدام محتوى العنصر <Input> لتحديد وسيطات الدالة. يتم تخزين استجابة الإجراء في المتغيّر الذي تحدّده باستخدام العنصر <Output>.

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

عنصر <Connector>

اسم الإضافة التي تم ضبطها لاستخدامها هذا هو الاسم المحدد للنطاق البيئي الذي تمّ منحه للإضافة عند إعدادها للنشر في بيئة معيّنة.

<Connector>name-of-configured-extension</Connector>

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

العنصر <Input>

ملف JSON يحتوي على نص الطلب الذي سيتم إرساله إلى الإضافة.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

هذا هو في الأساس وسيط للإجراء الذي تحدّده باستخدام العنصر <Action>. ستختلف قيمة العنصر <Input> حسب الإضافة والإجراء الذي تستدعيه. يمكنك الاطّلاع على مستندات حزمة الإضافة للحصول على تفاصيل حول خصائص كل إجراء.

يُرجى العِلم أنّه على الرغم من أنّ العديد من قيم العنصر <Input> ستعمل بشكل صحيح بدون تضمينها كقسم <![CDATA[]]>، تسمح قواعد JSON بقيم لن يتم تحليلها كملف XML. من أفضل الممارسات تضمين JSON كقسم CDATA لتجنُّب أخطاء التحليل في وقت التشغيل.

قيمة العنصر <Input> هي JSON منسَّق بشكل جيد تحدّد خصائصه القيم التي سيتم إرسالها إلى إجراء الإضافة لتنفيذه. على سبيل المثال، يتضمّن الإجراء log في إضافة Google Cloud Logging Extension قيمًا تحدّد السجلّ الذي سيتمّ الكتابة إليه (logName)، والبيانات الوصفية التي سيتمّ تضمينها مع الإدخال (metadata)، ورسالة السجلّ (data). في ما يلي مثال:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

استخدام متغيّرات المسار في <Input> JSON

يتم التعامل مع محتوى <Input> على أنّه نموذج رسالة. وهذا يعني أنّه سيتم استبدال اسم المتغيّر المضمّن بين قوسين معقوفين في وقت التشغيل بقيمة المتغيّر المُشار إليه.

على سبيل المثال، يمكنك إعادة كتابة كتلة <Input> السابقة لاستخدام متغيّر التدفق client.ip للحصول على عنوان IP للعميل الذي يستدعي خادم وكيل واجهة برمجة التطبيقات:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

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

يتضمّن المثال التالي <Input> مرجعَين لمتغيّرات التدفق:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

عند وقت التشغيل، سيتم تحديد قيم سمات JSON على النحو التالي:

• قيمة السمة logName، وهي سلسلة حرفية example-log
• قيمة السمة metadata -- قيمة متغيّر التدفق my.log.entry.metadata بدون علامات الاقتباس المحيطة يمكن أن يكون ذلك مفيدًا إذا كانت قيمة المتغيّر هي نفسها JSON تمثّل عنصرًا.
• قيمة السمة message، أي قيمة متغيّر التدفق client.ip مع علامات الاقتباس المحيطة

عنصر <Output>

اسم متغيّر يخزّن استجابة إجراء الإضافة.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

أو

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

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

تكون عناصر استجابة الإضافة بتنسيق JSON. هناك خياران لكيفية تعامل السياسة مع JSON:

• تم التحليل (الإعداد التلقائي): تحلّل السياسة عنصر JSON وتنشئ تلقائيًا متغيرات تتضمّن بيانات JSON. على سبيل المثال، إذا كان JSON يحتوي على "messageId" : 12345; وسمّيت متغيّر الإخراج extensionOutput، يمكنك الوصول إلى معرّف الرسالة هذا في سياسات أخرى باستخدام المتغيّر {extensionOutput.messageId}.
• غير محلَّل: يحتوي متغيّر الإخراج على استجابة JSON غير محلَّلة وغير مُعالَجة من الإضافة. (إذا أردت ذلك، يمكنك مواصلة تحليل قيمة الاستجابة في خطوة منفصلة باستخدام سياسة JavaScript).

سمات <Output>

متغيّرات سير العمل

بلا عُري

رموز الخطأ

تتّبع الأخطاء التي يتم عرضها من سياسات Apigee Edge تنسيقًا متسقًا كما هو موضّح في مرجع أخطاء السياسات.

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

أخطاء وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.