Parametreleri doğrulama

Makale
03/18/2024

UYGULANANLAR: Tüm API Management katmanları

İlke validate-parameters , isteklerdeki üst bilgi, sorgu veya yol parametrelerini API şemasına göre doğrular.

Önemli

API'yi sürümünden önceki bir yönetim API'sini 2021-01-01-previewvalidate-parameters kullanarak içeri aktardıysanız, ilke çalışmayabilir. Yönetim API'sini veya sonraki bir sürümünü 2021-01-01-preview kullanarak API'nizi yeniden içeri aktarmanız gerekebilir.

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.

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-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Özellikler

Öznitelik	Açıklama	Zorunlu	Varsayılan
specified-parameter-action	API şemasında belirtilen istek parametreleri için gerçekleştirilecek eylem . bir `headers`, `query`veya `path` öğesinde sağlandığında, değer öğesindeki `validate-parameters` değerini `specified-parameter-action` geçersiz kılar. İlke ifadelerine izin verilir.	Yes	Yok
unspecified-parameter-action	API şemasında belirtilmeyen istek parametreleri için gerçekleştirilecek eylem . Bir `headers`veya `query` öğesinde sağlandığında, değeri öğesindeki `validate-parameters` değerini `unspecified-parameter-action` geçersiz kılar. İ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
üst bilgiler	İsteklerdeki belirli adlandırılmış parametreler için varsayılan doğrulama eylemlerini geçersiz kılmak için bu öğeyi ve bir veya daha fazla `parameter` alt öğeyi ekleyin. Parametre API şemasında belirtilirse, bu değer üst düzey `specified-parameter-action` yapılandırmayı geçersiz kılar. Parametre API şemasında belirtilmezse, bu değer üst düzey `unspecified-parameter-action` yapılandırmayı geçersiz kılar.	Hayır
query	İsteklerdeki belirli adlandırılmış sorgu parametreleri için varsayılan doğrulama eylemlerini geçersiz kılmak için bu öğeyi ve bir veya daha fazla `parameter` alt öğeyi ekleyin. Parametre API şemasında belirtilirse, bu değer üst düzey `specified-parameter-action` yapılandırmayı geçersiz kılar. Parametre API şemasında belirtilmezse, bu değer üst düzey `unspecified-parameter-action` yapılandırmayı geçersiz kılar.	Hayır
yol	İsteklerdeki belirli URL yolu parametreleri için varsayılan doğrulama eylemlerini geçersiz kılmak için bu öğeyi ve bir veya daha fazla `parameter` alt öğeyi ekleyin. Parametre API şemasında belirtilirse, bu değer üst düzey `specified-parameter-action` yapılandırmayı geçersiz kılar. Parametre API şemasında belirtilmezse, bu değer üst düzey `unspecified-parameter-action` yapılandırmayı geçersiz kılar.	Hayır

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

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

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.

Örnek

Bu örnekte, tüm sorgu ve yol parametreleri önleme modunda ve üst bilgiler algılama modunda doğrulanır. Doğrulama birkaç üst bilgi parametresi için geçersiz kılınmış:

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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}

İçerik doğrulama

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