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

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

من الناحية المفاهيمية، متغيرات التدفق هي عناصر يمكنك الوصول إليها من داخل سياساتك أو أدواتك المساعدة (مثل أداة أداة التتبُّع). تتيح لك هذه السياسات الحفاظ على الحالة المرتبطة بمعاملة واجهة برمجة التطبيقات التي تتم معالجتها من خلال Apigee Edge.

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

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

  • عنوان IP والعناوين ومسار عنوان URL والحِمل النافع الذي تم إرساله من التطبيق الذي يقدّم الطلب
  • معلومات النظام، مثل التاريخ والوقت اللذين يتلقّى فيهما Edge طلبًا
  • البيانات المستمدّة عند تنفيذ إحدى السياسات على سبيل المثال، بعد تنفيذ سياسة تتحقّق من صحة رمز OAuth المميّز، ينشئ Edge متغيّرات سير العمل التي تتضمّن معلومات مثل اسم التطبيق الذي يرسل الطلب.
  • معلومات عن الردّ من النظام المستهدَف

بعض المتغيّرات "مضمّنة" في Edge ويتم تعبئتها تلقائيًا كلما تم تلقّي طلب بيانات من واجهة برمجة التطبيقات. وهي متاحة طوال مدة معاملة واجهة برمجة التطبيقات. يمكنك أيضًا إنشاء متغيّرات مخصّصة باستخدام سياسات مثل AssignMessage policy، أو في رمز JavaScript وNode.js وJava.

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

كيف يتم استخدام متغيّرات المسار؟

يتم استخدام متغيّرات التدفق في السياسات وعمليات التدفق الشرطية:

  • يمكن للسياسات استرداد الحالة من متغيرات التدفق واستخدامها لتنفيذ عملها.

    على سبيل المثال، يمكن أن تسترد سياسة VerifyJWT الرمز المميّز المطلوب التحقّق منه من متغيّر في التدفق، ثم تجري عملية التحقّق منه. كمثال آخر، يمكن لسياسة JavaScript استرداد متغيّرات التدفق وتشفير البيانات الواردة في تلك المتغيّرات.

  • يمكن أن تشير التدفقات الشرطية إلى متغيرات التدفق لتوجيه تدفق واجهة برمجة التطبيقات من خلال Edge، على غرار طريقة عمل عبارة switch في البرمجة.

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

لنلقِ نظرة على أمثلة حول كيفية استخدام المتغيّرات في كل سياق من هذه السياقات.

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

تتلقّى بعض السياسات متغيرات التدفق كمدخلات.

على سبيل المثال، تأخذ سياسة AssignMessage التالية قيمة متغيّر التدفق client.ip وتضعها في عنوان طلب يُسمى My-Client-IP. في حال إضافتها إلى مسار الطلب، تضبط هذه السياسة عنوانًا يتم تمريره إلى الخلفية المستهدَفة. في حال ضبطها على مسار الاستجابة، يتم إرسال العنوان إلى تطبيق العميل.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

في مثال آخر، عند تنفيذ سياسة الحصة، يتم ملء العديد من متغيرات التدفق بقيم ذات صلة بالسياسة. أحد هذه المتغيرات يُسمى ratelimit.my-quota-policy.used.count (حيث my-quota-policy هو اسم سياسة الحصة التي تهمّك).

يمكنك لاحقًا تنفيذ سير عمل شرطي ينص على أنّه "إذا كان عدد الحصص الحالية أقل من% 50 من الحد الأقصى، وكان الوقت بين الساعة 9 صباحًا و5 مساءً، يتم فرض حصة مختلفة". قد يعتمد هذا الشرط على قيمة عدد الحصص الحالية وعلى متغير تدفق يُسمى system.time، وهو أحد متغيرات Edge المضمّنة.

متغيرات سير العمل في المسارات المشروطة

تُقيّم عمليات سير العمل الشرطية متغيرات سير العمل وتتيح للوكلاء التصرّف بشكل ديناميكي. تُستخدَم الشروط عادةً لتغيير سلوك عمليات التدفق والخطوات وقواعد التوجيه.

في ما يلي سير عمل شرطي يقيّم قيمة المتغيّر request.verb في خطوة سير عمل وكيل. في هذه الحالة، إذا كان فعل الطلب هو POST، يتم تنفيذ سياسة VerifyAPIKey. هذا نمط شائع الاستخدام في إعدادات خادم وكيل لواجهة برمجة التطبيقات.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

قد تتساءل الآن عن مصدر المتغيرات، مثل request.verb وclient.ip وsystem.time. متى يتم إنشاء هذه المتغيرات وتعبئتها بقيمة؟ لمساعدتك في فهم وقت إنشاء المتغيرات ووقت توفّرها لك، راجِع فهم نطاق متغيرات التدفق.

متغيّرات التدفق في رمز JavaScript الذي يتم استدعاؤه باستخدام سياسة JavaScript

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

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

تشبه هذه الطريقة في استخدام JavaScript لقراءة المتغيّرات وضبطها العمل الذي يمكنك تنفيذه باستخدام سياسة AssignMessage (الموضّحة سابقًا). إنّها مجرد طريقة أخرى لإنجاز أنواع المهام نفسها على Edge. النقطة الأساسية التي يجب تذكُّرها هي أنّ رمز JavaScript الذي يتم تنفيذه بموجب سياسة JavaScript يمكنه الوصول إلى جميع متغيرات التدفق المتوفّرة والتي تقع ضمن النطاق في تدفق خادم وكيل واجهة برمجة التطبيقات.

متغيّرات التدفق في رمز Node.js

من خلال طلب وحدة apigee-access، يمكنك ضبط متغيرات التدفق والوصول إليها من داخل رمز Node.js الذي يتم نشره على Edge.

في ما يلي مثال بسيط يتم فيه ضبط قيمة المتغير custom.foo على Bar. بعد ضبط هذا المتغيّر الجديد، يصبح متاحًا لأي سياسات أو تعليمات برمجية أخرى تحدث في مسار الخادم الوكيل بعد تنفيذ تعليمات Node.js البرمجية.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

يمكنك الاطّلاع على مزيد من المعلومات حول استخدام apigee-access للتعامل مع المتغيّرات في الوصول إلى متغيّرات التدفق في Node.js.

فهم نطاق متغيّر التدفق

يرتبط نطاق المتغيّر بسير العمل أو "دورة الحياة" الإجمالية لطلب بيانات من خادم وكيل لواجهة برمجة التطبيقات.

تصوُّر مسار خادم وكيل لواجهة برمجة التطبيقات

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

يوضّح الشكل التالي تسلسل عمليات سير العمل هذا. لاحظ كيف تتألف التدفقات من أربعة أقسام رئيسية: طلب ProxyEndpoint وطلب TargetEndpoint وردّ TargetEndpoint وردّ ProxyEndpoint.

ضَع بنية المسار هذه في اعتبارك بينما نبدأ في استكشاف متغيرات المسار خلال بقية هذا الموضوع.

كيفية ارتباط نطاق المتغيّر بتدفّق الخادم الوكيل

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

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

يسرد الجدول التالي المجموعة الكاملة لنطاقات المتغيّرات ويشير إلى وقت توفّرها في مسار الخادم الوكيل.

نطاق المتغير أماكن تعبئة هذه المتغيّرات
طلب الخادم الوكيل مقطع طلب ProxyEndpoint
الطلب المستهدَف قسم طلب TargetEndpoint
الردّ المستهدَف مقطع استجابة TargetEndpoint
ردّ الخادم الوكيل مقطع استجابة ProxyEndpoint
متوفّر دائمًا فور تلقّي الخادم الوكيل طلبًا تتوفّر هذه المتغيّرات خلال دورة حياة تدفق الخادم الوكيل بأكملها.

على سبيل المثال، هناك متغيّر مضمّن في Edge يُسمى client.ip. يحتوي هذا المتغيّر على نطاق "طلب وكيل". تتم تعبئته تلقائيًا بعنوان IP الخاص بالعميل الذي استدعى الخادم الوكيل. يتم ملء هذا الحقل عندما يصل الطلب لأول مرة إلى ProxyEndpoint ويظل متاحًا طوال دورة حياة مسار الخادم الوكيل بأكمله.

هناك متغيّر غير قابل للتخصيص آخر يُسمّى target.url. نطاق هذه السمة هو "طلب الاستهداف". يتم ملء هذا الحقل في قسم طلب TargetEndpoint باستخدام عنوان URL للطلب الذي تم إرساله إلى نظام الخلفية المستهدف. إذا حاولت الوصول إلى target.url في مقطع طلب ProxyEndpoint، ستتلقّى القيمة NULL. إذا حاولت ضبط هذا المتغيّر قبل أن يكون ضمن النطاق، لن يفعل الخادم الوكيل أي شيء، أي لن يعرض خطأ ولن يضبط المتغيّر.

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

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

تنسخ هذه السياسة ببساطة العنصر request وتعيّنه إلى العنصر response. ولكن أين يجب وضع هذه السياسة في مسار الخادم الوكيل؟ والإجابة هي أنّه يجب وضعه في ردّ TargetEndpoint، لأنّ نطاق متغير الردّ هو "ردّ الهدف".

الإشارة إلى متغيّرات سير العمل

تتّبع جميع المتغيّرات المضمّنة في Apigee Edge اصطلاح تسمية بنقطة. يسهّل هذا الاصطلاح تحديد الغرض من المتغير. على سبيل المثال، system.time.hour وrequest.content.

تحتفظ Apigee ببادئات مختلفة لتنظيم المتغيرات ذات الصلة بشكل مناسب. تشمل هذه البادئات ما يلي:

  • request
  • response
  • system
  • target

للإشارة إلى متغيّر في إحدى السياسات، ضَع المتغيّر بين قوسَين معقوفَين. على سبيل المثال، تأخذ سياسة AssignMessage التالية قيمة المتغيّر client.ip وتضعها في عنوان طلب يُسمى Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

في المسارات الشرطية، لا يلزم استخدام الأقواس المتعرّجة. يقيّم شرط المثال التالي المتغير request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

يمكنك أيضًا الرجوع إلى متغيّرات التدفق في رموز JavaScript وJava البرمجية. يمكنك الاطّلاع على ما يلي للحصول على مزيد من المعلومات:

نوع بيانات متغيّرات سير العمل

لكل سمة من سمات متغيّر التدفق نوع بيانات محدّد جيدًا، مثل "سلسلة" أو "عدد صحيح طويل" أو "عدد صحيح" أو "قيمة منطقية" أو "مجموعة". يمكنك الاطّلاع على أنواع البيانات المُدرَجة في مرجع متغيرات سير العمل. بالنسبة إلى المتغيرات التي تم إنشاؤها بواسطة سياسة، يُرجى الرجوع إلى موضوع مرجع السياسة المحدّد للحصول على معلومات حول نوع البيانات.

تتخذ المتغيرات التي تنشئها يدويًا النوع المحدّد عند إنشائها، وتعتمد على أنواع القيم المسموح بها. على سبيل المثال، تقتصر المتغيرات التي تم إنشاؤها في رمز Node.js على Number أو String أو Boolean أو null أو undefined.

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

تنشئ العديد من السياسات متغيرات تدفق كجزء من تنفيذها العادي. تتضمّن مستندات مرجع السياسة جميع المتغيّرات الخاصة بالسياسة.

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

بعض متغيّرات السياسة مفيدة لتصحيح الأخطاء. يمكنك استخدام أداة التتبُّع، مثلاً، لمعرفة المتغيّرات التي تم ضبطها في مثيل معيّن في مسار وكيل.

تتيح لك سياسة ExtractVariables ملء المتغيرات المخصّصة بالبيانات المستخرَجة من الرسائل. يمكنك استخراج مَعلمات طلب البحث والعناوين وغيرها من البيانات. على سبيل المثال، يمكنك تحليل رسائل الطلبات والاستجابات باستخدام أنماط لاستخراج بيانات معيّنة من الرسائل.

في المثال التالي، تحلّل سياسة "استخراج المتغيّرات" رسالة استجابة وتخزّن بيانات محدّدة مأخوذة من الاستجابة. تنشئ السياسة متغيّرَين مخصّصَين، geocoderesponse.latitude وgeocoderesponse.longitude، وتعيّن لهما قيمًا.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

يُرجى العِلم أيضًا أنّ العديد من السياسات تنشئ متغيرات تلقائيًا. يمكنك الوصول إلى هذه المتغيّرات ضمن سياق تدفّق الخادم الوكيل، وهي موضّحة في مرجع السياسة ضمن كل موضوع من مواضيع السياسة.

التعامل مع متغيرات التدفق في رمز JavaScript

يمكنك الوصول إلى المتغيرات وضبطها مباشرةً في رمز JavaScript الذي يتم تنفيذه في سياق خادم وكيل لواجهة برمجة التطبيقات. من خلال نموذج عنصر JavaScript في Apigee، يمكن للغة JavaScript التي يتم تنفيذها على Edge الوصول مباشرةً إلى متغيّرات تدفق الخادم الوكيل.

للوصول إلى المتغيّرات في رمز JavaScript، استدعِ طرق getter/setter على أيّ من هذه العناصر:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

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

يتوافق الكائن context مع المتغيرات المتاحة "على مستوى العالم"، مثل متغيرات النظام. على سبيل المثال، يمكنك طلب getVariable() من العنصر context للحصول على السنة الحالية:

var year = context.getVariable('system.time.year');

وبالمثل، يمكنك طلب setVariable() لضبط قيمة متغيّر مخصّص أو أي متغيّرات قابلة للكتابة جاهزة للاستخدام. في هذا المثال، ننشئ متغيّرًا مخصّصًا باسم organization.name.myorg ونُعيّن له قيمة.

var org = context.setVariable('organization.name.myorg', value);

بما أنّ هذا المتغيّر تم إنشاؤه باستخدام العنصر context، سيكون متاحًا لجميع أقسام المسار (وهذا يشبه إلى حد كبير إنشاء متغيّر عام).

يمكنك أيضًا الحصول على متغيّرات تدفق الخادم الوكيل أو ضبطها في رمز Java الذي تنفّذه باستخدام سياسة JavaCallout.

الوصول إلى متغيّرات التدفق في تطبيقات Node.js

يمكنك الحصول على متغيرات التدفق وضبطها وحذفها من رمز Node.js الذي تم نشره على Edge. كل ما عليك فعله هو "طلب" وحدة apigee-access في الرمز البرمجي. لمزيد من التفاصيل، يُرجى الاطّلاع على الوصول إلى متغيرات التدفق في Node.js.

ما يجب تذكُّره

في ما يلي بعض النقاط المهمة التي يجب تذكّرها بشأن متغيرات التدفق:

  • يتم إنشاء بعض المتغيرات "الجاهزة للاستخدام" وتعبئتها تلقائيًا بواسطة الخادم الوكيل نفسه. يتم توثيق هذه المتغيّرات في مرجع متغيّرات التدفق.
  • يمكنك إنشاء متغيّرات مخصّصة متاحة للاستخدام في عملية الربط. يمكنك إنشاء متغيّرات باستخدام سياسات مثل AssignMessage policy وJavaScript policy، وفي رمز Node.js.
  • للمتغيرات نطاق. على سبيل المثال، يتم ملء بعض المتغيرات تلقائيًا عندما يتلقّى الوكيل الأول طلبًا من أحد التطبيقات، بينما يتم ملء متغيرات أخرى في قسم تدفق الردود الخاص بالوكيل. تبقى متغيرات الرد هذه غير محدّدة إلى أن يتم تنفيذ جزء الرد.
  • عند تنفيذ السياسات، يمكنها إنشاء متغيرات خاصة بالسياسات وتعبئتها. تسرد المستندات الخاصة بكل سياسة جميع المتغيرات ذات الصلة الخاصة بالسياسة.
  • تُقيّم التدفقات الشرطية عادةً متغيّرًا واحدًا أو أكثر. عليك فهم المتغيرات إذا أردت إنشاء مسارات مشروطة.
  • تستخدم العديد من السياسات متغيرات كمدخلات أو مخرجات. ربما يتم استخدام متغيّر تم إنشاؤه بواسطة إحدى السياسات لاحقًا بواسطة سياسة أخرى.
  • يمكنك الحصول على العديد من متغيّرات التدفق وضبطها من داخل Node.js باستخدام JavaScript مباشرةً (ونموذج عناصر JavaScript) أو سياسة JavaCallout التي تنفّذ الرمز على Edge.

عيّنات التعليمات البرمجية ذات الصلة

تتوفّر نماذج لخادم وكيل لواجهة برمجة التطبيقات على GitHub، ويمكن تنزيلها واستخدامها بسهولة. راجِع استخدام نماذج خوادم وكيل لواجهة برمجة التطبيقات للحصول على معلومات حول تنزيل النماذج واستخدامها. راجِع قائمة الأمثلة للاطّلاع على وصف لأمثلة خادم وكيل API ووظائفها.

تشمل نماذج الخوادم الوكيلة التي تتضمّن استخدام المتغيّرات ومعالجتها ما يلي:

  • المتغيرات - يوضّح كيفية استخراج المتغيرات وضبطها استنادًا إلى محتوى الرسائل بتنسيق JSON وXML والنقل.
  • policy-mashup-cookbook: هو تطبيق كامل يستخدم تركيبة السياسات لاستدعاء واجهتَي برمجة تطبيقات عامتَين، ويدمج النتائج، وينشئ ردًا محسّنًا لتطبيق العميل. لمزيد من المعلومات حول هذا النموذج، يُرجى الاطّلاع على استخدام تركيبة السياسات.
  • ‫conditional-policy - تنفّذ هذه السمة فرض سياسة مشروطة بسيطة استنادًا إلى قيم المتغيرات.

مواضيع ذات صلة

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