استفاده از متغیرهای جریان

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

از نظر مفهومی، متغیرهای جریان ، اشیایی هستند که می‌توانید از درون خط‌مشی‌ها یا ابزارهای خود (مانند ابزار Trace ) به آنها دسترسی داشته باشید. آنها به شما اجازه می دهند وضعیت مرتبط با یک تراکنش API پردازش شده توسط Apigee Edge را حفظ کنید.

متغیرهای جریان چیست؟

متغیرهای جریان در متن یک جریان پروکسی API وجود دارند، و آنها وضعیت را در یک تراکنش API دنبال می کنند، همانطور که متغیرهای نامگذاری شده وضعیت را در یک برنامه نرم افزاری دنبال می کنند. متغیرهای جریان اطلاعاتی مانند:

  • آدرس IP، هدرها، مسیر URL و بار ارسال شده از برنامه درخواست کننده
  • اطلاعات سیستم مانند تاریخ و زمانی که Edge درخواستی را دریافت می کند
  • داده هایی که هنگام اجرای یک خط مشی به دست می آیند. به عنوان مثال پس از اجرای سیاستی که یک نشانه OAuth را تأیید می کند، Edge متغیرهای جریانی ایجاد می کند که اطلاعاتی مانند نام برنامه درخواست کننده را در خود نگه می دارد.
  • اطلاعات در مورد پاسخ از سیستم هدف

برخی از متغیرها در Edge "ساخت‌شده" هستند و هر زمان که درخواست API دریافت می‌شود به‌طور خودکار پر می‌شوند. آنها در سراسر یک تراکنش API در دسترس هستند. همچنین می توانید متغیرهای سفارشی خود را با استفاده از خط مشی هایی مانند AssignMessage Policy یا در JavaScript، Node.js و کد جاوا ایجاد کنید.

همانطور که خواهید دید، متغیرها دارای دامنه هستند و محل دسترسی آنها تا حدی به زمان ایجاد آنها در جریان پروکسی API بستگی دارد. به طور کلی، زمانی که یک متغیر ایجاد می‌شود، برای همه سیاست‌ها و کدهایی که بعداً در جریان تراکنش API اجرا می‌شوند، در دسترس است.

چگونه از متغیرهای جریان استفاده می شود؟

متغیر جریان در سیاست ها و جریان های مشروط استفاده می شود:

  • سیاست ها می توانند حالت را از متغیرهای جریان بازیابی کرده و از آنها برای انجام کار خود استفاده کنند.

    به عنوان مثال، یک خط مشی VerifyJWT می تواند توکن مورد تایید را از یک متغیر جریان بازیابی کند و سپس تایید را روی آن انجام دهد. به عنوان مثال دیگری، یک خط مشی جاوا اسکریپت می تواند متغیرهای جریان را بازیابی کند و داده های موجود در آن متغیرها را رمزگذاری کند.

  • جریان‌های شرطی می‌توانند به متغیرهای جریان اشاره کنند تا جریان یک API را از طریق 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>

برای مثال دیگر، زمانی که یک خط مشی Quota اجرا می شود، چندین متغیر جریان با مقادیر مرتبط با خط مشی پر می شوند. یکی از این متغیرها ratelimit.my-quota-policy.used.count نام دارد (که در آن my-quota-policy نام خط مشی سهمیه ای است که شما به آن علاقه دارید).

ممکن است بعداً یک جریان مشروط را اجرا کنید که می گوید "اگر تعداد سهمیه فعلی کمتر از 50٪ حداکثر است و بین ساعت 9 صبح تا 5 بعد از ظهر است، سهمیه دیگری را اعمال کنید." این شرایط ممکن است به مقدار تعداد سهمیه فعلی و یک متغیر جریان به نام system.time بستگی داشته باشد که یکی از متغیرهای Edge داخلی است.

متغیرهای جریان در جریان های شرطی

جریان های شرطی متغیرهای جریان را ارزیابی می کنند و پراکسی ها را قادر می سازند تا به صورت پویا رفتار کنند. شرایط معمولاً برای تغییر رفتار جریان ها، مراحل و قوانین مسیر استفاده می شود.

در اینجا یک جریان شرطی وجود دارد که مقدار متغیر request.verb را در یک مرحله جریان پروکسی ارزیابی می کند. در این حالت، اگر فعل درخواست POST باشد، سیاست VerifyAPIKey اجرا می شود. این یک الگوی رایج است که در تنظیمات پروکسی API استفاده می شود.

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

اکنون، ممکن است تعجب کنید، متغیرهایی مانند request.verb ، client.ip و system.time از کجا می آیند؟ چه زمانی آنها نمونه سازی می شوند و با یک مقدار پر می شوند؟ برای اینکه بفهمید متغیرها چه زمانی ایجاد می شوند و چه زمانی در دسترس شما هستند، به درک محدوده متغیر جریان مراجعه کنید.

متغیرهای جریان در کد جاوا اسکریپت با خط مشی جاوا اسکریپت فراخوانی می شوند

با خط‌مشی جاوا اسکریپت ، می‌توانید کد جاوا اسکریپت را از داخل یک جریان پروکسی API اجرا کنید. جاوا اسکریپتی که توسط این خط‌مشی اجرا می‌شود از مدل شی جاوا اسکریپت Apigee استفاده می‌کند که دسترسی کد سفارشی شما را به درخواست، پاسخ و اشیاء زمینه مرتبط با جریان پروکسی API که کد شما در آن اجرا می‌شود، فراهم می‌کند. به عنوان مثال، این کد یک هدر پاسخ را با مقدار بدست آمده از متغیر جریان target.name تنظیم می کند.

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

این تکنیک استفاده از جاوا اسکریپت برای خواندن و تنظیم متغیرها مشابه کاری است که می توانید با خط مشی AssignMessage انجام دهید (نشان داده شده در قبل). این فقط راه دیگری برای انجام کارهای مشابه در Edge است. نکته کلیدی که باید به خاطر بسپارید این است که جاوا اسکریپت اجرا شده توسط خط مشی جاوا اسکریپت به تمام متغیرهای جریان موجود و در محدوده جریان پروکسی API دسترسی دارد.

متغیرهای جریان در کد 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 اطلاعات بیشتری کسب کنید.

درک محدوده متغیر جریان

دامنه متغیر مربوط به جریان یا کلی "چرخه عمر" فراخوانی پروکسی API است.

تجسم جریان یک پروکسی API

برای درک محدوده متغیر جریان، درک یا تجسم نحوه جریان پیام ها از طریق یک پروکسی API مهم است. یک پروکسی API شامل یک سری مراحل پردازش پیام است که به صورت یک جریان سازماندهی شده اند. در هر مرحله از جریان پروکسی، پروکسی اطلاعات موجود را ارزیابی می کند و تصمیم می گیرد که چه کاری انجام دهد. در طول مسیر، پروکسی ممکن است کد خط مشی را اجرا کند یا انشعاب شرطی را انجام دهد.

شکل زیر این توالی جریان ها را نشان می دهد. توجه داشته باشید که چگونه جریان ها از چهار بخش اصلی تشکیل شده اند: درخواست ProxyEndpoint، درخواست TargetEndpoint، پاسخ TargetEndpoint، و پاسخ ProxyEndpoint.

این ساختار جریان را در ذهن داشته باشید، همانطور که ما شروع به بررسی متغیرهای جریان از طریق بقیه این مبحث می کنیم.

چگونه دامنه متغیر با جریان پروکسی مرتبط است

همانطور که قبلاً توضیح داده شد، به محض اینکه بتوانید نحوه جریان پیام ها از طریق یک پروکسی را تجسم کنید، می توانید دامنه متغیر را درک کنید. منظور ما از محدوده، نقطه ای در چرخه حیات جریان پروکسی است که یک متغیر برای اولین بار نمونه سازی می شود.

به عنوان مثال، اگر یک خط مشی متصل به بخش درخواست ProxyEndpoint داشته باشید، آن خط مشی قادر به دسترسی به متغیرهایی که در محدوده بخش درخواست TargetEndpoint هستند، نخواهد بود. دلیل این امر این است که بخش درخواست TargetEndpoint جریان هنوز اجرا نشده است، بنابراین پروکسی API فرصتی برای پر کردن متغیرها در آن محدوده نداشته است.

جدول زیر مجموعه کاملی از دامنه‌های متغیر را فهرست می‌کند و نشان می‌دهد که چه زمانی در جریان پروکسی در دسترس هستند.

دامنه متغیر جایی که این متغیرها پر شده اند
درخواست پروکسی بخش درخواست ProxyEndpoint
درخواست هدف بخش درخواست TargetEndpoint
پاسخ هدف بخش پاسخ TargetEndpoint
پاسخ پروکسی بخش پاسخ ProxyEndpoint
همیشه در دسترس به محض اینکه پروکسی درخواستی را دریافت کرد. این متغیرها در کل چرخه حیات جریان پروکسی در دسترس هستند.

برای مثال، یک متغیر Edge داخلی به نام client.ip وجود دارد. این متغیر دارای دامنه "درخواست پروکسی" است. به طور خودکار با آدرس IP مشتری که پروکسی را فراخوانی کرده است پر می شود. هنگامی که یک درخواست برای اولین بار به ProxyEndpoint می رسد پر می شود و در طول کل چرخه حیات جریان پروکسی در دسترس باقی می ماند.

متغیر داخلی دیگری به نام target.url وجود دارد. دامنه این متغیر "درخواست هدف" است. در بخش درخواست TargetEndpoint با URL درخواست ارسال شده به هدف Back-end پر شده است. اگر سعی کنید به 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>

همچنین می توانید به متغیرهای جریان در جاوا اسکریپت و کد جاوا ارجاع دهید. برای اطلاعات بیشتر رجوع کنید به:

نوع داده متغیرهای جریان

هر ویژگی از متغیر جریان دارای یک نوع داده کاملاً تعریف شده است، مانند String، Long، Integer، Boolean یا Collection. می توانید انواع داده های فهرست شده در مرجع متغیرهای جریان را بیابید. برای متغیرهایی که توسط یک خط مشی ایجاد شده اند، برای اطلاعات نوع داده به موضوع مرجع خط مشی خاص مراجعه کنید.

متغیرهایی که به صورت دستی ایجاد می کنید، نوع داده شده در زمان ایجاد را فرض می کنند و به انواع مقادیر مجاز بستگی دارند. به عنوان مثال، متغیرهای ایجاد شده در کد Node.js به Number، String، Boolean، null یا تعریف نشده محدود می شوند.

استفاده از متغیرهای جریان در سیاست ها

بسیاری از سیاست ها متغیرهای جریان را به عنوان بخشی از اجرای عادی خود ایجاد می کنند. مرجع Policy همه این متغیرهای خاص سیاست را مستند می کند.

همانطور که با پراکسی ها و خط مشی ها کار می کنید، حتماً با مرجع خط مشی مشورت کنید تا بفهمید کدام متغیرها ایجاد شده اند و برای چه مواردی استفاده می شوند. به عنوان مثال، خط مشی Quota مجموعه ای از متغیرها را ایجاد می کند که حاوی اطلاعاتی در مورد تعداد و محدودیت های سهمیه، زمان انقضا و غیره است.

برخی از متغیرهای خط مشی برای اشکال زدایی مفید هستند. برای مثال می‌توانید از ابزار Trace tool استفاده کنید تا ببینید کدام متغیرها در یک نمونه خاص در یک جریان پروکسی تنظیم شده‌اند.

خط مشی ExtractVariables به شما امکان می دهد متغیرهای سفارشی را با داده های استخراج شده از پیام ها پر کنید. می توانید پارامترهای پرس و جو، سرصفحه ها و سایر داده ها را استخراج کنید. به عنوان مثال، می توانید پیام های درخواست و پاسخ را با استفاده از الگوها برای استخراج داده های خاص از پیام ها تجزیه کنید.

در مثال زیر، Extract Variables یک پیام پاسخ را تجزیه می کند و داده های خاص گرفته شده از پاسخ را ذخیره می کند. این خط مشی دو متغیر سفارشی 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>

باز هم، توجه داشته باشید که بسیاری از سیاست ها به طور خودکار متغیرها را ایجاد می کنند. شما می توانید به آن متغیرها در زمینه جریان پروکسی دسترسی داشته باشید، و آنها در مرجع خط مشی تحت هر موضوع خط مشی جداگانه مستند شده اند.

کار با متغیرهای جریان در کد جاوا اسکریپت

می‌توانید مستقیماً در کد جاوا اسکریپت که در متن یک پراکسی API اجرا می‌شود، به متغیرها دسترسی داشته باشید و آن‌ها را تنظیم کنید. از طریق مدل شی جاوا اسکریپت Apigee، اجرای جاوا اسکریپت در Edge دسترسی مستقیم به متغیرهای جریان پروکسی دارد.

برای دسترسی به متغیرها در کد جاوا اسکریپت، متدهای getter/setter را روی هر یک از این اشیاء فراخوانی کنید:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

همانطور که می بینید، این ارجاعات شیء به بخش های آشنای مدل جریان پروکسی نگاشت می شوند، همانطور که قبلاً در تجسم جریان یک پروکسی API توضیح داده شد.

شی context مربوط به متغیرهای در دسترس "کلی" است، مانند متغیرهای سیستم. به عنوان مثال، می توانید getVariable() در شیء context فراخوانی کنید تا سال جاری را بدست آورید:

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

به طور مشابه، می توانید setVariable() برای تنظیم مقدار یک متغیر سفارشی یا برای هر متغیر خارج از جعبه قابل نوشتن فراخوانی کنید. در اینجا، یک متغیر سفارشی به نام organization.name.myorg ایجاد می کنیم و یک مقدار به آن اختصاص می دهیم.

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

از آنجایی که این متغیر با شی context ایجاد می شود، برای همه بخش های جریان در دسترس خواهد بود (در اصل، این مانند ایجاد یک متغیر سراسری است).

همچنین می توانید متغیرهای جریان پروکسی را در کد جاوا که با خط مشی JavaCallout اجرا می کنید، دریافت/تنظیم کنید.

دسترسی به متغیرهای جریان در برنامه های Node.js

می توانید متغیرهای جریان را از کد Node.js که در Edge مستقر شده است دریافت، تنظیم و حذف کنید. تنها کاری که باید انجام دهید این است که ماژول apigee-access را در کد خود "نیاز" کنید. برای جزئیات، دسترسی به متغیرهای جریان در Node.js را ببینید.

آنچه باید به خاطر بسپارید

در اینجا چند نکته مهم در مورد متغیرهای جریان وجود دارد:

  • برخی از متغیرهای "خارج از جعبه" به طور خودکار توسط خود پراکسی نمونه سازی و تکمیل می شوند. اینها در مرجع متغیرهای جریان مستند شده اند.
  • می توانید متغیرهای سفارشی ایجاد کنید که برای استفاده در جریان پروکسی در دسترس هستند. ایجاد متغیرها با استفاده از خط مشی هایی مانند خط مشی AssignMessage و خط مشی جاوا اسکریپت و در کد Node.js امکان پذیر است.
  • متغیرها دامنه دارند. به عنوان مثال، زمانی که اولین پروکسی درخواستی از یک برنامه دریافت می کند، برخی از متغیرها به طور خودکار پر می شوند. سایر متغیرها در بخش جریان پاسخ پراکسی پر می شوند. این متغیرهای پاسخ تا زمانی که بخش پاسخ اجرا نشود، تعریف نشده باقی می مانند.
  • وقتی خط‌مشی‌ها اجرا می‌شوند، می‌توانند متغیرهای خاص سیاست را ایجاد و پر کنند. اسناد مربوط به هر خط مشی همه این متغیرهای مربوط به خط مشی خاص را فهرست می کند.
  • جریان های شرطی معمولاً یک یا چند متغیر را ارزیابی می کنند. اگر می خواهید جریان های شرطی ایجاد کنید، باید متغیرها را درک کنید.
  • بسیاری از سیاست ها از متغیرها به عنوان ورودی یا خروجی استفاده می کنند. شاید متغیری که توسط یک خط مشی ایجاد می شود، بعداً توسط دیگری استفاده شود.
  • می‌توانید با استفاده از جاوا اسکریپت مستقیم (و مدل شی جاوا اسکریپت ما) یا سیاست JavaCallout که کد را روی Edge اجرا می‌کند، متغیرهای جریان زیادی را از داخل Node.js دریافت و تنظیم کنید.

نمونه کدهای مرتبط

نمونه های پروکسی API در GitHub هستند و دانلود و استفاده از آنها آسان است. برای اطلاعات در مورد دانلود و استفاده از نمونه ها به استفاده از نمونه پراکسی های API مراجعه کنید. برای توضیح نمونه‌های پراکسی API و کارهایی که انجام می‌دهند، به فهرست نمونه‌ها مراجعه کنید.

پراکسی های نمونه ای که دارای استفاده از متغیرها و پردازش متغیر هستند عبارتند از:

  • متغیرها - نحوه استخراج و تنظیم متغیرها را بر اساس محتوای پیام JSON و XML نشان می دهد.
  • Policy-mashup-cookbook - یک برنامه کامل که از ترکیب خط مشی برای فراخوانی دو API عمومی استفاده می کند، نتایج را ترکیب می کند و یک پاسخ غنی برای برنامه مشتری ایجاد می کند. برای اطلاعات بیشتر در مورد این نمونه، به استفاده از ترکیب خط مشی مراجعه کنید.
  • شرطی-سیاست - اجرای سیاست مشروط ساده بر اساس مقادیر متغیر را اجرا می کند.

موضوعات مرتبط

  • همه متغیرهایی که به طور خودکار در یک پراکسی API پر می شوند در مرجع متغیرهای جریان فهرست شده اند. مرجع همچنین نوع و دامنه هر متغیر را فهرست می کند.
  • اگر می‌خواهید بدانید که یک خط‌مشی خاص چه متغیرهایی را پر می‌کند، به مبحث مرجع خط‌مشی مراجعه کنید. به عنوان مثال، متغیرهای جریان را در مرجع خط مشی Quota ببینید.