کنترل نحوه اجرای یک پروکسی با جریان ها

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

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

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

مثال پیکربندی جریان زیر، جریانی را تعریف می‌کند که در آن، سیاست VerifyAPIKey در صورتی اجرا می‌شود که مسیر درخواست ورودی با / خاتمه یابد و فعل HTTP درخواست، GET باشد.

<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 کد خود را بین کدی که با کلاینت پروکسی (نقطه پایانی پروکسی) تعامل دارد و کد اختیاری که با هدف بک‌اند پروکسی، در صورت وجود (نقطه پایانی هدف) تعامل دارد، تقسیم می‌کند.

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

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

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

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

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

موقعیت نوع جریان توضیحات
۱ پیش جریان

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

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

۲ جریان شرطی

محل منطق شرطی. بعد از PreFlow و قبل از PostFlow اجرا می‌شود.

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

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

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

۴ PostClientFlow (فقط جریان پروکسی) جریانی برای ثبت پیام‌ها پس از ارسال پاسخ به کلاینت.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

یک PostClientFlow می‌تواند شامل سیاست‌های زیر باشد:

* سیاست FlowCallout فقط می‌تواند جریان‌های مشترکی را فراخوانی کند که خودشان معیارهای حضور در 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) نشان می‌دهد، تماشا کنید.

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

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

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

پیکربندی جریان مثال زیر به سه سیاست (که در جای دیگری در فایل‌های 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 شما پس از یک درخواست ارائه می‌دهد. این ابزار پردازش بین درخواست و پاسخ را نشان می‌دهد. اما به طور خاص تفکیک بین PreFlow، جریان‌های شرطی و PostFlow را نشان نمی‌دهد.

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

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

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

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

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

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