Parametreleri doğrulama
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-preview
validate-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. |
önlemek | İ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, çalışma alanı
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ı Application Insights'a 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} |
İlgili ilkeler
İlgili içerik
İlkelerle çalışma hakkında daha fazla bilgi için bkz: