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

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

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

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

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

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

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

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

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

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

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

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

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

    على سبيل المثال، قد لا يتم تنفيذ سياسة إرجاع خطأ إلا عندما يكون متغير تدفق معين تعيين. أخيرًا، يمكنك الحصول على متغيرات التدفق وتعيينها في تطبيق استهداف 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 التي يتم تنفيذها من خلال هذه السياسة Apigee نموذج كائن JavaScript يتيح لك الوصول إلى الرمز المخصّص للوصول إلى عناصر الطلب والاستجابة والسياق المرتبطة مسار الخادم الوكيل لواجهة برمجة التطبيقات الذي يتم فيه تنفيذ الرمز على سبيل المثال، يحدد هذا الرمز عنوان الاستجابة بالقيمة التي يتم الحصول عليها من متغير التدفق 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 request رد TargetEndpoint وresponse ProxyEndpoint.

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

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

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

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

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

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

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

هناك متغيّر آخر مضمّن آخر يسمى 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، لأن نطاق متغير الاستجابة هو "target response".

متغيرات تدفق الإشارة

تتبع جميع المتغيّرات المضمّنة في 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 وJavaScript. يمكنك الاطّلاع على ما يلي للحصول على مزيد من المعلومات:

نوع بيانات متغيّرات التدفق

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

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

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

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

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

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

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

في المثال التالي، تحلِّل ميزة "استخراج المتغيّرات" رسالة ردّ وتخزِّن بيانات محدّدة. مأخوذة من الرد. تنشئ السياسة متغيّرَين مخصّصَين، 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) في التعليمات البرمجية. لمعرفة التفاصيل، يُرجى الاطّلاع على الوصول إلى متغيّرات التدفق في Node.js.

معلومات يجب تذكّرها

فيما يلي بعض الأشياء المهمة التي يجب تذكرها حول متغيرات التدفق:

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

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

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

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

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

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

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