إضافة دعم CORS إلى خادم وكيل لواجهة برمجة التطبيقات

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

سياسة مشاركة الموارد المتعددة المصادر (CORS) هي آلية عادية تسمح باستخدام JavaScript. استدعاءات XMLHttpRequest (XHR) التي يتم تنفيذها في صفحة ويب للتفاعل مع موارد من غير المصدر النطاقات. تمثّل سياسة مشاركة الموارد المتعددة المصادر (CORS) حلاً شائعًا التنفيذ لـ "سياسة المصدر نفسه". يتم فرضها من خلال جميع المتصفحات. على سبيل المثال، إذا أجريت استدعاء XHR لواجهة برمجة تطبيقات Twitter من رمز JavaScript في متصفحك، فسيفشل الاتصال. وذلك لأن النطاق الذي يعرض الصفحة على أن يكون متصفحك ليس هو نفسه النطاق الذي يقدم واجهة برمجة تطبيقات Twitter. توفر سياسة مشاركة الموارد المتعددة المصادر (CORS) حلاً هذه المشكلة عن طريق السماح للخوادم "بالاشتراك" في حال أرادوا توفير مصادر من مصادر متعددة المشاركة.

حالة استخدام نموذجية لسياسة مشاركة الموارد المتعددة المصادر (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 يستدعي واجهة برمجة تطبيقات الخدمة على الواجهة الخلفية. تذكر أن شبكة Edge تقع بين العميل (المتصفح في هذه الحالة) والخلفية API (الخدمة). نظرًا لأن خادم وكيل واجهة برمجة التطبيقات يتم تنفيذه على الخادم وليس في المتصفح، تمكن من الاتصال بالخدمة بنجاح. بعد ذلك، كل ما عليك فعله هي إرفاق عناوين CORS باستجابة TargetEndpoint. وطالما أن المتصفح يدعم سياسة مشاركة الموارد المتعددة المصادر (CORS)، فهذه العناوين تشير إلى المتصفح بأنّه لا بأس من "الاسترخاء". بسياسة المصدر نفسه، ما يسمح نجاح طلب البيانات من واجهة برمجة التطبيقات من مصادر متعددة.

بمجرد إنشاء الخادم الوكيل الذي يتيح استخدام سياسة مشاركة الموارد المتعددة المصادر (CORS)، يمكنك طلب عنوان URL للخادم الوكيل لواجهة برمجة التطبيقات بدلاً من الخلفية في التعليمات البرمجية من جانب العميل. على سبيل المثال:

<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 إلى خادم وكيل لواجهة برمجة التطبيقات من خلال إرفاق "إضافة CORS". على الخادم الوكيل لواجهة برمجة التطبيقات عند إنشائها. لإضافة هذه السياسة، ضَع علامة في مربّع الاختيار إضافة عناوين CORS في صفحة الأمان في معالج إنشاء خادم وكيل.

عند وضع علامة في مربّع الاختيار هذا، تتم تلقائيًا إضافة سياسة تُسمى "إضافة سياسة مشاركة الموارد المتعددة المصادر (CORS)" إلى النظام. ومرفق بها التدفق المسبق لاستجابة TargetEndpoint، كما هو موضح في الشكل التالي:

يتم تنفيذ سياسة إضافة CORS كسياسة AssignMessage، وهي ويضيف العناوين المناسبة إلى الرد. تتيح العناوين للمتصفح معرفة المصادر التي ستتم مشاركة موارده معها، والطرق التي تقبلها، وما إلى ذلك. يمكنك قراءة المزيد عن عناوين CORS هذه في اقتراح W3C لمشاركة الموارد المتعدّدة المصادر

عليك تعديل السياسة على النحو التالي:

• أضِف العنوانَين content-type وauthorization (المطلوبَين لتوفير المصادقة الأساسية أو OAuth2) إلى العنوان Access-Control-Allow-Headers، كما هو موضّح في مقتطف الرمز أدناه.
• بالنسبة إلى مصادقة OAuth2، قد تحتاج إلى اتخاذ خطوات معيّنة لتصحيح السلوك غير المتوافق مع RFC.
• ننصح باستخدام <Set> لضبط عناوين CORS بدلاً من <Add>، كما هو موضّح في المقتطف أدناه. عند استخدام <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) الطلبات الواردة من مصدر العميل، فسيتم فرض سياسة المشاركة المتعددة المصادر في المتصفّح أي طلبات عبر النطاقات يتم إجراؤها من العميل للتفاعل مع الموارد التي يستضيفها ذلك الخادم ستفشل.

عادةً ما يتم تنفيذ طلبات طلب CORS المبدئي باستخدام طريقة خيارات HTTP. عندما يقوم خادم تتلقى سياسة مشاركة الموارد المتعددة المصادر (CORS) طلب OPTIONS، فإنها تُرجع مجموعة من عناوين سياسة مشاركة الموارد المتعددة المصادر (CORS) إلى العميل للإشارة إلى مستوى دعم سياسة مشاركة الموارد المتعددة المصادر (CORS). ونتيجة لهذه المصافحة، يعرف العميل ما هي يُسمح لهم بتقديم طلب من نطاق غير صادر عن المستخدم.

لمزيد من المعلومات عن الطلب المبدئي، يُرجى الرجوع إلى اقتراح W3C لمشاركة الموارد المتعدّدة المصادر. تتوفر في بالإضافة إلى العديد من المدونات والمقالات عن سياسة CORS التي يمكنك الرجوع إليها.

لا توفّر Apigee حلاً للإطلاق التجريبي لـ CORS، ولكن من الممكن تنفيذها، كما هو موضح في هذا القسم. الهدف هو تقييم الوكيل لخيارات الطلب في تدفق مشروط. يمكن للخادم الوكيل إرسال رد مناسب إلى البرنامج.

لنلقِ نظرة على مسار نموذجي، ثم نناقش الأجزاء التي تتعامل مع الطلب المبدئي:

<?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 هذه:

• يتم إنشاء RouteRule على هدف "NULL" (فارغ) مع شرط خاص بطلب OPTIONS. لاحظ أن لم يتم تحديد TargetEndpoint. إذا تم تلقي طلب OPTIONS وكان المصدر رؤوس طلبات 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>
  

• يتم إنشاء تدفق OptionPreFlight الذي يضيف سياسة "إضافة سياسة مشاركة الموارد المتعددة المصادر (CORS)" التي تحتوي على سياسة مشاركة الموارد المتعددة المصادر (CORS). إلى التدفق إذا تم تلقي طلب OPTIONS ومصدر هذه البيانات عناوين طلبات Access-Control-Request-Method ليست فارغة.
  
  

   <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 مع النموذج.