Aracılığıyla paylaş

API içeri aktarma kısıtlamaları ve bilinen sorunlar

  • Makale

UYGULANANLAR: Tüm API Management katmanları

BIR API'yi içeri aktarırken bazı kısıtlamalarla karşılaşabilir veya başarıyla içeri aktarabilmek için önce sorunları tanımlamanız ve düzeltmeniz gerekebilir. Bu makalede şunları öğreneceksiniz:

  • API Management'ın OpenAPI içeri aktarma sırasındaki davranışı.
  • OpenAPI içeri aktarma sınırlamaları ve OpenAPI dışarı aktarmanın çalışma şekli.
  • WSDL ve WADL içeri aktarma gereksinimleri ve sınırlamaları.

OpenAPI içeri aktarma sırasında API Management

OpenAPI içeri aktarma sırasında API Management:

  • Özellikle, gerekli olarak işaretlenmiş sorgu dizesi parametrelerini denetler.
  • Varsayılan olarak, gerekli sorgu dizesi parametrelerini gerekli şablon parametrelerine dönüştürür.

Belirtimdeki gerekli sorgu parametrelerinin API Management'taki sorgu parametrelerine çevrilmesi tercih ediyorsanız, portalda API'yi oluştururken sorgu parametrelerini işlem şablonlarına ekle ayarını devre dışı bırakın. Api'nin translateRequiredQueryParameters özelliğini queryolarak ayarlamak için API'leri - REST API'sini Oluştur veya Güncelleştir'i kullanarak da bunu gerçekleştirebilirsiniz.

GET, HEAD ve OPTIONS işlemleri için API Management, OpenAPI belirtiminde tanımlanmışsa bir istek gövdesi parametresi atar.

OpenAPI/Swagger içeri aktarma sınırlamaları

OpenAPI belgenizi içeri aktarırken hata alıyorsanız, aşağıdakilerden birini yaparak belgeyi önceden doğruladığınızdan emin olun:

  • Tasarımcıyı Azure portalında kullanma (Tasarım > Ön Ucu > OpenAPI Belirtimi Düzenleyicisi) veya
  • Swagger Editor gibi bir üçüncü taraf aracıyla.

Genel

URL şablonu gereksinimleri

Gereksinim Açıklama
Gerekli yol ve sorgu parametreleri için benzersiz adlar OpenAPI'de:
  • Parametre adının yalnızca yol, sorgu, üst bilgi gibi bir konumda benzersiz olması gerekir.
API Management'ta:
  • İşlemlerin hem yol hem de sorgu parametreleri tarafından ayrımcılığa uğramasına izin veririz.
  • OpenAPI bu ayrımcılığı desteklemediğinden, parametre adlarının URL şablonunun tamamında benzersiz olmasını gerektirir. Adlar büyük/küçük harfe duyarlı değildir.
Tanımlı URL parametresi URL şablonunun bir parçası olmalıdır.
Kullanılabilir kaynak dosya URL'si Göreli sunucu URL'lerine uygulanır.
\$ref Işaretçi Dış dosyalara başvurulamıyor.

OpenAPI belirtimleri

Desteklenen sürümler

API Management yalnızca şunları destekler:

  • OpenAPI sürüm 2.
  • OpenAPI sürüm 3.0.x (sürüm 3.0.3'e kadar).
  • OpenAPI sürüm 3.1 (yalnızca içeri aktarma)

Boyut sınırlamaları

Boyut sınırı Açıklama
4 MB'a kadar OpenAPI belirtimi, API Management'a satır içi olarak içeri aktarıldığında.
Azure Resource Manager API istek boyutu Bir OpenAPI belgesi, API Management hizmetinizden erişilebilen bir konumun URL'si aracılığıyla sağlandığında. Bkz. Azure abonelik sınırları.

Desteklenen uzantılar

Desteklenen tek uzantılar şunlardır:

Dahili Açıklama
x-ms-paths
  • URL'deki sorgu parametrelerine göre ayırt edilen yollar tanımlamanıza olanak tanır.
  • AutoRest belgelerinde ele alınmıştır.
x-servers OpenAPI 2 için OpenAPI 3 servers nesnesinin arka penceresi.

Desteklenmeyen uzantılar

Dahili Açıklama
Recursion API Management özyinelemeli olarak tanımlanan tanımları desteklemez.
Örneğin, kendilerine başvuran şemalar.
Server Nesne API işlem düzeyinde desteklenmez.
Produces Anahtar kelime API tarafından döndürülen MIME türlerini açıklar.
Desteklenmiyor.

Özel uzatmalar

  • İçeri aktarmada yoksayılır.
  • Dışarı aktarma için kaydedilmez veya korunmaz.

Desteklenmeyen tanımlar

API işlemleri için satır içi şema tanımları desteklenmez. Şema tanımları:

  • API kapsamında tanımlanır.
  • API işlemleri isteğinde veya yanıt kapsamlarında başvurulabilir.

Yoksayılan tanımlar

Güvenlik tanımları yoksayılır.

Tanım kısıtlamaları

Sorgu parametreleri içeri aktarılırken yalnızca varsayılan dizi serileştirme yöntemi (style: form, explode: true) desteklenir. OpenAPI belirtimlerindeki sorgu parametreleri hakkında daha fazla bilgi için serileştirme belirtimine bakın.

Tanımlama bilgilerinde tanımlanan parametreler desteklenmez. Tanımlama bilgilerinin içeriğini çözmek ve doğrulamak için ilkeyi kullanmaya devam edebilirsiniz.

OpenAPI sürüm 2

OpenAPI sürüm 2 desteği yalnızca JSON biçimiyle sınırlıdır.

"Form" türü parametreleri desteklenmez. Kodu çözmek, doğrulamak ve yükleri doğrulamak application/x-www-form-urlencodedapplication/form-data için ilkeyi kullanmaya devam edebilirsiniz.

OpenAPI sürüm 3.x

API Management aşağıdaki belirtim sürümlerini destekler:

HTTPS URL'leri

  • Birden çok servers belirtilirse, API Management bulduğu ilk HTTPS URL'sini kullanır.
  • HERHANGI bir HTTPS URL'si yoksa, sunucu URL'si boş olur.

Desteklenir

  • example

Desteklenmeyen

Aşağıdaki alanlar OpenAPI sürüm 3.0.x veya OpenAPI sürüm 3.1.x'e eklenmiştir, ancak desteklenmez:

Object Alan
OpenAPI externalDocs
Bilgi summary
Bileşenler
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
Pathıtem
  • trace
  • servers
İşlem
  • externalDocs
  • callbacks
  • security
  • servers
Parametre
  • allowEmptyValue
  • style
  • explode
  • allowReserved

OpenAPI içeri aktarma, güncelleştirme ve dışarı aktarma mekanizmaları

Genel

API Management hizmetinden dışarı aktarılan API tanımları şunlardır:

  • Öncelikli olarak API Management hizmetinde barındırılan API'yi çağırması gereken dış uygulamalara yöneliktir.
  • Aynı veya farklı API Management hizmetine içeri aktarılması amaçlanmamıştır.

Api tanımlarının farklı hizmetler/ortamlar arasında yapılandırma yönetimi için Git ile API Management hizmetini kullanmayla ilgili belgelere bakın.

OpenAPI içeri aktarma yoluyla yeni API ekleme

OpenAPI belgesinde bulunan her işlem için aşağıdakilerle yeni bir işlem oluşturulur:

  • Azure kaynak adı olarak operationIdayarlanır.

    • operationId değeri normalleştirilir.
    • Belirtilmezse (mevcut değilse, nullveya boşsaoperationId), HTTP yöntemi ve yol şablonu birleştirilerek Azure kaynak adı değeri oluşturulur.
      • Örneğin, get-foo.

  • Görünen ad olarak summaryayarlanır.

    • summary Değer:
      • Olduğu gibi içeri aktarıldı.
      • Uzunluk 300 karakterle sınırlıdır.
    • Belirtilmezse summary (mevcut değilse, nullveya boşsa), görünen ad değeri olarak operationIdayarlanır.

için normalleştirme kuralları operationId

  • Küçük harfe dönüştürün.
  • Alfasayısal olmayan karakterlerin her dizisini tek bir tireyle değiştirin.
    • Örneğin, GET-/foo/{bar}?buzz={quix} içine get-foo-bar-buzz-quix-dönüştürülür.
  • Her iki tarafta da tireleri kırpın.
    • Örneğin, get-foo-bar-buzz-quix-get-foo-bar-buzz-quix
  • Bir kaynak adı için en fazla sınırdan dört karakter daha az olmak üzere 76 karakter sığacak şekilde kırpın.
  • Yinelenenleri kaldırma soneki için gerekirse biçiminde -1, -2, ..., -999kalan dört karakteri kullanın.

OpenAPI içeri aktarma yoluyla mevcut BIR API'yi güncelleştirme

İçeri aktarma sırasında mevcut API işlemi:

  • OpenAPI belgesinde açıklanan API ile eşleşecek değişiklikler.
  • Değerini mevcut işlemin Azure kaynak adıyla karşılaştırarak OpenAPI belgesindeki bir işlemle eşleşir operationId .
    • Eşleşme bulunursa, mevcut işlemin özellikleri "yerinde" güncelleştirilir.
    • Eşleşme bulunamazsa:
      • HTTP yöntemi ve yol şablonu birleştirilerek yeni bir işlem oluşturulur; örneğin, get-foo.
      • Her yeni işlem için içeri aktarma işlemi, aynı HTTP yöntemi ve yol şablonuyla mevcut bir işlemden ilke kopyalamayı dener.

Tüm mevcut eşleşmeyen işlemler silinir.

İçeri aktarmayı daha öngörülebilir hale getirmek için şu yönergeleri izleyin:

  • Her işlem için özellik belirtin operationId .
  • İlk içeri aktarma işleminden sonra değişiklik yapmaktan operationId kaçının.
  • Hiçbir zaman ve HTTP yöntemi veya yol şablonunu aynı anda değiştirmeyin operationId .

için normalleştirme kuralları operationId

  • Küçük harfe dönüştürün.
  • Alfasayısal olmayan karakterlerin her dizisini tek bir tireyle değiştirin.
    • Örneğin, GET-/foo/{bar}?buzz={quix} içine get-foo-bar-buzz-quix-dönüştürülür.
  • Her iki tarafta da tireleri kırpın.
    • Örneğin, get-foo-bar-buzz-quix-get-foo-bar-buzz-quix
  • Bir kaynak adı için en fazla sınırdan dört karakter daha az olmak üzere 76 karakter sığacak şekilde kırpın.
  • Yinelenenleri kaldırma soneki için gerekirse biçiminde -1, -2, ..., -999kalan dört karakteri kullanın.

API'leri OpenAPI olarak dışarı aktarma

Her işlem için şu şekildedir:

  • Azure kaynak adı olarak operationIddışarı aktarılır.
  • Görünen ad olarak summarydışarı aktarılır.

normalleştirme işleminin operationId dışarı aktarmada değil, içeri aktarmada yapıldığını unutmayın.

WSDL

WSDL dosyalarıyla SOAP doğrudan ve SOAP-REST API'leri oluşturabilirsiniz.

SOAP bağlamaları

  • Yalnızca "belge" ve "değişmez değer" kodlama stilinin SOAP bağlamaları desteklenir.
  • "rpc" stili veya SOAP Kodlama desteği yok.

İçeri aktarmalar ve eklemeler

  • wsdl:import, xsd:importve xsd:include yönergeleri desteklenmez. Bunun yerine bağımlılıkları tek bir belgede birleştirin.

  • WSDL dosyasında , xsd:importve bağımlılıklarını çözümlemek ve xsd:include birleştirmek wsdl:importiçin açık kaynak bir araç için bu GitHub deposuna bakın.

WS-* belirtimleri

WS-* belirtimlerini içeren WSDL dosyaları desteklenmez.

Birden çok bölümü olan iletiler

Bu ileti türü desteklenmiyor.

WCF wsHttpBinding

  • Windows Communication Foundation ile oluşturulan SOAP hizmetleri kullanmalıdır basicHttpBinding.
  • wsHttpBinding desteklenmez.

MTOM

  • kullanan MTOMhizmetler çalışabilir .
  • Şu anda resmi destek sunulmaz.

Özyineleme

  • Özyinelemeli olarak tanımlanan türler API Management tarafından desteklenmez.
  • Örneğin, kendi dizilerine bakın.

Birden çok ad alanı

Şemada birden çok ad alanı kullanılabilse de, ileti bölümlerini tanımlamak için yalnızca hedef ad alanı kullanılabilir. Bu ad alanları, diğer giriş veya çıkış öğelerini tanımlamak için kullanılır.

Hedef dışındaki ad alanları dışarı aktarmada korunmaz. İleti bölümlerini diğer ad alanlarıyla tanımlayan bir WSDL belgesini içeri aktarabilirsiniz ancak tüm ileti bölümlerinde dışarı aktarma sırasında WSDL hedef ad alanı bulunur.

Birden çok uç nokta

WSDL dosyaları, bir veya daha fazla wsdl:service öğeye göre birden çok hizmet ve wsdl:port uç nokta (bağlantı noktası) tanımlayabilir. Ancak API Management ağ geçidi, istekleri yalnızca tek bir hizmete ve uç noktaya aktarıp ara sunucuya aktarabiliyor. WSDL dosyasında birden çok hizmet veya uç nokta tanımlanmışsa, wsdlSelector özelliğini kullanarak API'yi içeri aktarırken hedef hizmet adını ve uç noktayı tanımlayın.

İpucu

İstekleri birden çok hizmet ve uç nokta arasında yük dengelemek istiyorsanız yük dengeli bir arka uç havuzu yapılandırmayı göz önünde bulundurun.

Diziler

SOAP-REST dönüşümü yalnızca aşağıdaki örnekte gösterilen sarmalanmış dizileri destekler:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

Şu anda bilinen WADL içeri aktarma sorunu yoktur.