Aracılığıyla paylaş

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

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 özelliğini translateRequiredQueryParameters olarak ayarlamak için query REST API'sini kullanarak da bu ayarı yapabilirsiniz.

GET, HEAD ve OPTIONS işlemleri için API Management, OpenAPI belirtiminde tanımlanmışsa istek gövdesi parametresini yok sayar.

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

OpenAPI belgenizi içeri aktarırken hata alırsanı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 İşaretçiler Dış dosyalara başvurulamıyor.
En Fazla URL Uzunluğu API URL'si 128 karakterden kısa olmalıdır.

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
x-servers OpenAPI 3 servers nesnesinin OpenAPI 2'ye geri aktarımı.

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 sözcük 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 parametrelerini içeri aktardığınızda, 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.

Çerezlerde 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:

Nesne Alan
OpenAPI externalDocs
Bilgi summary
Bileşen
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
Yol Öğesi
  • trace
  • servers
İşlem
  • externalDocs
  • callbacks
  • security
  • servers
  • deprecated
Parametre
  • allowEmptyValue
  • style
  • explode
  • allowReserved
  • deprecated
Sunucu şablonu oluşturma
  • API Server and Base URL

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, operationIdveya boşsanull), 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.
  • Alfanümerik 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 olur.
  • 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.
  • Gerekirse, yinelenmeleri kaldırma son eki olarak kullanmak için kalan dört karakteri -1, -2, ..., -999 biçiminde 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 var olan bir işlemden ilke kopyalamaya çalışır.

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.
  • Alfanümerik 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.
  • Gerekirse, yinelenmeleri kaldırma son eki olarak kullanmak için kalan dört karakteri -1, -2, ..., -999 biçiminde 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 operationId dışa aktarmada değil, içe aktarmada yapılır.

WSDL (İngilizce)

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

SOAP bağlamaları

  • Yalnızca "belge" ve "literal" kodlama stiline sahip 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ındaki wsdl:import, xsd:import ve xsd:include bağımlılıklarını çözümlemek ve birleştirmek için açık kaynaklı bir araç arıyorsanız, 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ü desteklenmez.

WCF wsHttpBinding

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

MTOM (MTOM)

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

Özyineleme

  • API Management özyinelemeli olarak tanımlanan türleri desteklemez.
  • Ö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 API'leri ve ara sunucu isteklerini yalnızca tek bir hizmete ve uç noktaya 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

Birden fazla hizmet ve uç nokta arasında istekleri yük dengelemek istiyorsanız, bir yük dengeli arka uç havuzu yapılandırmayı düşünün.

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 (Türkçe)

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

  • Last updated on