شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات
از نظر مفهومی، متغیرهای جریان ، اشیایی هستند که میتوانید از درون سیاستها یا ابزارهای خود (مانند ابزار Trace tool ) به آنها دسترسی داشته باشید. آنها به شما امکان میدهند وضعیت مرتبط با یک تراکنش API پردازش شده توسط Apigee Edge را حفظ کنید.
متغیرهای جریان چیستند؟
متغیرهای جریان در چارچوب یک جریان پروکسی API وجود دارند و وضعیت را در یک تراکنش API ردیابی میکنند، همانطور که متغیرهای نامگذاری شده وضعیت را در یک برنامه نرمافزاری ردیابی میکنند. متغیرهای جریان اطلاعاتی مانند موارد زیر را ذخیره میکنند:
- آدرس IP، هدرها، مسیر URL و محتوای ارسالی از برنامه درخواستکننده
- اطلاعات سیستم مانند تاریخ و زمانی که Edge درخواستی را دریافت میکند
- دادههایی که هنگام اجرای یک سیاست به دست میآیند. برای مثال، پس از اجرای یک سیاست که یک توکن OAuth را اعتبارسنجی میکند، Edge متغیرهای جریانی ایجاد میکند که اطلاعاتی مانند نام برنامه درخواستکننده را در خود نگه میدارند.
- اطلاعات مربوط به پاسخ از سیستم هدف
برخی از متغیرها به صورت «توکار» در Edge وجود دارند و هر زمان که یک درخواست API دریافت شود، به طور خودکار پر میشوند. آنها در طول یک تراکنش API در دسترس هستند. همچنین میتوانید متغیرهای سفارشی خود را با استفاده از سیاستهایی مانند سیاست AssignMessage یا در جاوا اسکریپت، Node.js و کد جاوا ایجاد کنید.
همانطور که خواهید دید، متغیرها دارای دامنه هستند و محل دسترسی به آنها تا حدودی به زمان ایجاد آنها در جریان پروکسی API بستگی دارد. به طور کلی، وقتی یک متغیر ایجاد میشود، برای همه سیاستها و کدهایی که بعداً در جریان تراکنش API اجرا میشوند، در دسترس است.
متغیرهای جریان چگونه استفاده میشوند؟
متغیرهای جریان در سیاستها و جریانهای شرطی استفاده میشوند:
- سیاستها میتوانند وضعیت را از متغیرهای جریان بازیابی کرده و از آنها برای انجام کار خود استفاده کنند.
برای مثال، یک سیاست VerifyJWT میتواند توکنی را که باید تأیید شود از یک متغیر جریان بازیابی کند و سپس تأیید را روی آن انجام دهد. به عنوان مثالی دیگر، یک سیاست جاوا اسکریپت میتواند متغیرهای جریان را بازیابی کرده و دادههای موجود در آن متغیرها را رمزگذاری کند.
- جریانهای شرطی میتوانند به متغیرهای جریان ارجاع دهند تا جریان یک API را از طریق Edge هدایت کنند، چیزی شبیه به نحوه عملکرد دستور switch در برنامهنویسی.
برای مثال، یک سیاست برای بازگرداندن یک خطا ممکن است فقط زمانی اجرا شود که یک متغیر جریان خاص تنظیم شده باشد. در نهایت، میتوانید متغیرهای جریان را در یک برنامه هدف Node.js دریافت و تنظیم کنید.
بیایید به نمونههایی از نحوه استفاده از متغیرها در هر یک از این زمینهها نگاهی بیندازیم.
متغیرهای جریان در سیاستها
برخی از سیاستها متغیرهای جریان را به عنوان ورودی میگیرند.
برای مثال، سیاست AssignMessage زیر مقدار متغیر جریان client.ip را میگیرد و آن را در یک هدر درخواست به نام My-Client-IP قرار میدهد. اگر این سیاست به جریان درخواست اضافه شود، یک هدر تنظیم میکند که به هدف backend ارسال میشود. اگر روی جریان پاسخ تنظیم شود، هدر به برنامه کلاینت ارسال میشود.
<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 نام سیاست سهمیهبندی مورد نظر شماست).
ممکن است بعداً یک جریان شرطی اجرا کنید که میگوید «اگر تعداد سهمیه فعلی کمتر از ۵۰٪ حداکثر باشد و بین ساعت ۹ صبح تا ۵ بعد از ظهر باشد، سهمیه متفاوتی اعمال شود.» این شرط ممکن است به مقدار تعداد سهمیه فعلی و یک متغیر جریان به نام 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.

این ساختار جریان را در ذهن داشته باشید تا بتوانیم متغیرهای جریان را در ادامهی این مبحث بررسی کنیم.
چگونه دامنه متغیر با جریان پروکسی مرتبط است
به محض اینکه بتوانید نحوهی جریان پیامها از طریق یک پروکسی را، همانطور که قبلاً توضیح داده شد، تجسم کنید، میتوانید دامنهی متغیر را درک کنید. منظور ما از دامنه، نقطهای در چرخهی حیات جریان پروکسی است که یک متغیر برای اولین بار نمونهسازی میشود.
برای مثال، اگر یک سیاست (policy) به بخش درخواست ProxyEndpoint متصل شده باشد، آن سیاست قادر به دسترسی به هیچ متغیری که در محدودهی بخش درخواست TargetEndpoint قرار دارد، نخواهد بود. دلیل این امر این است که بخش درخواست TargetEndpoint از جریان هنوز اجرا نشده است، بنابراین پروکسی API فرصتی برای پر کردن متغیرها در آن محدوده نداشته است.
جدول زیر مجموعه کاملی از محدودههای متغیر را فهرست میکند و نشان میدهد که چه زمانی در جریان پروکسی در دسترس قرار میگیرند.
| دامنه متغیر | جایی که این متغیرها پر میشوند |
|---|---|
| درخواست پروکسی | بخش درخواست ProxyEndpoint |
| درخواست هدف | بخش درخواست TargetEndpoint |
| پاسخ هدف | بخش پاسخ TargetEndpoint |
| پاسخ پروکسی | بخش پاسخ ProxyEndpoint |
| همیشه در دسترس | به محض اینکه پروکسی درخواستی دریافت کند. این متغیرها در کل چرخه حیات جریان پروکسی در دسترس هستند. |
برای مثال، یک متغیر داخلی Edge به نام client.ip وجود دارد. این متغیر دامنه "درخواست پروکسی" دارد. به طور خودکار با آدرس IP کلاینتی که پروکسی را فراخوانی کرده است، پر میشود. این متغیر زمانی پر میشود که یک درخواست برای اولین بار به ProxyEndpoint میرسد و در کل چرخه حیات جریان پروکسی در دسترس باقی میماند.
یک متغیر داخلی دیگر به نام target.url وجود دارد. دامنه این متغیر "target request" است. این متغیر در بخش درخواست TargetEndpoint با URL درخواستی که به back-end target ارسال میشود، پر میشود. اگر سعی کنید در بخش درخواست ProxyEndpoint target.url دسترسی پیدا کنید، مقدار NULL دریافت خواهید کرد. اگر سعی کنید این متغیر را قبل از اینکه در محدوده قرار گیرد، تنظیم کنید، پروکسی هیچ کاری انجام نمیدهد - خطایی ایجاد نمیکند و متغیر را تنظیم نمیکند.
در اینجا یک مثال ساده وجود دارد که نحوه تفکر در مورد دامنه متغیر را نشان میدهد. فرض کنید میخواهید کل محتوای یک شیء درخواست (هدرها، پارامترها، بدنه) را کپی کرده و آن را به payload پاسخ اختصاص دهید تا به برنامه فراخوانی کننده ارسال شود. میتوانید از سیاست 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 یا undefined محدود میشوند.
استفاده از متغیرهای جریان در سیاستها
بسیاری از سیاستها، متغیرهای جریان را به عنوان بخشی از اجرای عادی خود ایجاد میکنند. مرجع سیاست، تمام این متغیرهای خاص سیاست را مستند میکند.
هنگام کار با پروکسیها و سیاستها، حتماً به مرجع سیاست مراجعه کنید تا بفهمید کدام متغیرها ایجاد میشوند و برای چه چیزی استفاده میشوند. به عنوان مثال، سیاست سهمیه مجموعهای از متغیرها را ایجاد میکند که حاوی اطلاعاتی در مورد تعداد و محدودیتهای سهمیه، زمان انقضا و غیره هستند.
برخی از متغیرهای سیاست برای اشکالزدایی مفید هستند. برای مثال، میتوانید از ابزار Trace برای دیدن اینکه کدام متغیرها در یک نمونه خاص در یک جریان پروکسی تنظیم شدهاند، استفاده کنید.
سیاست 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 " مراجعه کنید.
آنچه باید به خاطر داشته باشید
در اینجا چند نکته مهم در مورد متغیرهای جریان وجود دارد که باید به خاطر داشته باشید:
- برخی از متغیرهای «آماده» به طور خودکار توسط خود پروکسی نمونهسازی و مقداردهی میشوند. این موارد در مرجع متغیرهای Flow مستند شدهاند.
- شما میتوانید متغیرهای سفارشی ایجاد کنید که برای استفاده در جریان پروکسی در دسترس باشند. ایجاد متغیرها با استفاده از سیاستهایی مانند سیاست AssignMessage و سیاست جاوا اسکریپت و در کد Node.js امکانپذیر است.
- متغیرها دارای دامنه هستند. برای مثال، برخی از متغیرها به طور خودکار زمانی که اولین پروکسی درخواستی از یک برنامه دریافت میکند، پر میشوند. سایر متغیرها در بخش جریان پاسخ پروکسی پر میشوند. این متغیرهای پاسخ تا زمانی که بخش پاسخ اجرا نشود، تعریف نشده باقی میمانند.
- وقتی سیاستها اجرا میشوند، میتوانند متغیرهای مختص به سیاست را ایجاد و پر کنند. مستندات مربوط به هر سیاست، تمام این متغیرهای مختص به سیاست مربوطه را فهرست میکند.
- جریانهای شرطی معمولاً یک یا چند متغیر را ارزیابی میکنند. اگر میخواهید جریانهای شرطی ایجاد کنید، باید متغیرها را درک کنید.
- بسیاری از سیاستها از متغیرها به عنوان ورودی یا خروجی استفاده میکنند. شاید متغیری که توسط یک سیاست ایجاد میشود، بعداً توسط سیاست دیگری مورد استفاده قرار گیرد.
- شما میتوانید بسیاری از متغیرهای جریان را از داخل Node.js با استفاده مستقیم از جاوا اسکریپت (و مدل شیء جاوا اسکریپت ما) یا سیاست JavaCallout که کد را در Edge اجرا میکند، دریافت و تنظیم کنید.
نمونههای کد مرتبط
نمونههای پروکسی API در GitHub هستند و دانلود و استفاده از آنها آسان است. برای اطلاعات در مورد دانلود و استفاده از نمونهها ، به بخش «استفاده از نمونه پروکسیهای API» مراجعه کنید. برای شرح نمونههای پروکسی API و عملکرد آنها، به فهرست نمونهها مراجعه کنید.
نمونههایی از پروکسیهایی که از متغیرها و پردازش متغیر استفاده میکنند عبارتند از:
- متغیرها - نحوه استخراج و تنظیم متغیرها بر اساس انتقال و محتوای پیام JSON و XML را نشان میدهد.
- policy-mashup-cookbook - یک برنامه کامل که از ترکیب سیاست برای فراخوانی دو API عمومی استفاده میکند، نتایج را ترکیب میکند و یک پاسخ غنیشده برای برنامه کلاینت تولید میکند. برای اطلاعات بیشتر در مورد این نمونه، به استفاده از ترکیب سیاست مراجعه کنید.
- سیاست شرطی - اجرای سیاستهای شرطی ساده را بر اساس مقادیر متغیر پیادهسازی میکند.
مباحث مرتبط
- تمام متغیرهایی که به طور خودکار در یک پروکسی API قرار میگیرند، در مرجع متغیرهای Flow فهرست شدهاند. این مرجع همچنین نوع و دامنه هر متغیر را فهرست میکند.
- اگر میخواهید بدانید که یک سیاست خاص کدام متغیرها را جمعآوری میکند، به مبحث مرجع مربوط به آن سیاست مراجعه کنید. برای مثال، به متغیرهای جریان در مرجع سیاست سهمیهبندی مراجعه کنید.