CORS

Makale
04/04/2024

UYGULANANLAR: Tüm API Management katmanları

İlke, cors tarayıcı tabanlı istemcilerden etki alanları arası çağrılara izin vermek için bir işleme veya API'ye çıkış noktaları arası kaynak paylaşımı (CORS) desteği ekler.

Not

İlkenin öğelerini ve alt öğelerini ilke bildiriminde sağlanan sırayla ayarlayın. Portal, bu ilkeyi yapılandırmanıza yardımcı olmak için kılavuzlu, form tabanlı bir düzenleyici sağlar. API Management ilkelerini ayarlama veya düzenleme hakkında daha fazla bilgi edinin.

İlke bildirimi

<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>

Özellikler

Adı	Açıklama	Zorunlu	Varsayılan
allow-credentials	`Access-Control-Allow-Credentials` Denetim öncesi yanıttaki üst bilgi bu özniteliğin değerine ayarlanır ve istemcinin etki alanları arası isteklerde kimlik bilgilerini gönderebilmesini etkiler. İlke ifadelerine izin verilir.	Hayır	`false`
terminate-unmatched-request	İlke ayarlarıyla eşleşmeyen çıkış noktaları arası isteklerin işlenmesini denetler. İlke ifadelerine izin verilir. İstek bir denetim öncesi isteği olarak işlendiğinde `OPTIONS` ve `Origin` üst bilgi ilke ayarlarıyla eşleşmiyorsa: - Özniteliği olarak ayarlanırsa `true`isteği hemen boş `200 OK` bir yanıtla sonlandırın - Özniteliği olarak `false`ayarlanırsa, gelen öğesinin doğrudan alt öğeleri olan diğer kapsam `cors` içi ilkeleri denetleyin ve uygulayın. hiçbir `cors` ilke bulunmazsa, isteği boş `200 OK` bir yanıtla sonlandırın. veya `GETHEAD` isteği üst bilgisini içerdiğinde `Origin` (ve bu nedenle basit bir çıkış noktaları arası istek olarak işlenir) ve ilke ayarlarıyla eşleşmez: - Özniteliği olarak `true`ayarlanırsa, isteği hemen boş `200 OK` bir yanıtla sonlandırın. - Özniteliği olarak ayarlandıysa `false`, isteğin normal şekilde ilerlemesine izin verin ve yanıta CORS üst bilgileri eklemeyin.	Hayır	`true`

Öğeler

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
izin verilen çıkış noktaları	Etki alanları arası isteklerin izin verilen çıkış noktalarını açıklayan öğeleri içerir `origin` . `allowed-origins`herhangi bir kaynak veya URI içeren bir veya daha fazla `origin` öğeye izin verebileceğini belirten `*` tek `origin` bir öğe içerebilir.	Yes	Yok
izin verilen yöntemler	Veya dışındaki `GETPOST` yöntemlere izin veriliyorsa bu öğe gereklidir. Desteklenen HTTP fiillerini belirten öğeleri içerir `method` . değeri `*` tüm yöntemleri gösterir.	Hayır	Bu bölüm yoksa `GET` ve `POST` destekleniyorsa.
allowed-headers	Bu öğe, isteğe dahil edilebilecek üst bilgilerin adlarını belirten öğeler içerir `header` .	Yes	Yok
expose-headers	Bu öğe, istemci tarafından erişilebilecek üst bilgilerin adlarını belirten öğeler içerir `header` .	Hayır	YOK

Dikkat

İlke * ayarlarında joker karakteri dikkatli kullanın. Bu yapılandırma fazla izin verebilir ve bir API'yi belirli API güvenlik tehditlerine karşı daha savunmasız hale getirebilir.

izin verilen çıkış noktaları öğeleri

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
başlangıç	Değer, tüm çıkış noktalarına izin vermek için veya tek bir çıkış noktası belirten bir URI olabilir `*` . URI bir düzen, konak ve bağlantı noktası içermelidir. Tırnak işaretleri kullanmayın.	Yes	Bağlantı noktası bir URI'de atlanırsa, HTTP için 80 numaralı bağlantı noktası kullanılır ve HTTPS için 443 numaralı bağlantı noktası kullanılır.

allowed-methods öznitelikleri

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
preflight-result-max-age	Denetim `Access-Control-Max-Age` öncesi yanıttaki üst bilgi bu özniteliğin değerine ayarlanır ve kullanıcı aracısının denetim öncesi yanıtı önbelleğe alma yeteneğini etkiler. İlke ifadelerine izin verilir.	Hayır	0

allowed-methods öğeleri

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
yöntemi	HTTP fiilini belirtir. İlke ifadelerine izin verilir.	Bölüm varsa `allowed-methods` en az bir `method` öğe gereklidir.	Yok

allowed-headers öğeleri

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
üst bilgi	Üst bilgi adını belirtir.	Bu bölüm varsa içinde `allowed-headers` en az bir `header` öğe gereklidir.	Yok

expose-headers öğeleri

Veri Akışı Adı	Açıklama	Zorunlu	Varsayılan
üst bilgi	Üst bilgi adını belirtir.	Bu bölüm varsa içinde `expose-headers` en az bir `header` öğe gereklidir.	Yok

Kullanım

İlke bölümleri: gelen
İlke kapsamları: genel, çalışma alanı, ürün, API, işlem
Ağ geçitleri: klasik, v2, tüketim, şirket içinde barındırılan

Kullanım notları

İlkeyi cors birden fazla kapsamda (örneğin, ürün kapsamında ve genel kapsamda) yapılandırabilirsiniz. öğesinin base işlem, API ve ürün kapsamlarında üst kapsamlarda gerekli ilkeleri devralacak şekilde yapılandırıldığından emin olun.
cors Ön kontrol sırasında istekte OPTIONS yalnızca ilke değerlendirilir. Yapılandırılan diğer ilkeler onaylanan istekte değerlendirilir.

Bu ilke, ilke bölümünde yalnızca bir kez kullanılabilir.

CORS hakkında

CORS , tarayıcının ve sunucunun etkileşim kurmasına ve belirli çıkış noktaları arası isteklere (XMLHttpRequest web sayfasındaki JavaScript'ten diğer etki alanlarına yapılan çağrılar) izin verilip verilmeyeceğini belirlemesine olanak tanıyan HTTP üst bilgi tabanlı bir standarttır. Bu, yalnızca aynı kaynak isteklerine izin vermekten daha fazla esneklik sağlar, ancak tüm çıkış noktaları arası isteklere izin vermekten daha güvenlidir.

CORS iki tür çıkış noktaları arası istek belirtir:

Önceden denetimli (veya "ön kontrol") istekleri - Tarayıcı, asıl isteğin gönderilmesine izin verilip verilmediğini belirlemek için önce yöntemini kullanarak OPTIONS sunucuya bir HTTP isteği gönderir. Sunucu yanıtı erişime izin veren üst bilgi içeriyorsa Access-Control-Allow-Origin , tarayıcı gerçek isteği izler.
Basit istekler - Bu istekler bir veya daha fazla ek Origin üst bilgi içerir, ancak CORS ön kontrol tetiklemez. Yalnızca ve HEAD yöntemlerini ve sınırlı bir istek üst bilgisi kümesini kullanan GET isteklere izin verilir.

`cors` ilke senaryoları

cors API Management'ta ilkeyi aşağıdaki senaryolar için yapılandırın:

Geliştirici portalında etkileşimli test konsolunu etkinleştirin. Ayrıntılar için geliştirici portalı belgelerine bakın.

Not

Etkileşimli konsol için CORS'yi etkinleştirdiğinizde API Management varsayılan olarak ilkeyi cors genel kapsamda yapılandırılır.
Arka uçlar kendi CORS desteğini sağlamadığında denetim öncesi istekleri yanıtlamak veya basit CORS isteklerinden geçmek için API Management’i etkinleştirin.

Not

İstek, API'de tanımlanan bir OPTIONS yöntemle bir işlemle eşleşiyorsa, ilkeyle cors ilişkili denetim öncesi istek işleme mantığı yürütülmeyecektir. Bu nedenle, bu tür işlemler özel denetim öncesi işleme mantığını uygulamak için kullanılabilir; örneğin, ilkeyi cors yalnızca belirli koşullar altında uygulamak için.

Yaygın yapılandırma sorunları

Üst bilgideki abonelik anahtarı - İlkeyi corsürün kapsamında yapılandırdıysanız ve API'niz abonelik anahtarı kimlik doğrulamasını kullanıyorsa, abonelik anahtarı üst bilgide geçirildiğinde ilke çalışmaz. Geçici bir çözüm olarak, istekleri bir abonelik anahtarını sorgu parametresi olarak içerecek şekilde değiştirin.
Üst bilgi sürümü oluşturma ile API - İlkeyi corsAPI kapsamında yapılandırıyorsanız ve API'niz üst bilgi sürüm oluşturma şeması kullanıyorsa, sürüm üst bilgide geçirildiğinden ilke çalışmaz. Yol veya sorgu parametresi gibi alternatif bir sürüm oluşturma yöntemi yapılandırmanız gerekebilir.
İlke sırası - İlke gelen bölümündeki ilk ilke değilse cors beklenmeyen davranışla karşılaşabilirsiniz. İlke düzenleyicisinde Etkin ilkeyi hesapla'yı seçerek her kapsamdaki ilke değerlendirme sırasını denetleyin. Genel olarak, yalnızca ilk cors ilke uygulanır.
Boş 200 Tamam yanıtı - Bazı ilke yapılandırmalarında, bazı çıkış noktaları arası istekler boş 200 OK bir yanıtla tamamlar. Bu yanıt, varsayılan değerine true ayarlandığında ve gelen isteğin ilkede cors yapılandırılan izin verilen kaynakla eşleşmeyen bir Origin üst bilgisi olduğunda terminate-unmatched-request beklenir.

Örnek

Bu örnekte, ve dışında POSTGET özel üst bilgileri veya yöntemleri olanlar gibi denetim öncesi isteklerin nasıl desteklenip desteklendiği gösterilmektedir. Özel üst bilgileri ve diğer HTTP fiillerini desteklemek için aşağıdaki örnekte gösterildiği gibi ve allowed-headers bölümlerini kullanınallowed-methods.

<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>

Etki alanları arası

İlkelerle çalışma hakkında daha fazla bilgi için bkz: