سياسة ExtensionCallout

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

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

توفّر الإضافة إمكانية الوصول إلى مورد محدَّد خارجي عن Apigee Edge. قد يكون المورد هو خدمات Google Cloud Platform، مثل Cloud Storage أو تحويل الكلام إلى نص في السحابة الإلكترونية. ولكن يمكن أن يكون المورد أي مورد خارجي يمكن الوصول إليه عبر 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">

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

السمة الوصف تلقائي التواجد في المنزل
name

الاسم الداخلي للسياسة وقد تحتوي قيمة السمة name على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. لا يمكن أن تتجاوز هذه القيمة 255 حرفًا.

ويمكنك اختياريًا استخدام العنصر <DisplayName> لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف للغة طبيعية.

 لا ينطبق مطلوبة
continueOnError

اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ السياسة. وهو سلوك متوقّع لمعظم السياسات.

اضبط القيمة على true لمواصلة تنفيذ التدفق حتى بعد تعذُّر تنفيذ السياسة.

 false إجراء اختياري
enabled

اضبط القيمة على true لفرض السياسة.

اضبط القيمة على false من أجل إيقاف السياسة. ولن يتم فرض السياسة حتى إذا ظلت مرتبطة بمسار.

 صحيح إجراء اختياري
async

تم إيقاف هذه السمة نهائيًا.

 false منهي العمل به

العنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
تلقائي

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم استخدام قيمة السمة name الخاصة بالسياسة.
التواجد في المنزل إجراء اختياري
Type سلسلة

عنصر <Action>

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

<Action>action-exposed-by-extension</Action>
تلقائي لا ينطبق
التواجد في المنزل مطلوبة
Type سلسلة

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

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

عنصر <الموصل>

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

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

تلقائي لا ينطبق
التواجد في المنزل مطلوبة
Type سلسلة

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

عنصر <Input>

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

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

تلقائي لا ينطبق
التواجد في المنزل اختيارية أو مطلوبة حسب الإضافة.
Type سلسلة

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

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

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

تلقائي لا ينطبق
التواجد في المنزل اختيارية أو مطلوبة حسب الإضافة.
Type كائن أو سلسلة تم تحليلها، استنادًا إلى إعداد السمة parsed

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

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

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

<الإخراج> السمات

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

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

بلا عُري

رموز الخطأ

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

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

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

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

اسم الخطأ رموز حالة HTTP السبب
تعذّر التنفيذ. 500 تتفاعل الإضافة مع حدوث خطأ.

أخطاء النشر

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

اسم الخطأ يحدث في الحالات إصلاح
InvalidConnectorInstance العنصر <Connector> فارغ.
ConnectorInstanceDoesNotExists الإضافة التي تم تحديدها في العنصر <Connector> غير متوفّرة في البيئة المحيطة.
InvalidAction العنصر <Action> في السياسة Extension callout غير متوفّر أو تم ضبطه على قيمة فارغة.
AllowExtensionsInPostClientFlow لا يُسمح باستخدام سياسة Extension callout في مسار PostClient.