İçeriği doğrulama

UYGULANANLAR: Tüm API Management katmanları

İlke, validate-content bir isteğin veya yanıt gövdesinin boyutunu veya içeriğini desteklenen bir veya daha fazla şemaya göre doğrular.

Aşağıdaki tablo, ilkenin desteklediği şema biçimlerini ve istek veya yanıt içerik türlerini gösterir. İçerik türü değerleri büyük/küçük harfe duyarlı değildir.

Biçimlendir	İçerik türleri
JSON	Örnekler: application/json application/hal+json
XML	Örnek: application/xml
SOAP	İzin verilen değerler: application/soap+xml SOAP 1.2 API'leri için text/xml SOAP 1.1 API'leri için

Not

Bu doğrulama ilkesi tarafından kullanılabilecek API şemasının boyutu üst sınırı 4 MB'tır. Şema bu sınırı aşarsa doğrulama ilkeleri çalışma zamanında hata döndürür. Bunu artırmak için lütfen desteğe başvurun.

Hangi içerik doğrulanır?

İlke, istekte veya yanıtta aşağıdaki içeriği şemaya göre doğrular:

• Tüm gerekli özelliklerin varlığı.
• Şemada alan ayarlanmışsa, ek özelliklerin additionalProperties varlığı veya yokluğu. özniteliğiyle allow-additional-properties geçersiz kılınabilir.
• Tüm özelliklerin türleri. Örneğin, bir şema bir özelliği bir tamsayı olarak belirtiyorsa, istek (veya yanıt) bir tamsayı içermelidir ve dize gibi başka bir tür içermemelidir.
• Şemada belirtilmişse özelliklerin biçimi ; örneğin, regex (anahtar sözcük belirtilmişse pattern ), minimum tamsayılar için vb.

İpucu

Şemalarda kullanılabilecek regex desen kısıtlamalarının örnekleri için bkz . OWASP Doğrulama Regex Deposu.

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

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" />
</validate-content>

Özellikler

Öznitelik	Açıklama	Zorunlu	Varsayılan
unspecified-content-type-action	API şemasında belirtilmemiş içerik türüne sahip istekler veya yanıtlar için gerçekleştirilecek eylem . İlke ifadelerine izin verilir.	Yes	Yok
en büyük boyut	İstek veya yanıtın üst bilgiyle denetlenen bayt cinsinden gövdesinin Content-Length uzunluk üst sınırı. İstek gövdesi veya yanıt gövdesi sıkıştırılmışsa, bu değer sıkıştırılmış uzunlukdur. İzin verilen en yüksek değer: 102.400 bayt (100 KB). (Bu sınırı artırmanız gerekiyorsa desteğe başvurun.) İlke ifadelerine izin verilir.	Yes	Yok
boyut aşıldı eylemi	Gövdesi içinde max-sizebelirtilen boyutu aşan istekler veya yanıtlar için gerçekleştirilecek eylem. İlke ifadelerine izin verilir.	Yes	Yok
errors-variable-name	Doğrulama hatalarını günlüğe kaydetmek için içindeki context.Variables değişkenin adı. İlke ifadelerine izin verilmez.	Hayır	YOK

Öğeler

Veri Akışı Adı	Açıklama	Gerekli
content-type-map	Gelen isteğin veya yanıtın içerik türünü doğrulamayı tetiklemede kullanılan başka bir içerik türüyle eşlemek için bu öğeyi ekleyin.	Hayır
content	İstek veya yanıttaki içerik türünü veya eşlenmiş içerik türünü doğrulamak ve belirtilen eylemi gerçekleştirmek için bu öğelerden birini veya daha fazlasını ekleyin.	Hayır

content-type-map öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
any-content-type-value	Gelen içerik türünden bağımsız olarak bir isteğin veya yanıtın gövdesini doğrulama için kullanılan içerik türü. İlke ifadelerine izin verilmez.	Hayır	YOK
missing-content-type-value	Gelen içerik türü eksik veya boş olduğunda, bir isteğin veya yanıtın gövdesinin doğrulanması için kullanılan içerik türü. İlke ifadelerine izin verilmez.	Hayır	YOK

content-type-map-elements

Veri Akışı Adı	Açıklama	Gerekli
Tür	Gelen içerik türünü, bir isteğin veya yanıtın gövdesinin doğrulanması için kullanılan bir içerik türüne eşlemek için bu öğelerden birini veya daha fazlasını ekleyin. Bilinen bir gelen içerik türünü belirtmek için kullanın from veya bir koşulla eşleşen herhangi bir gelen içerik türünü belirtmek için bir ilke ifadesiyle kullanın when . belirtilmişse ve missing-content-type-valueiçindeki any-content-type-value eşlemeyi geçersiz kılar.	Hayır

içerik öznitelikleri

Öznitelik	Açıklama	Zorunlu	Varsayılan
Tür	Gövde doğrulamasını yürütmek için içerik türü, içerik türü üst bilgisinde veya belirtildiyse içinde eşlenen değerle content-type-mappingdenetlendi. Boşsa, API şemasında belirtilen her içerik türüne uygulanır. SOAP isteklerini ve yanıtlarını doğrulamak için (validate-as öznitelik "soap" olarak ayarlanır), SOAP 1.2 API'leri veya text/xml SOAP 1.1 API'leri için olarak ayarlayın typeapplication/soap+xml.	Hayır	YOK
farklı doğrula	eşleşen bir istek veya yanıt typegövdesinin doğrulanması için kullanılacak doğrulama altyapısı. Desteklenen değerler: "json", "xml", "soap". "soap" belirtildiğinde, istek veya yanıttan gelen XML SOAP zarfından ayıklanır ve xml şemasına göre doğrulanır.	Yes	Yok
schema-id	İçerik doğrulaması için API Management örneğine eklenen mevcut şemanın adı. Belirtilmezse, API tanımından varsayılan şema kullanılır.	Hayır	YOK
şema başvurusu	içinde schema-idbelirtilen bir JSON şeması için, JSON belgesindeki geçerli bir yerel başvuru yoluna isteğe bağlı başvuru. Örnek: #/components/schemas/address. özniteliği, API Management'ın geçerli bir JSON şeması olarak işlediği bir JSON nesnesi döndürmelidir. XML şeması schema-ref için desteklenmez ve herhangi bir üst düzey şema öğesi XML isteğinin veya yanıt yükünün kökü olarak kullanılabilir. Doğrulama, XML isteğinden veya yanıt yükü kökünden başlayan tüm öğelerin sağlanan XML şemasına uygun olup olmadığını denetler.	Hayır	YOK
allow-additional-properties	Boole. JSON şeması için, şemada yapılandırılan değerin çalışma zamanı geçersiz kılmasının additionalProperties uygulanıp uygulanmayacağını belirtir: - true: JSON şemasının additionalProperties alanı ek özelliklere izin vermeyecek şekilde yapılandırılmış olsa bile istek veya yanıt gövdesinde ek özelliklere izin verin. - false: JSON şemasının additionalProperties alanı ek özelliklere izin verecek şekilde yapılandırılmış olsa bile istek veya yanıt gövdesinde ek özelliklere izin verme. Öznitelik belirtilmezse, ilke şemadaki alanın yapılandırmasına additionalProperties göre ek özellikleri doğrular.	Hayır	YOK

Eylemler

İçerik doğrulama ilkeleri, api isteğindeki bir varlığı doğrularken API Management'ın API şemasına karşı gerçekleştirilen bir eylemi belirten bir veya daha fazla öznitelik içerir.

• API şemasında temsil edilen öğeler için ve ilkeye bağlı olarak API şemasında temsil edilmeen öğeler için bir eylem belirtilebilir.

• İlkenin alt öğesinde belirtilen bir eylem, üst öğesi için belirtilen bir eylemi geçersiz kılar.

Kullanılabilir eylemler:

Eylem	Açıklama
yoksayma	Doğrulamayı atlayın.
Önle	İstek veya yanıt işlemeyi engelleyin, ayrıntılı doğrulama hatasını günlüğe kaydedip bir hata döndürin. İlk hata kümesi algılandığında işleme kesintiye uğrar.
detect	İstek veya yanıt işlemeyi kesintiye uğratmadan günlük doğrulama hataları.

Kullanım

• İlke bölümleri: gelen, giden, hata durumunda
• İ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

Günlükler

İlke yürütme sırasındaki doğrulama hataları hakkındaki ayrıntılar, ilkenin kök öğesindeki özniteliğinde errors-variable-name belirtilen değişkene context.Variables kaydedilir. Bir prevent eylemde yapılandırıldığında, doğrulama hatası daha fazla istek veya yanıt işlemeyi engeller ve ayrıca özelliğine context.LastError yayılır.

Hataları araştırmak için bağlam değişkenlerindeki hataları Uygulama Analizler günlüğe kaydetmek için bir izleme ilkesi kullanın.

Performans üzerindeki etkileri

Doğrulama ilkesi eklemek API aktarım hızını etkileyebilir. Aşağıdaki genel ilkeler geçerlidir:

• API şema boyutu ne kadar büyük olursa aktarım hızı o kadar düşük olur.
• İstek veya yanıttaki yük ne kadar büyük olursa aktarım hızı o kadar düşük olur.
• API şemasının boyutu, performans üzerinde yükün boyutundan daha büyük bir etkiye sahiptir.
• Boyutu birkaç megabayt olan bir API şemasında doğrulama, bazı koşullar altında istek veya yanıt zaman aşımlarına neden olabilir. Etki, hizmetin Tüketim ve Geliştirici katmanlarında daha belirgindir.

Doğrulama ilkelerinin API aktarım hızı üzerindeki etkisini değerlendirmek için beklenen üretim iş yüklerinizle yük testleri gerçekleştirmenizi öneririz.

İçerik doğrulama şemaları

Varsayılan olarak, istek veya yanıt içeriğinin doğrulanması API tanımından JSON veya XML şemalarını kullanır. Bu şemalar bir OpenAPI veya WSDL belirtiminden API Management'a aktarılırken el ile belirtilebilir veya otomatik olarak oluşturulabilir.

İlkeyi validate-content kullanarak, isteğe bağlı olarak API Management örneğinize eklediğiniz ve API tanımının parçası olmayan bir veya daha fazla JSON veya XML şemasında doğrulayabilirsiniz. API Management'a eklediğiniz bir şema birçok API'de yeniden kullanılabilir.

Azure portalını kullanarak API Management örneğinize şema eklemek için:

1. Portalda API Management örneğine gidin.

2. Sol taraftaki menünün API'ler bölümünde Şemalar>+ Ekle'yi seçin.

3. Şema oluştur penceresinde aşağıdakileri yapın:

   1. Şema için bir Ad (Kimlik) girin.
   2. Şema türü'nde JSON veya XML'yi seçin.
   3. Bir Açıklama girin.
   4. Create metodunda aşağıdakilerden birini yapın:
      • Yeni oluştur'u seçin ve şemayı girin veya yapıştırın.
      • Dosyadan içeri aktar'ı veya URL'den içeri aktar'ı seçin ve bir şema konumu girin.

        Not

        URL'den bir şemayı içeri aktarmak için şemaya tarayıcıdan İnternet üzerinden erişilebilir olması gerekir.

   5. Kaydet'i seçin.

   

API Management şema kaynağını göreli URI'ye /schemas/<schemaId>ekler ve şema Şemalar sayfasındaki listede görünür. Özelliklerini görüntülemek veya şema düzenleyicisinde düzenlemek için bir şema seçin.

Not

Bir şema, API Management örneğine eklenen başka bir şemaya çapraz başvuruda bulunabilir. Örneğin, aşağıdakine benzer bir öğe kullanarak API Management'a eklenmiş bir XML şeması ekleyin:

<xs:include schemaLocation="/schemas/myschema" />

İpucu

WSDL ve XSD şema başvurularını çözümlemeye ve oluşturulan şemaları API Management'a toplu içeri aktarmaya yönelik açık kaynak araçları GitHub'da kullanılabilir.

Örnekler

JSON şema doğrulaması

Aşağıdaki örnekte API Management, boş içerik türü üst bilgisine sahip istekleri veya içerik türü üst bilgisine application/hal+json sahip istekleri içerik türüne application/jsonsahip istekler olarak yorumlar. Ardından API Management, API tanımındaki içerik türü için tanımlanan bir şemada application/json algılama modunda doğrulama gerçekleştirir. Yükü 100 KB'tan büyük olan iletiler engellenir. Şemanın additionalProperties alanı ek özelliklere izin verecek şekilde yapılandırılmış olsa bile ek özellikler içeren istekler engellenir.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

SOAP şema doğrulaması

Aşağıdaki örnekte API Management, gelen içerik türünden bağımsız olarak tüm istekleri içerik türüyle application/soap+xml (SOAP 1.2 API'leri tarafından kullanılan içerik türü) istek olarak yorumlar. İstek boş bir içerik türü üst bilgisi, içerik türü üst bilgisi text/xml (SOAP 1.1 API'leri tarafından kullanılır) veya başka bir içerik türü üst bilgisi ile gelebilir. Ardından API Management, SOAP zarfından XML yükünü ayıklar ve "myschema" adlı şemaya karşı önleme modunda doğrulama gerçekleştirir. Yükü 100 KB'tan büyük olan iletiler engellenir.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

Doğrulama hataları

API Management, aşağıdaki biçimde içerik doğrulama hataları oluşturur:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

Aşağıdaki tabloda doğrulama ilkelerinin tüm olası hataları listeledik.

• Ayrıntılar: Hataları araştırmak için kullanılabilir. Herkese açık olarak paylaşılmamalıdır.
• Genel yanıt: İstemciye hata döndürüldü. Uygulama ayrıntılarını sızdırmaz.

Doğrulama ilkesi eylemi belirttiğinde prevent ve bir hata ürettiğinde, API management'tan gelen yanıt bir HTTP durum kodu içerir: İlke gelen bölümünde uygulandığında 400 ve giden bölümde ilke uygulandığında 502.

Ad	Tür	Doğrulama kuralı	Ayrıntılar	Genel yanıt	Eylem
içeriği doğrulama
	RequestBody	SizeLimit	İsteğin gövdesi {size} bayt uzunluğunda ve yapılandırılmış {maxSize} bayt sınırını aşıyor.	İsteğin gövdesi {size} bayt uzunluğunda ve {maxSize} bayt sınırını aşıyor.	algılama /önleme
	ResponseBody	SizeLimit	Yanıtın gövdesi {size} bayt uzunluğunda ve yapılandırılmış {maxSize} bayt sınırını aşıyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{messageContentType}	RequestBody	Belirtilme -miş	Belirtilmemiş {messageContentType} içerik türüne izin verilmiyor.	Belirtilmemiş {messageContentType} içerik türüne izin verilmiyor.	algılama /önleme
{messageContentType}	ResponseBody	Belirtilme -miş	Belirtilmemiş {messageContentType} içerik türüne izin verilmiyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	ApiSchema		API'nin şeması yok veya çözümlenemedi.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	ApiSchema		API'nin şeması tanımları belirtmez.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{messageContentType}	RequestBody / ResponseBody	MissingDefinition	API'nin şeması{messageContentType} içerik türüyle ilişkili {definitionName} tanımını içermiyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{messageContentType}	RequestBody	IncorrectMessage	İsteğin gövdesi{messageContentType} içerik türüyle ilişkili {definitionName} tanımına uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	İsteğin gövdesi{messageContentType} içerik türüyle ilişkili {definitionName} tanımına uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	algılama /önleme
{messageContentType}	ResponseBody	IncorrectMessage	Yanıtın gövdesi{ messageContentType} içerik türüyle ilişkili {definitionName} tanımına uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	RequestBody	Validationexception	İsteğin gövdesi {messageContentType} içerik türü için doğrulanamıyor. {özel durum ayrıntıları}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	ResponseBody	Validationexception	Yanıtın gövdesi {messageContentType} içerik türü için doğrulanamıyor. {özel durum ayrıntıları}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
validate-parameters / validate-headers
{paramName} / {headerName}	QueryParameter / PathParameter / RequestHeader	Belirtilme -miş	Belirtilmemiş {path parametresi / sorgu parametresi / header} {paramName} izin verilmiyor.	Belirtilmemiş {path parametresi / sorgu parametresi / header} {paramName} izin verilmiyor.	algılama /önleme
{headerName}	ResponseHeader	Belirtilme -miş	Belirtilmemiş {headerName} üst bilgilerine izin verilmiyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	ApiSchema		API'nin şeması yok veya çözümlenemedi.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
	ApiSchema		API şeması tanımları belirtmez.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{paramName}	QueryParameter / PathParameter / RequestHeader / ResponseHeader	MissingDefinition	API'nin şeması {query parametresi / yol parametresi / header} {paramName} ile ilişkili {definitionName} tanımını içermiyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	İstek, {query parametresi / yol parametresi / header} {paramName} için birden çok değer içeremez.	İstek, {query parametresi / yol parametresi / header} {paramName} için birden çok değer içeremez.	algılama /önleme
{headerName}	ResponseHeader	IncorrectMessage	Yanıt, {headerName} üst bilgisi için birden çok değer içeremez.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	{query parametresi / yol parametresi / header} {paramName} değeri tanıma uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	{query parametresi / yol parametresi / header} {paramName} değeri tanıma uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	algılama /önleme
{headerName}	ResponseHeader	IncorrectMessage	{headerName} üst bilgisinin değeri tanıma uymuyor. {valError.Message} Satır: {valError.LineNumber}, Position: {valError.LinePosition}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{paramName}	QueryParameter / PathParameter / RequestHeader	IncorrectMessage	{query parametresi / yol parametresi / header} {paramName} değeri tanıma göre ayrıştırılamaz. {örn. message}	{query parametresi / yol parametresi / header} {paramName} değerinin tanımına göre ayrıştırılamadı. {örn. message}	algılama /önleme
{headerName}	ResponseHeader	IncorrectMessage	{headerName} üst bilgisinin değeri tanıma göre ayrıştırılamıyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{paramName}	QueryParameter / PathParameter / RequestHeader	Validationerror	{Sorgu parametresi / Yol parametresi / Header} {paramName} doğrulanamıyor. {özel durum ayrıntıları}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
{headerName}	ResponseHeader	Validationerror	{headerName} üst bilgisi doğrulanamıyor. {özel durum ayrıntıları}	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme
validate-status-code
{status-code}	StatusCode	Belirtilme -miş	Yanıt durum koduna {status-code} izin verilmiyor.	İstek bir iç hata nedeniyle işlenemedi. API sahibine başvurun.	algılama /önleme

Aşağıdaki tabloda, olası İleti değerleriyle birlikte doğrulama hatasının tüm olası Neden değerleri listelenir:

Nedeni	İleti
Hatalı istek	Bağlam değişkeni için {Details}, istemci için {Public response}
Yanıta izin verilmiyor	Bağlam değişkeni için {Details}, istemci için {Public response}

İlgili ilkeler

• İçerik doğrulama

İlgili içerik

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

• Öğretici: API'nizi dönüştürme ve koruma
• İlke deyimlerinin ve ayarlarının tam listesi için ilke başvurusu
• İlke ifadeleri
• İlkeleri ayarlama veya düzenleme
• İlke yapılandırmalarını yeniden kullanma
• İlke kod parçacıkları deposu
• Azure için Microsoft Copilot kullanarak ilke yazma