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

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

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

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

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

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

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

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

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

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

2 جریان مشروط

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

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

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

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

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

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

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

در یک نقطه پایانی پروکسی، یک PreFlow یک مکان عالی برای کد است که یک کلاینت را احراز هویت می کند و ترافیک مشتریان را محدود می کند. در نقطه پایانی هدف، جایی که شروع به آماده‌سازی برای ارسال درخواست به هدف باطن می‌کند، یک 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>
    ...

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

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

اضافه کردن منطق به جریان ها

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

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

رسیدگی به خطاها در جریان

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

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

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

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