İç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.

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.

İ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" case-insensitive-property-names="true | false"/>
</validate-content>

Özellikler

Öğeler

content-type-map öznitelikleri

content-type-map-elements

içerik öznitelikleri

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:

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, çalışma alanı

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.

İç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.

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

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

İ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'da Microsoft Copilot kullanarak ilke yazma