افزودن پشتیبانی از CORS به پراکسی میانای برنامه‌سازی کاربردی

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

‫CORS (هم‌رسانی منبع میان‌مبدئی) سازوکار استانداردی است که به فراخوانی‌های JavaScript XMLHttpRequest (XHR) اجراشده در صفحه وب اجازه می‌دهد با منابع دامنه‌های غیرمبدأ تعامل داشته باشد. ‫CORS راه‌حلی است که معمولاً برای «خط‌مشی مبدأ یکسان» که توسط همه مرورگرها اجرا می‌شود پیاده‌سازی می‌شود. برای مثال، اگر از کد جاوا اسکریپت درحال اجرا در مرورگرتان، فراخوانی XHR به Twitter API انجام دهید، فراخوانی ناموفق خواهد بود. دلیل این امر این است که دامنه‌ای که صفحه را به مرورگر شما ارائه می‌دهد با دامنه‌ای که Twitter API را ارائه می‌دهد یکسان نیست. ‫CORS با اجازه دادن به سرورها برای «موافقت» با هم‌رسانی منابع بین مبدأها، راه‌حلی برای این مشکل ارائه می‌دهد.

ویدیو: برای آشنایی با نحوه فعال کردن CORS در پراکسی API، ویدیو کوتاهی را تماشا کنید.

مورد استفاده معمول برای CORS

کد JQuery زیر یک سرویس هدف ساختگی را فراخوانی می‌کند. اگر از داخل زمینه مرورگر (صفحه وب) اجرا شود، به‌دلیل خط‌مشی مبدأ یکسان، تماس ناموفق خواهد بود:

<script>
var url = "http://service.example.com";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This is where we end up!
            }
    });
  });
});
</script>

یکی از راه‌حل‌های این مشکل ایجاد یک پراکسی Apigee API است که API سرویس را در پشتیبان فراخوانی می‌کند. به‌یاد داشته باشید که Edge بین کارخواه (در این مورد، مرورگر) و زیرینه میانای برنامه‌سازی کاربردی (سرویس) قرار دارد. چون پراکسی API در سرور اجرا می‌شود، نه در مرورگر، می‌تواند سرویس را با موفقیت فراخوانی کند. سپس، تنها کاری که باید انجام دهید این است که سرصفحه‌های CORS را به پاسخ TargetEndpoint پیوست کنید. تا زمانی که مرورگر از CORS پشتیبانی کند، این سرایندها به مرورگر علامت می‌دهند که «خط‌مشی مبدأ یکسان» خود را «آزاد کند» و به فراخوانی میانای برنامه‌سازی کاربردی چندمبدأ اجازه موفقیت دهد.

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

<script>
var url = "http://myorg-test.apigee.net/v1/example";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This time, we do not end up here!
            }
    });
  });
});
</script>

پیوست کردن خط‌مشی «افزودن خط‌مشی CORS» به کارگزار میانای برنامه‌سازی کاربردی جدید

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

وقتی این چارگوش انتخاب را انتخاب می‌کنید، خط‌مشی‌ای به‌نام «افزودن CORS» به‌طور خودکار به سیستم اضافه می‌شود و به پیش‌جریان پاسخ «نقطه پایانی هدف» پیوست می‌شود، همان‌طور که در شکل زیر نشان داده شده است:

خط‌مشی CORS به پیمایشگر در بخش «خط‌مشی‌ها» اضافه شد و به پیش‌جریان پاسخ TargetEndpoint در پانل سمت راست پیوست شد

خط‌مشی «افزودن خط‌مشی CORS» به‌عنوان خط‌مشی «تخصیص پیام» پیاده‌سازی می‌شود که سرایندهای مناسب را به پاسخ اضافه می‌کند. اساساً، سرایندها به مرورگر اطلاع می‌دهند که منابع خود را با کدام مبدأها هم‌رسانی کند، کدام روش‌ها را می‌پذیرد، و غیره. می‌توانید درباره این سرایندهای CORS در توصیه W3C درباره هم‌رسانی منبع میان‌مبدئی بیشتر بخوانید.

باید خط‌مشی را به‌صورت زیر اصلاح کنید:

  • سرآیندهای content-type و authorization (برای پشتیبانی از اصالت‌سنجی پایه یا OAuth2 الزامی است) را به سرآیند Access-Control-Allow-Headers اضافه کنید، همان‌طور که در گزیده کد زیر نشان داده شده است.
  • برای اصالت‌سنجی OAuth2، ممکن است لازم باشد اقداماتی برای اصلاح رفتار غیرسازگار با RFC انجام دهید.
  • توصیه می‌شود که به‌جای <Add>، از <Set> برای تنظیم سرایندهای CORS استفاده کنید، همان‌طور که در گزیده زیر نشان داده شده است. هنگام استفاده از <Add>، اگر سرایند Access-Control-Allow-Origin ازقبل وجود داشته باشد، خطای زیر را دریافت خواهید کرد:

    The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

    برای کسب اطلاعات بیشتر، خطای CORS : سرایند حاوی چندین مقدار «*, *» است، اما فقط یک مقدار مجاز است را ببینید.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

افزودن سرایندهای CORS به پراکسی موجود

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

مدیریت درخواست‌های پیش‌پرواز CORS

پیش‌پرواز CORS به ارسال درخواست به سرور برای تأیید اینکه آیا از CORS پشتیبانی می‌کند یا نه اشاره دارد. پاسخ‌های پیش‌پرواز معمولاً شامل این موارد است: مبدأهایی که سرور درخواست‌های CORS را از آن‌ها می‌پذیرد، فهرستی از روش‌های HTTP که برای درخواست‌های CORS پشتیبانی می‌شوند، سرایندهایی که می‌توانند به‌عنوان بخشی از درخواست منبع استفاده شوند، حداکثر زمان ذخیره شدن پاسخ پیش‌پرواز در حافظه نهان، و موارد دیگر. اگر سرویس از پشتیبانی CORS خبر ندهد یا نخواهد درخواست‌های بین مبدأ را از مبدأ کارخواه بپذیرد، خط‌مشی بین مبدأ مرورگر اجرا خواهد شد و هرگونه درخواست بین دامنه‌ای که کارخواه برای تعامل با منابع میزبانی‌شده در آن سرور ارسال کند ناموفق خواهد بود.

معمولاً درخواست‌های پیش‌پرواز CORS با روش HTTP OPTIONS انجام می‌شوند. وقتی سروری که از CORS پشتیبانی می‌کند درخواست OPTIONS دریافت می‌کند، مجموعه‌ای از سرایندهای CORS را به کلاینت برمی‌گرداند که سطح پشتیبانی CORS آن را نشان می‌دهد. در نتیجه این دست دادن، کارخواه می‌داند که چه چیزی مجاز است از دامنه غیرمبدأ درخواست کند.

برای اطلاعات بیشتر درباره پیش‌پرواز، به توصیه W3C درباره هم‌رسانی منابع بین مبدأها مراجعه کنید. علاوه‌براین، وبلاگ‌ها و مقاله‌های متعددی درباره CORS وجود دارد که می‌توانید به آن‌ها مراجعه کنید.

Apigee راه‌حل پیش‌پرواز CORS را به‌صورت آماده ارائه نمی‌دهد، اما همان‌طور که در این بخش توضیح داده شده است، پیاده‌سازی آن امکان‌پذیر است. هدف این است که پراکسی درخواست OPTIONS را در یک جریان شرطی ارزیابی کند. کارگزار می‌تواند پاسخ مناسبی به کارخواه ارسال کند.

بیایید به یک جریان نمونه نگاه کنیم و سپس درباره بخش‌هایی که درخواست پیش‌پرواز را مدیریت می‌کنند بحث کنیم:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <Description/>
    <Flows>
        <Flow name="OptionsPreFlight">
            <Request/>
            <Response>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Response>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
        </Flow>
    </Flows>

    <PreFlow name="PreFlow">
        <Request/>
        <Response/>

    </PreFlow>
    <HTTPProxyConnection>
        <BasePath>/v1/cnc</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="NoRoute">
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
    </RouteRule>
    <RouteRule name="default">
        <TargetEndpoint>default</TargetEndpoint>
   </RouteRule>
   <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
</ProxyEndpoint>

بخش‌های کلیدی این ProxyEndpoint به‌شرح زیر است:

  • «قانون مسیر» با شرط درخواست «گزینه‌ها» برای هدف «تهی» ایجاد می‌شود. توجه داشته باشید که هیچ TargetEndpoint مشخص نشده است. اگر درخواست OPTIONS دریافت شود و سرصفحه‌های درخواست Origin و Access-Control-Request-Method غیرتهی باشند، کارگزار بلافاصله سرصفحه‌های CORS را در پاسخی به مشتری برمی‌گرداند (هدف «پشتیبان» پیش‌فرض واقعی را دور می‌زند). برای جزئیات مربوط به شرایط جریان و RouteRule، به شرایط با متغیرهای جریان مراجعه کنید.

    <RouteRule name="NoRoute">
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
    </RouteRule>
  • جریانی به نام OptionsPreFlight ایجاد می‌شود که اگر درخواست OPTIONS دریافت شود و سراینده و سراینده‌های درخواست Access-Control-Request-Method تهی نباشند، خط‌مشی «افزودن CORS» را که حاوی سراینده‌های CORS است به جریان اضافه می‌کند.

     <Flow name="OptionsPreFlight">
                <Request/>
                <Response>
                    <Step>
                        <Name>add-cors</Name>
                    </Step>
                </Response>
            <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
     </Flow>

استفاده از راهکار نمونه CORS

یک راهکار نمونه CORS که به‌عنوان یک جریان مشترک پیاده‌سازی شده است، در GitHub دردسترس است. بسته جریان هم‌رسانی‌شده را به محیطتان وارد کنید و آن را بااستفاده از قلاب‌های جریان یا مستقیماً به جریان‌های پراکسی میانای برنامه‌سازی کاربردی پیوست کنید. برای جزئیات، فایل CORS-Shared-FLow README ارائه‌شده با نمونه را ببینید.