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-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, queryveya 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 headersveya 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

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}

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