کنترل نحوه اجرای کارگزار با جریان‌ها

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

هر مدل برنامه‌نویسی کاربردی شامل روشی برای کنترل جریان پردازش است. در یک پراکسی API، این کار با جریان‌ها انجام می‌شود. به جاری‌سازی‌ها منطق، گزاره‌های شرطی، رسیدگی به خطا، و غیره اضافه می‌کنید. از جریان‌ها برای کنترل آنچه اتفاق می‌افتد و زمان آن استفاده می‌کنید.

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

مثال پیکربندی جاریان زیر جاریانی را تعریف می‌کند که در آن خط‌مشی VerifyAPIKey اگر مسیر درخواست ورودی با / تمام شود و فعل HTTP درخواست «دریافت» باشد اجرا می‌شود.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

مقدار Verify-API-Key در عنصر <Name> جریان برای گنجاندن خط‌مشی‌ای که در جای دیگری در پراکسی با XML پیکربندی شده است، مانند موارد زیر، استفاده می‌شود:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

درحال طراحی توالی اجرای جریان

جریان‌ها را به‌گونه‌ای ساختاردهی می‌کنید که بتوانید منطق را در توالی درست در مسیر پردازش اجرا کنید.

هنگام تصمیم‌گیری درباره اینکه منطق را کجا اضافه کنید، ابتدا انتخاب می‌کنید که آن را به نقطه پایانی پراکسی اضافه کنید یا به نقطه پایانی هدف. کارگزار API کد خود را بین کدی که با کارگزار مشتری (نقطه پایانی کارگزار) تعامل دارد و کد اختیاری که با هدف پشتیبان کارگزار تعامل دارد، درصورت وجود (نقطه پایانی هدف)، تقسیم می‌کند.

هر دو نقطه پایانی حاوی جریان هستند، همان‌طور که در اینجا توضیح داده شده است:

نوع نقطه پایانی شرح جریان‌های کار پشتیبانی‌شده
ProxyEndpoint شامل جریان‌های پراکسی میانای برنامه‌سازی کاربردی نزدیک‌ترین به مشتری است. مکان‌هایی را برای عملکرد منطق فراهم می‌کند ابتدا در درخواست از کارخواه، سپس در پاسخ به کارخواه. PreFlow، جریان‌های شرطی، PostFlow،‏ PostClientFlow
TargetEndpoint شامل جریان‌های پراکسی میانای برنامه‌سازی کاربردی نزدیک‌ترین به منبع زیرینه است. مکان‌هایی را برای منطق فراهم می‌کند تا درخواست را برای منبع زمینه‌ای آماده کند، سپس پاسخ را از منبع زمینه‌ای مدیریت کند. PreFlow، جریان‌های شرطی، PostFlow

جریان را با XML پیکربندی می‌کنید که مشخص می‌کند چه اتفاقی باید بیفتد و به چه ترتیبی. تصویر زیر نشان می‌دهد که جریان‌ها چگونه به‌صورت ترتیبی در نقطه پایانی پراکسی و نقطه پایانی هدف مرتب می‌شوند:

درخواست از کارخواه HTTP که از «نقطه پایان پراکسی» به «نقطه پایان هدف» در زیرینه ارسال می‌شود تا به سرویس HTTP برسد. هر پانل درخواست و پاسخ، جریان پیش‌از جاری‌سازی، جریان‌های شرطی، و جریان پس‌از جاری‌سازی را نشان می‌دهد. علاوه‌براین، نمونه‌هایی از نقطه پایان پراکسی و نقطه پایان هدف ارائه شده است.

نقطه پایانی پراکسی و نقطه پایانی هدف هرکدام حاوی جاری‌سازی‌هایی هستند که می‌توانید آن‌ها را در توالی زیر ترتیب دهید:

موقعیت نوع جریان شرح
1 PreFlow

وقتی لازم است مطمئن شوید کد خاصی قبل‌از هر چیز دیگری اجرا می‌شود مفید است.

اگر PreFlow در نقطه پایانی هدف باشد، پس‌از نقطه پایانی پراکسی PostFlow اجرا می‌شود.
2 جریان شرطی

مکان منطق شرطی. پس‌از «جریان پیش‌از اجرا» و قبل‌از «جریان پس‌از اجرا» اجرا می‌شود.

فقط یک جریان کار شرطی برای هر بخش اجرا می‌شود--اولین جریانی که شرط آن به درست ارزیابی می‌شود. یعنی می‌توانید یک جریان شرطی داشته باشید که به‌عنوان بخشی از هریک از موارد زیر اجرا شود:
  • خط لوله درخواست ProxyEndpoint
  • خط لوله درخواست TargetEndpoint
  • خط لوله پاسخ ProxyEndpoint
  • خط لوله پاسخ TargetEndpoint
3 PostFlow

جایی مناسب برای ثبت داده‌ها، ارسال اعلان مبنی بر اینکه هنگام پردازش درخواست اتفاقی افتاده است، و غیره. پس‌از جریان‌های شرطی و «جریان پیش‌از اجرا» اجرا می‌شود.

اگر PostFlow در نقطه پایانی پراکسی باشد و نقطه پایانی هدفی وجود داشته باشد، نقطه پایانی پراکسی PostFlow قبل‌از نقطه پایانی هدف PreFlow اجرا می‌شود.
4 PostClientFlow (فقط جریان پراکسی) جریانی برای ثبت پیام‌ها پس‌از اینکه پاسخ به کارخواه برگردانده می‌شود.

اجرای کد ابتدا با PreFlow

«جریان پیش‌از اجرا» زمانی مفید است که بخواهید مطمئن شوید کد خاصی قبل‌از هر چیز دیگری اجرا می‌شود.

در نقطه پایانی پراکسی، «جریان پیش‌از اجرا» مکان مناسبی برای کد اصالت‌سنجی کارخواه و محدود کردن ترافیک کارخواهان است. در نقطه پایانی هدف، جایی که شروع به آماده‌سازی برای ارسال درخواست به هدف زمینه‌ای می‌کند، «جریان پیش‌از اجرا» برای اولین گام‌های آماده‌سازی برای ارسال درخواست مناسب است.

برای مثال، معمولاً نمی‌خواهید به کاربری که از سهمیه خود فراتر رفته است خدمات ارائه دهید. برای پشتیبانی از این الزامات، خط‌مشی‌های سهمیه و امنیت را در بخش «جریان پیش‌از اجرا» قرار می‌دهید. به این ترتیب، لازم نیست نگران باشید که شرطی در جریان شرطی بعدی ارزیابی نشود. خط‌مشی‌های این جریان همیشه قبل‌از هر پردازش دیگری اجرا خواهند شد.

در مثال زیر، خط‌مشی‌های SpikeArrest و Quota قبل‌از پردازش گذرها به جریان‌های شرطی اجرا می‌شوند.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

اجرای کد به‌صورت شرطی با جاری‌سازی شرطی

بین «جریان پیش‌از» و «جریان پس‌از»، می‌توانید جریان‌هایی داشته باشید که به‌صورت شرطی اجرا می‌شوند. این کار به شما امکان می‌دهد چندین توالی منطقی را پیکربندی کنید، اما براساس وضعیت کارگزار فقط یکی از آن‌ها اجرا شود. اگر بتوانید همه منطق را در PreFlow یا PostFlow اجرا کنید و هیچ شرطی لازم نباشد (به‌عبارت دیگر، فقط یک مسیر ازطریق نقطه پایانی پشتیبانی شود)، جریان شرطی اختیاری است.

هر جریان شرطی را مشخص می‌کند که مقادیر حالت مختلف را آزمایش می‌کند. این کار به‌طور مؤثر اجرا را براساس شرایط شاخه‌بندی می‌کند. برای مثال، ممکن است بخواهید XML را فقط زمانی به JSON تبدیل کنید که برنامه درخواست‌کننده در دستگاه همراه اجرا می‌شود.

در اینجا، محدودیت‌های سهمیه فقط درصورتی اعمال می‌شود که درخواست از نوع GET با الگوی نشانی وب /issue/** (/issue/ با هر چیزی در نشانی وب پس‌از آخرین اسلش رو به جلو) باشد.

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

از متغیرهای جریان برای مشخص کردن شرایط استفاده می‌کنید. برای اطلاعات بیشتر درباره استفاده از متغیرها در شرایط، شرایط با متغیرهای جریان را ببینید.

برای نمونه‌هایی از استفاده از تطبیق الگو در شرایط، به تطبیق الگو مراجعه کنید.

اجرای کد پس‌از منطق اصلی با «جریان پس از اجرا»

«جریان پس‌از» مکان مناسبی برای انجام کنش‌ها پس‌از منطق اصلی نقطه پایانی و قبل‌از پایان پردازش نقطه پایانی است. «جریان پس‌از» پس‌از جریان‌های شرطی و «جریان پیش‌از» اجرا می‌شود.

«جریان پس‌از» مکان خوبی برای ثبت برخی داده‌ها، ارسال اعلان مبنی بر وقوع اتفاقی، تبدیل قالب پیام پاسخ، و غیره است.

در مثال زیر، خط‌مشی AssignMessage به‌نام SetResponseHeaders سرصفحه‌های پیام پاسخ را قبل‌از اینکه Apigee Edge پاسخ را به مشتری برگرداند تنظیم می‌کند.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

اجرای کد پس‌از دریافت پاسخ کارگزار شما توسط مشتری با PostClientFlow

«جریان PostClientFlow» می‌تواند شامل خط‌مشی‌های زیر باشد:

* خط‌مشی «دعوت به جاری‌سازی» فقط می‌تواند جاری‌سازی‌های هم‌رسانی‌شده‌ای را فراخوانی کند که خودشان معیارهای قرار گرفتن در «جاری‌سازی پس‌از مشتری» را داشته باشند (یعنی فقط حاوی خط‌مشی‌های سازگار باشند).

اگر یکی را اضافه کنید، PostClientFlow آخرین جاری‌سازی خواهد بود که اجرا می‌شود و پس‌از ارسال پاسخ به مشتری اجرا می‌شود.

‫PostClientFlow برای ثبت نهایی خوب است. همچنین می‌توانید مُهر زمان شروع و پایان را برای پیام پاسخ ثبت کنید.

در اینجا نمونه‌ای از PostClientFlow با خط‌مشی MessageLogging پیوست‌شده آورده شده است.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

ویدیو: این ویدیو کوتاه را ببینید که نحوه ایجاد PostClientFlow بااستفاده از خط‌مشی MessageLogging از مجموعه «ویدیو چهار دقیقه‌ای برای توسعه‌دهندگان» (4MV4D) را نشان می‌دهد.

برای اطلاعات بیشتر، به اینجا مراجعه کنید:

افزودن منطق به جریان‌ها

وقتی به کارگزارتان منطق اضافه می‌کنید، این کار را با افزودن خط‌مشی به جاری‌سازی‌های کارگزارتان انجام می‌دهید. همان‌طور که جریان‌ها به‌صورت توالی اجرا می‌شوند (ابتدا «جریان پیش‌از اجرا» سپس «جریان» سپس «جریان پس‌از اجرا»، همان‌طور که در این موضوع توضیح داده شده است)، محتوای جریان نیز به‌صورت توالی اجرا می‌شود.

پیکربندی جریان نمونه زیر به سه خط‌مشی (پیکربندی‌شده در جای دیگر در فایل‌های XML خودشان) ارجاع می‌دهد. خط‌مشی ارجاع‌شده توسط Verify-API-Key قبل‌از خط‌مشی ارجاع‌شده توسط Remove-API-Key اجرا می‌شود؛ هر دو خط‌مشی با خط‌مشی نشان‌داده‌شده توسط Quota دنبال می‌شوند.

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

کنسول Apigee Edge این توالی خط‌مشی‌ها را به‌صورت ردیفی از نمادها نشان می‌دهد که هر نماد نشان‌دهنده خط‌مشی است.

کنسول Apigee Edge این توالی خط‌مشی‌ها را به‌صورت ردیفی از نمادها ارائه می‌دهد که هر نماد نشان‌دهنده خط‌مشی است. نمادهای نشان‌داده‌شده در مسیر درخواست شامل این موارد است: «تأیید کلید میانای API»، «برداشتن کلید میانای API»، و «سهمیه»

جریان‌های اشکال‌زدایی

ابزار Apigee Edge Trace روشی گرافیکی برای دیدن نحوه اجرای منطق در پراکسی API شما پس‌از درخواست ارائه می‌دهد. این ابزار پردازش بین درخواست و پاسخ را نشان می‌دهد. این به‌طور خاص جدایی بین «جریان پیش‌از پخش»، جریان‌های شرطی، و «جریان پس‌از پخش» را نشان نمی‌دهد.

برای اطلاعات بیشتر درباره ردیابی پراکسی‌ها، به استفاده از ابزار ردیابی مراجعه کنید.

مدیریت خطاها در جریان‌ها

می‌توانید خطاها را از مکان‌های مختلف در پراکسی API، ازجمله از جریان‌ها، افزایش دهید.

مثال زیر بخش پاسخ از «جریان پیش‌از» در نقطه پایانی هدف است -- به عبارت دیگر، این کد بلافاصله پس‌از دریافت پاسخ از هدف زیرینه اجرا می‌شود. در این مثال، اگر پاسخ هدف ۲۰۰ (موفقیت) نباشد، خطا ایجاد می‌شود.

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

برای اطلاعات بیشتر درباره مدیریت خطا، به مدیریت خطاها مراجعه کنید.