سياسة ExtensionCallout

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

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

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

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

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

نماذج

يظهر أدناه مثال على سياسة للاستخدام مع إضافة تسجيل الدخول إلى السحابة الإلكترونية:

<?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 for Private Cloud، استخدِم واجهة برمجة التطبيقات تعديل خصائص المؤسسة لضبط علامة 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">

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

<DisplayName> عنصر

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

<DisplayName>Policy Display Name</DisplayName>

<Action> عنصر

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

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

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

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

<موصّل> عنصر

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

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

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

&lt;Input&gt; عنصر

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

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

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

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

قيمة العنصر <Input> بتنسيق JSON بشكل صحيح، وتحدِّد خصائصه القيم لإرسالها إلى إجراء الإضافة لاستدعاءها. على سبيل المثال، إضافة تسجيل الدخول إلى Google Cloud يتخذ الإجراء log للإضافة قيمًا تحدد السجل للكتابة إلى (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 مع علامات اقتباس مضمَّنة.

&lt;Output&gt; عنصر

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

<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).

&lt;Output&gt; السمات

متغيّرات التدفق

بلا عُري

رموز الخطأ

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

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

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

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

أخطاء النشر

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