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

  • Cikk

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 közben az API Management:

  • Kifejezetten kötelezőként megjelölt lekérdezésisztring-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. Ezt az API-k – REST API létrehozása vagy frissítése használatával is elvégezheti az API tulajdonságának translateRequiredQueryParameters beállításáhozquery.

GET, HEAD és OPTIONS műveletek esetén az API Management elvet egy kérelem törzsparamétert, 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:

  • A tervező használata az Azure Portalon (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.
Definiált URL-paraméter Az URL-sablon részét kell képeznie.
Elérhető forrásfájl URL-címe Relatív kiszolgáló URL-címére 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 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:

Mellék 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ója.
x-servers Az OpenAPI 2 OpenAPI 3 servers objektumánakháttérportja.

Nem támogatott bővítmények

Mellék 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 Objektum 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

  • A rendszer figyelmen kívül hagyja az importáláskor.
  • A program nem menti vagy nem őrzi meg 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űveleti kéréseiben vagy válasz hatóköreiben hivatkozhat gombra.

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 a kódoláshoz, valamint a hasznos adatok ellenőrzéséhez és application/form-data ellenőrzéséhezapplication/x-www-form-urlencoded.

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

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
Info summary
Összetevők
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Művelet
  • externalDocs
  • callbacks
  • security
  • servers
Paraméter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

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.

  • Megjelenítendő név beállítása a következőre summary: .

    • summary Érték:
      • Importálva is.
      • 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} átalakítja a következővé get-foo-bar-buzz-quix-: .
  • Vágja le a kötőjeleket mindkét oldalon.
    • Például: get-foo-bar-buzz-quix-get-foo-bar-buzz-quix
  • A csonkolási érték 76 karakterből áll, négy karakterrel kevesebb, mint egy erőforrásnév maximális korlátja.
  • Ha szükséges -1, -2, ..., -999, használjon további négy karaktert a duplikálás megszüntetéséhez.

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űvelet 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 operationId egyszerre a HTTP-metódust vagy 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} átalakítja a következővé get-foo-bar-buzz-quix-: .
  • Vágja le a kötőjeleket mindkét oldalon.
    • Például: get-foo-bar-buzz-quix-get-foo-bar-buzz-quix
  • A csonkolási érték 76 karakterből áll, négy karakterrel kevesebb, mint egy erőforrásnév maximális korlátja.
  • Ha szükséges -1, -2, ..., -999, használjon további négy karaktert a duplikálás megszüntetéséhez.

API exportálása OpenAPI-ként

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

  • Az Azure-erőforrásnév exportálása operationId.
  • A megjelenítendő név exportálása summary.

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

WSDL

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

SOAP-kötések

  • 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 az irányelvek nem támogatottak. Ehelyett egyesítse a függőségeket egy dokumentumba.

  • A WSDL-fájlokban lévő, nyílt forráskódú eszközök megoldásához és xsd:include egyesítéséhez wsdl:importxsd:importtekintse meg ezt a GitHub-adattárat.

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 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 tudja importálni és proxykérelmeket importálni. 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.