Megosztás a következőn keresztül:

API-importálási korlátozások és ismert problémák

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

Az API importálása során előfordulhat, hogy korlátozásokat tapasztal, vagy azonosítania és kijavítania kell a problémákat, mielőtt sikeresen importálhatná azokat. Ebben a cikkben a következőt fogja elsajátítani:

  • Az API Management viselkedése az OpenAPI-importálás során.
  • Az OpenAPI importálási korlátozásai és az OpenAPI-exportálás működése.
  • A WSDL- és WADL-importálásra vonatkozó követelmények és korlátozások.

API Management az OpenAPI importálása során

Az OpenAPI-importálás során az API Management:

  • Kifejezetten kötelezőként megjelölt lekérdezési string-paramétereket keres.
  • Alapértelmezés szerint a szükséges lekérdezési sztringparamétereket a szükséges sablonparaméterekké alakítja.

Ha azt szeretné, hogy a specifikációban szereplő szükséges lekérdezési paraméterek le legyenek fordítva a lekérdezési paraméterekre az API Managementben, tiltsa le a Lekérdezési paraméterek belefoglalása műveletsablonok beállításba az API portálon való létrehozásakor. Az API „Létrehozás vagy frissítés” REST API-jának használatával is elvégezheti ezt, ha az API translateRequiredQueryParameters tulajdonságát query-re állítja.

GET, HEAD és OPTIONS műveletek esetén az API Management elveti a kérelem törzsparaméterét, ha az OpenAPI-specifikációban van definiálva.

OpenAPI/Swagger importálási korlátozások

Ha hibaüzenetet kap az OpenAPI-dokumentum importálása közben, ellenőrizze, hogy korábban ellenőrizte-e a dokumentumot az alábbiak valamelyikével:

  • Az Azure Portalon lévő tervező használata (Design > Front End > OpenAPI Specification Editor), vagy
  • Külső eszközzel, például Swagger Editorral.

Általános

AZ URL-sablon követelményei

Követelmény Leírás
A szükséges elérési utak és lekérdezési paraméterek egyedi nevei Az OpenAPI-ban:
  • A paraméternévnek csak egy helyen belül kell egyedinek lennie, például elérési útnak, lekérdezésnek, fejlécnek.
Az API Managementben:
  • Lehetővé tesszük, hogy a műveleteket az elérési út és a lekérdezési paraméterek megkülönböztetik.
  • Az OpenAPI nem támogatja ezt a megkülönböztetést, ezért a paraméterneveknek egyedinek kell lenniük a teljes URL-sablonban. A nevek nem érzékenyek a kis- és nagybetűkre.
Definiált URL-paraméter Az URL-sablon részét kell képeznie.
Elérhető forrásfájl URL-címe Relatív szerver URL-ekre alkalmazva.
\$ref Mutatók Nem lehet külső fájlokra hivatkozni.

OpenAPI-specifikációk

Támogatott verziók

Az API Management csak a következőket támogatja:

  • OpenAPI 2-es verzió
  • OpenAPI 3.0.x-es verzió (a 3.0.3-ig)
  • OpenAPI 3.1-es verzió (csak importálás)

Méretkorlátozások

Méretkorlát Leírás
Legfeljebb 4 MB OpenAPI-specifikáció beágyazott importálása az API Managementbe.
Az Azure Resource Manager API kérésmérete Ha egy OpenAPI-dokumentumot egy URL-címen keresztül ad meg egy, az API Management szolgáltatásból elérhető helyre. Tekintse meg az Azure-előfizetés korlátait.

Támogatott bővítmények

Az egyetlen támogatott bővítmények a következők:

Kiterjesztés Leírás
x-ms-paths
  • Lehetővé teszi az URL-ben található lekérdezési paraméterek által megkülönböztetett elérési utak meghatározását.
  • Az AutoRest dokumentációban található.
x-servers Az OpenAPI 3 objektum visszaportolása az OpenAPI 2-höz.

Nem támogatott bővítmények

Kiterjesztés Leírás
Recursion Az API Management nem támogatja a rekurzívan definiált definíciókat.
Például a sémák magukra hivatkoznak.
Server tárgy Az API-művelet szintjén nem támogatott.
Produces kulcsszó Az API által visszaadott MIME-típusokat ismerteti.
Nem támogatott.

Egyéni bővítmények

  • Az importáláskor figyelmen kívül maradnak.
  • Nincsenek mentve vagy megőrizve exportálásra.

Nem támogatott definíciók

Az API-műveletek beágyazott sémadefiníciói nem támogatottak. Sémadefiníciók:

  • Az API-hatókörben vannak definiálva.
  • Az API műveletek kérésének vagy válaszának hatókörében hivatkozhat.

Figyelmen kívül hagyott definíciók

A rendszer figyelmen kívül hagyja a biztonsági definíciókat.

Definíciós korlátozások

Lekérdezési paraméterek importálásakor csak az alapértelmezett tömb szerializálási módszer (style: form, explode: true) támogatott. Az OpenAPI-specifikációk lekérdezési paramétereivel kapcsolatos további részletekért tekintse meg a szerializálási specifikációt.

A cookie-kban definiált paraméterek nem támogatottak. Továbbra is használhatja a szabályzatot a cookie-k tartalmának dekódolására és ellenőrzésére.

OpenAPI 2-es verzió

Az OpenAPI 2-es verziójának támogatása csak JSON-formátumra korlátozódik.

Az "Űrlap" típusú paraméterek nem támogatottak . A szabályzatot továbbra is használhatja application/x-www-form-urlencoded és application/form-data hasznos adatok dekódolásához és ellenőrzéséhez.

OpenAPI 3.x-es verzió

Az API Management a következő specifikációs verziókat támogatja:

HTTPS URL-címek

  • Ha több servers van megadva, az API Management az első megtalált HTTPS-URL-címet fogja használni.
  • Ha nincsenek HTTPS URL-címek, a kiszolgáló URL-címe üres.

Támogatott

  • example

Nem támogatott

A következő mezők az OpenAPI 3.0.x vagy az OpenAPI 3.1.x-es verziójában találhatók, de nem támogatottak:

Objektum Mező
OpenAPI externalDocs
Információ summary
Összetevők
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
Elérési út
  • trace
  • servers
Művelet
  • externalDocs
  • callbacks
  • security
  • servers
Paraméter
  • allowEmptyValue
  • style
  • explode
  • allowReserved
Kiszolgálói sablonozás
  • API Server and Base URL

OpenAPI importálási, frissítési és exportálási mechanizmusok

Általános

Az API Management szolgáltatásból exportált API-definíciók a következők:

  • Elsősorban olyan külső alkalmazásokhoz készült, amelyeknek meg kell hívniuk az API Management szolgáltatásban üzemeltetett API-t.
  • Nem importálható ugyanabba a vagy más API Management szolgáltatásba.

Az API-definíciók különböző szolgáltatások/környezetek közötti konfigurálásához tekintse meg az API Management szolgáltatás Gittel való használatával kapcsolatos dokumentációt.

Új API hozzáadása OpenAPI-importáláson keresztül

Az OpenAPI-dokumentumban található minden művelethez létrejön egy új művelet a következőkkel:

  • Az Azure-erőforrás neve a következőre operationIdvan állítva: .

    • operationId az érték normalizálva van.
    • Ha operationId nincs megadva (nem jelenik meg vagy nullüres), az Azure-erőforrásnév-érték a HTTP-metódus és az elérésiút-sablon kombinálásával jön létre.
      • Például: get-foo.

  • A megjelenítendő név beállítva summary.

    • summary érték:
      • Importálva változtatás nélkül.
      • A hossz legfeljebb 300 karakter hosszúságú lehet.
    • Ha summary nincs megadva (nincs megadva, nullvagy üres), a megjelenítendő név értéke a következő lesz operationId: .

Normalizálási szabályok a következőhöz: operationId

  • Konvertálás kisbetűssé.
  • Cserélje le a nem alfanumerikus karakterek sorozatait egyetlen kötőjelre.
    • Például GET-/foo/{bar}?buzz={quix} átalakul get-foo-bar-buzz-quix--vé.
  • Vágja le a kötőjeleket mindkét oldalon.
    • Például: get-foo-bar-buzz-quix- válik get-foo-bar-buzz-quix
  • Rövidítse 76 karakterre, ami négy karakterrel kevesebb, mint egy erőforrásnév maximális határa.
  • Ha szükséges, használjon egy további négy karakterből álló utótagot a duplikáció elkerülésére -1, -2, ..., -999 alakban.

Meglévő API frissítése OpenAPI-importáláson keresztül

Az importálás során a meglévő API-művelet:

  • Az OpenAPI-dokumentumban leírt API-val megegyező módosítások.
  • Megegyezik az OpenAPI-dokumentumban lévő művelettel úgy, hogy annak operationId értékét összehasonlítja a meglévő művelet Azure-erőforrás nevével.
    • Ha talál egyezést, a meglévő műveletnek a tulajdonságai helyben frissülnek.
    • Ha nem található egyezés:
      • Egy új művelet jön létre a HTTP-metódus és az elérésiút-sablon kombinálásával, például get-foo.
      • Minden új művelet esetében az importálás megkísérli a szabályzatok másolását egy meglévő műveletből ugyanazzal a HTTP-metódussal és elérésiút-sablonnal.

A rendszer minden meglévő nem egyező műveletet töröl.

Az importálás kiszámíthatóbbá tétele érdekében kövesse az alábbi irányelveket:

  • Minden művelethez adjon meg operationId tulajdonságot.
  • A kezdeti importálás után tartózkodjon a módosítástól operationId .
  • Soha ne módosítsa egyszerre a operationId, valamint a HTTP-metódust és az elérési út sablont.

Normalizálási szabályok a következőhöz: operationId

  • Konvertálás kisbetűssé.
  • Cserélje le a nem alfanumerikus karakterek sorozatait egyetlen kötőjelre.
    • Például GET-/foo/{bar}?buzz={quix} átalakul get-foo-bar-buzz-quix--vé.
  • Vágja le a kötőjeleket mindkét oldalon.
    • Például: get-foo-bar-buzz-quix- válik get-foo-bar-buzz-quix
  • Rövidítse 76 karakterre, ami négy karakterrel kevesebb, mint egy erőforrásnév maximális határa.
  • Ha szükséges, használjon egy további négy karakterből álló utótagot a duplikáció elkerülésére -1, -2, ..., -999 alakban.

API exportálása OpenAPI-ként

Minden művelet esetében a következő:

  • Az Azure-erőforrásnév exportálva mint operationId.
  • A megjelenítendő nevet summary formátumban exportálják.

Vegye figyelembe, hogy a operationId normalizálása importáláskor történik, és nem exportáláskor.

WSDL

A SOAP átmenő és SOAP-to-REST API-kat WSDL-fájlokkal is létrehozhatja.

SOAP összekapcsolások

  • Csak a "document" és a "literál" kódolási stílusú SOAP-kötések támogatottak.
  • Nem támogatott az "rpc" stílus vagy a SOAP-kódolás.

Import és beleértendő

  • A wsdl:import, xsd:import és xsd:include irányelvek nem támogatottak. Ehelyett egyesítse a függőségeket egy dokumentumba.

  • Tekintse meg ezt a wsdl:import, ha egy nyílt forráskódú eszközt keres a xsd:import, xsd:include, és függőségek feloldásához és egyesítéséhez egy WSDL fájlban.

WS-* specifikációk

A WS-* specifikációkat tartalmazó WSDL-fájlok nem támogatottak.

Több részből álló üzenetek

Ez az üzenettípus nem támogatott.

WCF wsHttpBinding

  • A Windows Communication Foundation szolgáltatással létrehozott SOAP-szolgáltatásoknak a következőt kell használniuk basicHttpBinding:
  • wsHttpBinding nem támogatott.

MTOM

  • A használt MTOMszolgáltatások működhetnek .
  • A hivatalos támogatást jelenleg nem kínáljuk.

Rekurzió

  • A rekurzívan definiált típusokat az API Management nem támogatja.
  • Hivatkozzon például egy önmagát tartalmazó tömbre.

Több névtér

Bár egy sémában több névtér is használható, csak a célnévtér használható üzenetrészek definiálására. Ezek a névterek más bemeneti vagy kimeneti elemek definiálására szolgálnak.

A céltól eltérő névterek exportáláskor nem maradnak meg. Bár importálhat egy WSDL-dokumentumot, amely más névterekkel rendelkező üzenetrészeket határoz meg, az összes üzenetrészen megjelenik a WSDL-célnévtér exportálása.

Több végpont

A WSDL-fájlok több szolgáltatást és végpontot (portot) definiálhatnak egy vagy több wsdl:service elem alapján wsdl:port . Az API Management-átjáró azonban csak egyetlen szolgáltatásra és végpontra tud kérelmeket importálni és proxyzni. Ha több szolgáltatás vagy végpont van definiálva a WSDL-fájlban, a wsdlSelector tulajdonság használatával azonosítsa a célszolgáltatás nevét és végpontot az API importálásakor.

Tipp

Ha több szolgáltatás és végpont közötti terheléselosztási kérelmeket szeretne kiosztani, érdemes lehet konfigurálni egy elosztott terhelésű háttérkészletet.

Tömbök

A SOAP-to-REST átalakítás csak az alábbi példában látható burkolt tömböket támogatja:

    <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

Jelenleg nincsenek ismert WADL-importálási problémák.