CORS

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

يضيف نهج cors دعم مشاركة الموارد عبر المنشأ (CORS) إلى عملية أو API للسماح بمكالمات عبر النطاقات من عملاء يستندون إلى المستعرض.

إشعار

تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. لمساعدتك في تكوين هذا النهج، يتيح المدخل محررًا موجهًا يستند إلى النموذج. تعلم كيفية إعداد نُهج APIM أو تعديلها.

نهج السياسة

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

سمات

الاسم ‏‏الوصف مطلوبة افتراضي
السماح ببيانات الاعتماد Access-Control-Allow-Credentialsسيتم تعيين العنوان في استجابة الاختبار المسبق لقيمة هذه السمة ويؤثر على قدرة العميل على إرسال بيانات الاعتماد في طلبات عبر المجال. يتم السماح بتعبيرات النهج. لا false
إنهاء طلب غير متطابق تتحكم هذه السمة في معالجة طلبات المنشأ المشترك التي لا تتطابق مع إعدادات نهج CORS. يتم السماح بتعبيرات النهج.

عند OPTIONS معالجة الطلب كطلب الاختبار المبدئي ولا Origin يتطابق العنوان مع إعدادات النهج:
- إذا تم تعيين السمة إلى true، فقم بإنهاء الطلب فورا باستجابة فارغة 200 OK
- إذا تم تعيين السمة إلى false، فتحقق من الواردة للنهج الأخرى داخل النطاق cors التي هي توابع مباشرة للعنصر الوارد وتطبيقها. إذا لم يتم العثور على نُهج cors قم بإنهاء الطلب مع استجابة 200 OK فارغة.

عندما GET يتضمن Origin أو HEAD الطلب العنوان (وبالتالي تتم معالجته كطلب بسيط عبر المنشأ)، ولا يتطابق مع إعدادات النهج:
- إذا تم تعيين السمة إلى true، فقم بإنهاء الطلب فورا باستجابة فارغة 200 OK .
- إذا تم تعيين السمة إلى false، فاسمح للطلب بالمتابعة بشكل طبيعي ولا تضيف عناوين CORS إلى الاستجابة.
لا true

عناصر

Name ‏‏الوصف مطلوبة افتراضي
الأصول المسموح بها يحتوي علىorigin عناصر تصف الأصول المسموح بها لطلبات المجال المشترك. allowed-origins يمكن أن يحتوي إما على عنصر واحد origin يحدد للسماح بأي أصل أو عنصر واحد أو أكثر يحتوي على *origin URI. ‏‏نعم‬ غير متوفر
allowed-methods هذا العنصر مطلوب إذا تم السماح بطرق أخرى غير GET أو POST. يحتوي على method عناصر تحدد أفعال HTTP المعتمدة. تشير * القيمة إلى كافة الطرق. لا إذا لم يتوفر هذا القسم، يتم دعم GETو POST.
الرؤوس المسموح بها يحتوي هذا العنصر على header عناصر تحدد أسماء العناوين التي يمكن تضمينها في الطلب. ‏‏نعم‬ غير متوفر
كشف عناوين يحتوي هذا العنصر على header عناصر تحدد أسماء العناوين التي يمكن تضمينها في الطلب. لا ‏‫غير متاح

تنبيه

استخدم حرف بدل* بعناية في إعدادات النهج. قد يكون هذا التكوين متساهلاً بشكل مفرط وقد يجعل واجهة برمجة التطبيقات أكثر عرضة إلى تهديدات أمان واجهة برمجة التطبيقات معينة.

عناصر الأصول المسموح بها

Name ‏‏الوصف مطلوبة افتراضي
أصلي يمكن أن تكون القيمة إما * للسماح بكافة الأصول أو URI الذي يحدد أصل واحد. يجب أن يتضمن URI نظام مضيف ومنفذ. ولا تقم بتضمين علامات الاقتباس. ‏‏نعم‬ إذا تم حذف المنفذ في URI، يتم استخدام المنفذ 80 ل HTTP ويتم استخدام المنفذ 443 ل HTTPS.

سمات الأساليب المسموح بها

Name ‏‏الوصف مطلوبة افتراضي
ما قبل الرحلة - النتيجة - الحد الأقصى للعمر سيتم تعيين العنوان Access-Control-Max-Age في الاستجابة المبدئية لقيمة هذه السمة ويؤثر على قدرة العميل المستخدم على التخزين المؤقت للاستجابة المبدئية. يتم السماح بتعبيرات النهج. لا 0

عناصر الأساليب المسموح بها

Name ‏‏الوصف مطلوبة افتراضي
الطريقة تعين فعل HTTP. يتم السماح بتعبيرات النهج. مطلوب عنصر واحد على الأقل method إذا كان allowed-methods المقطع موجودا. ‏‫غير متوفر‬

عناصر الرؤوس المسموح بها

Name ‏‏الوصف مطلوبة Default
العنوان تعين اسم عنوان مطلوب عنصر واحد header على الأقل في allowed-headers إذا كان هذا القسم موجودا. ‏‫غير متوفر‬

كشف عناصر الرؤوس

Name ‏‏الوصف مطلوبة Default
العنوان تعين اسم عنوان مطلوب عنصر واحد header على الأقل في expose-headers إذا كان هذا القسم موجودا. ‏‫غير متوفر‬

الاستخدام

  • أقسام النهج:الواردة.
  • نطاقات النهج: العمومية، ومساحة العمل، والمنتج، وواجهة برمجة التطبيقات، والتشغيل
  • البوابات: الكلاسيكية، الإصدار 2، الاستهلاك، المستضافة ذاتيا، مساحة العمل

ملاحظات الاستخدام

  • يمكنك تكوين النهج cors في أكثر من نطاق واحد (على سبيل المثال، في نطاق المنتج والنطاق العمومي). تأكد من تكوين العنصر base في العملية وواجهة برمجة التطبيقات ونطاقات المنتجات لتوريث النُهج المطلوبة في النطاقات الأصلية.
  • يتم تقييم النهج cors فقط عند الطلب OPTIONS أثناء الاختبار المبدئي. يتم تقييم النُهج المكونة المتبقية بناءً على الطلب المعتمد.
  • يمكن استخدام هذا النهج مرة واحدة فقط في قسم النهج.

نبذة عن CORS

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

تحدد CORS نوعين من الطلبات عبر المنشأ:

  • طلبات الاختبار المسبق (أو "الاختبار المبدئي") - يرسل المستعرض أولًا طلب HTTP باستخدام OPTIONS الأسلوب إلى الخادم، لتحديد ما إذا كان الطلب الفعلي مسموحًا بإرساله. إذا كانت استجابة الخادم تتضمن عنوان Access-Control-Allow-Origin الذي يسمح بالوصول، يتبع المتصفح الطلب الفعلي.

  • طلبات بسيطة - تتضمن هذه الطلبات عنوانًا إضافيًا Origin واحدًا أو أكثر ولكن لا تشغل الاختبار المبدئي ل CORS. يسمح فقط بالطلبات التي تستخدم أساليب GET و HEAD ومجموعة محدودة من عناوين الطلبات.

cors سيناريوهات النهج

تكوين cors النهج في APIM للسيناريوهات التالية:

  • تمكين وحدة تحكم الاختبار التفاعلية في مدخل المطور. راجع وثائق مدخل المطور للحصول على التفاصيل.

    إشعار

    عند تمكين CORS لوحدة التحكم التفاعلية، تقوم APIM بشكل افتراضي بتكوين cors النهج في النطاق العمومي.

  • قم بتمكين إدارة APIM للرد على طلبات الاختبار المبدئي أو المرور عبر طلبات CORS البسيطة عندما لا توفر الخلفيات دعم CORS الخاص بها.

    إشعار

    إذا كان الطلب يطابق عملية مع أسلوب OPTIONS المعرّفة في واجهة برمجة التطبيقات، لن يتم تنفيذ منطق معالجة طلب مبدئي المقترن بنهج cors. لذلك، يمكن استخدام هذه العمليات لتنفيذ منطق معالجة الاختبار المبدئي المخصص - على سبيل المثال، لتطبيق النهج cors فقط في ظل ظروف معينة.

مشكلات التكوين الشائعة

  • مفتاح الاشتراك في العنوان - إذا قمت بتكوين cors النهج في نطاق المنتج، بينما واجهة برمجة التطبيقات تستخدم مصادقة مفتاح الاشتراك، فلن يعمل النهج عند تمرير مفتاح الاشتراك في العنوان. كحل بديل، قم بتعديل الطلبات لتضمين مفتاح اشتراك كمعلمة استعلام.
  • واجهة برمجة التطبيقات مع تعيين إصدار العنوان - إذا قمت بتكوين cors النهج في نطاق واجهة برمجة التطبيقات، بينما تستخدم واجهة برمجة التطبيقات نظام إصدار العنوان، فلن يعمل النهج لأنه يتم تمرير الإصدار في العنوان. قد تحتاج إلى تكوين أسلوب إصدار بديل مثل مسار أو معلمة استعلام.
  • ترتيب النهج - قد تواجه سلوكًا غير متوقع إذا cors لم يكن النهج هو النهج الأول في القسم الوارد. حدّد حساب النهج الفعّال في محرر النهج للتحقق من ترتيب تقييم النهج في كل نطاق. بشكل عام، يتم تطبيق النهج الأول cors فقط.
  • استجابة Empty 200 OK - في بعض تكوينات النهج، تكتمل بعض الطلبات عبر المنشأ مع استجابة فارغة 200 OK. هذه الاستجابة متوقعة عند تعيين terminate-unmatched-request إلى قيمتها الافتراضية الخاصة trueوعند حصول الطلب الوارد على عنوان Originلا يتطابق مع أصل مسموح به تم تكوينه في النهج cors.

مثال

يوضح هذا المثال كيفية دعم الطلبات المبدئيةمثل تلك التي تتضمن عناوين مخصصة أو أساليب أخرى غير GETو POST. لدعم عناوين مخصصة وأفعال HTTP إضافية، استخدم أقسام allowed-methods وallowed-headers كما هو موضح في المثال التالي.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

لمزيد من المعلومات حول العمل مع النُهج، راجع: