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>
النهج ذات الصلة
المحتوى ذو الصلة
لمزيد من المعلومات حول العمل مع النُهج، راجع: