Omezení pro import rozhraní API a známé problémy

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Při importu rozhraní API můžete narazit na určitá omezení nebo potřebujete před úspěšným importem identifikovat a opravit problémy. V tomto článku se dozvíte:

  • Chování služby API Management během importu OpenAPI
  • Omezení importu OpenAPI a způsob fungování exportu OpenAPI
  • Požadavky a omezení pro import WSDL a WADL

API Management během importu OpenAPI

Během importu OpenAPI služba API Management:

  • Zkontroluje parametry řetězce dotazu označené jako povinné.
  • Ve výchozím nastavení převede požadované parametry řetězce dotazu na požadované parametry šablony.

Pokud dáváte přednost tomu, aby požadované parametry dotazu ve specifikaci byly přeloženy na parametry dotazu ve službě API Management, zakažte při vytváření rozhraní API na portálu nastavení Zahrnout parametry dotazu do šablon operací. Můžete toho dosáhnout také pomocí rozhraní API – Vytvoření nebo aktualizace rozhraní REST API k nastavení vlastnosti rozhraní API translateRequiredQueryParameters na query.

V případě operací GET, HEAD a OPTIONS služba API Management zahodí parametr textu požadavku, pokud je definovaný ve specifikaci OpenAPI.

Omezení importu OpenAPI/Swaggeru

Pokud při importu dokumentu OpenAPI dojde k chybám, ujistěte se, že jste ho předem ověřili:

  • Použití návrháře na webu Azure Portal (Editor specifikace OpenAPI pro návrh > front-endu > ) nebo
  • S nástrojem třetí strany, jako je Swagger Editor.

Obecné

Požadavky na šablonu adresy URL

Požadavek Popis
Jedinečné názvy požadovaných cest a parametrů dotazu V OpenAPI:
  • Název parametru musí být jedinečný jenom v rámci umístění, například cesta, dotaz nebo hlavička.
Ve službě API Management:
  • Umožňujeme, aby operace byly diskriminovány parametry cesty i dotazu.
  • OpenAPI tuto diskriminaci nepodporuje, proto vyžadujeme, aby názvy parametrů byly jedinečné v rámci celé šablony adresy URL.
Definovaný parametr adresy URL Musí být součástí šablony adresy URL.
Adresa URL dostupného zdrojového souboru Používá se na relativní adresy URL serveru.
\$ref Ukazatele Nejde odkazovat na externí soubory.

Specifikace OpenAPI

Podporované verze

Služba API Management podporuje pouze:

  • OpenAPI verze 2.
  • OpenAPI verze 3.0.x (až 3.0.3).
  • OpenAPI verze 3.1 (jenom import)

Omezení velikosti

Omezení velikosti Popis
Až 4 MB Při importu specifikace OpenAPI do služby API Management.
Velikost požadavku rozhraní API Azure Resource Manageru Pokud je dokument OpenAPI poskytnut prostřednictvím adresy URL umístění přístupného ze služby API Management. Podívejte se na limity předplatného Azure.

Podporovaná rozšíření

Jediná podporovaná rozšíření jsou:

Rozšíření Popis
x-ms-paths
  • Umožňuje definovat cesty, které jsou v adrese URL odlišné podle parametrů dotazu.
  • Probírané v dokumentaci k AutoRestu
x-servers Backport objektu OpenAPI 3 servers pro OpenAPI 2.

Nepodporovaná rozšíření

Rozšíření Popis
Recursion API Management nepodporuje definice definované rekurzivně.
Například schémata, která odkazují na sebe.
Server Objekt Nepodporuje se na úrovni operace rozhraní API.
Produces Klíčové slovo Popisuje typy MIME vrácené rozhraním API.
Nepodporováno

Vlastní rozšíření

  • Při importu se ignorují.
  • Pro export se neukládají ani nezachovávají.

Nepodporované definice

Definice vloženého schématu pro operace rozhraní API se nepodporují. Definice schématu:

  • Jsou definovány v oboru rozhraní API.
  • Lze odkazovat v násadách požadavků na operace rozhraní API nebo v oborech odpovědí.

Ignorované definice

Definice zabezpečení jsou ignorovány.

Omezení definic

Při importu parametrů dotazu se podporuje pouze výchozí metoda serializace pole (style: form, explode: true). Další podrobnosti o parametrech dotazu ve specifikacích OpenAPI najdete ve specifikaci serializace.

Parametry definované v souborech cookie se nepodporují. Zásady můžete dál používat k dekódování a ověřování obsahu souborů cookie.

OpenAPI verze 2

Podpora OpenAPI verze 2 je omezená jenom na formát JSON.

Parametry typu "Formulář" nejsou podporovány. Zásady můžete dál používat k dekódování a ověřování application/x-www-form-urlencoded a application/form-data datových částí.

OpenAPI verze 3.x

API Management podporuje následující verze specifikace:

Adresy URL HTTPS

  • Pokud je zadáno více servers , služba API Management použije první adresu URL HTTPS, která najde.
  • Pokud nejsou žádné adresy URL HTTPS, adresa URL serveru je prázdná.

Podporováno

  • example

Nepodporované

Následující pole jsou součástí OpenAPI verze 3.0.x nebo OpenAPI verze 3.1.x, ale nepodporují se:

Object Pole
OpenAPI externalDocs
Info summary
Komponenty
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operace
  • externalDocs
  • callbacks
  • security
  • servers
Parametr
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Mechanismy importu, aktualizace a exportu OpenAPI

Obecné

Definice rozhraní API exportované ze služby API Management jsou:

  • Primárně určené pro externí aplikace, které potřebují volat rozhraní API hostované ve službě API Management.
  • Nemělo by se importovat do stejné nebo jiné služby API Management.

Informace o správě konfigurací definic rozhraní API v různých službách a prostředích najdete v dokumentaci týkající se používání služby API Management s Gitem.

Přidání nového rozhraní API prostřednictvím importu OpenAPI

Pro každou operaci nalezenou v dokumentu OpenAPI se vytvoří nová operace s:

  • Název prostředku Azure nastavený na operationId.

    • operationId hodnota je normalizována.
    • Pokud operationId není zadána (není k dispozici nebo nullnení prázdná), vygeneruje se hodnota názvu prostředku Azure zkombinováním metody HTTP a šablony cesty.
      • Například get-foo.

  • Zobrazovaný název nastavený na summaryhodnotu .

    • summary Hodnotu:
      • Importovaný tak, jak je.
      • Délka je omezená na 300 znaků.
    • Pokud summary není zadána (není k dispozici, nullnebo je prázdná), hodnota zobrazovaného názvu se nastaví na operationIdhodnotu .

Pravidla normalizace pro operationId

  • Převést na malá písmena
  • Nahraďte každou sekvenci nealnumerických znaků jedinou pomlčkou.
    • Například GET-/foo/{bar}?buzz={quix} je transformován na get-foo-bar-buzz-quix-.
  • Oříznout pomlčky na obou stranách.
    • Například get-foo-bar-buzz-quix- se stane get-foo-bar-buzz-quix
  • Zkracujte tak, aby odpovídal 76 znakům, čtyři znaky menší než maximální limit názvu prostředku.
  • Pro příponu odstranění duplicit použijte zbývající čtyři znaky ve formě -1, -2, ..., -999.

Aktualizace existujícího rozhraní API prostřednictvím importu OpenAPI

Během importu existující operace rozhraní API:

  • Změny odpovídající rozhraní API popsanému v dokumentu OpenAPI
  • Porovná operaci v dokumentu OpenAPI porovnáním její operationId hodnoty s názvem prostředku Azure existující operace.
    • Pokud se najde shoda, vlastnosti existující operace se aktualizují na místě.
    • Pokud se shoda nenajde:
      • Novou operaci vytvoří kombinace metody HTTP a šablony cesty, get-foonapříklad .
      • Pro každou novou operaci se import pokusí zkopírovat zásady z existující operace se stejnou metodou HTTP a šablonou cesty.

Odstraní se všechny existující chybějící operace.

Pokud chcete, aby byl import předvídatelnější, postupujte podle těchto pokynů:

  • Zadejte operationId vlastnost pro každou operaci.
  • Po počátečním importu se neměňte operationId .
  • Nikdy se nemění operationId metoda HTTP ani šablona cesty současně.

Pravidla normalizace pro operationId

  • Převést na malá písmena
  • Nahraďte každou sekvenci nealnumerických znaků jedinou pomlčkou.
    • Například GET-/foo/{bar}?buzz={quix} je transformován na get-foo-bar-buzz-quix-.
  • Oříznout pomlčky na obou stranách.
    • Například get-foo-bar-buzz-quix- se stane get-foo-bar-buzz-quix
  • Zkracujte tak, aby odpovídal 76 znakům, čtyři znaky menší než maximální limit názvu prostředku.
  • Pro příponu odstranění duplicit použijte zbývající čtyři znaky ve formě -1, -2, ..., -999.

Export rozhraní API jako OpenAPI

Pro každou operaci je to:

  • Název prostředku Azure se exportuje jako operationId.
  • Zobrazovaný název se exportuje jako summary.

Všimněte si, že normalizace se provádí při importu operationId , ne při exportu.

WSDL

Pomocí souborů WSDL můžete vytvořit předávací rozhraní SOAP a rozhraní SOAP-to-REST API.

Vazby SOAP

  • Podporují se pouze vazby SOAP stylu kódování "document" a "literal".
  • Nepodporuje se styl rpc ani kódování SOAP.

Importy a zahrnutí

  • Direktivy wsdl:import, xsd:importa xsd:include direktivy nejsou podporovány. Místo toho sloučíte závislosti do jednoho dokumentu.

  • Opensourcový nástroj pro překlad a sloučení wsdl:importxsd:importa xsd:include závislosti v souboru WSDL najdete v tomto úložišti GitHubu.

Specifikace WS-*

Soubory WSDL obsahující specifikace WS-* nejsou podporovány.

Zprávy s více částmi

Tento typ zprávy není podporován.

WCF wsHttpBinding

  • Služby SOAP vytvořené pomocí služby Windows Communication Foundation by měly používat basicHttpBinding.
  • wsHttpBinding není podporováno.

MTOM

  • Služby, které používají MTOM, můžou fungovat.
  • Oficiální podpora se v tuto chvíli nenabízí.

Rekurze

  • Api Management nepodporuje rekurzivní typy definované rekurzivně.
  • Například odkazovat na pole sebe sama.

Více oborů názvů

V rámci schématu lze použít více oborů názvů, ale k definování částí zpráv lze použít pouze cílový obor názvů. Tyto obory názvů slouží k definování jiných vstupních nebo výstupních prvků.

Při exportu se nezachovají jiné obory názvů než cíl. I když můžete importovat dokument WSDL definující části zpráv s jinými obory názvů, všechny části zpráv budou mít cílový obor názvů WSDL při exportu.

Více koncových bodů

Soubory WSDL mohou definovat více služeb a koncových bodů (porty) jedním nebo více wsdl:servicewsdl:port prvky. Brána služby API Management ale dokáže importovat a proxy požadavky pouze na jednu službu a koncový bod. Pokud je v souboru WSDL definováno více služeb nebo koncových bodů, identifikujte název cílové služby a koncový bod při importu rozhraní API pomocí vlastnosti wsdlSelector .

Tip

Pokud chcete vyrovnávat zatížení požadavků napříč několika službami a koncovými body, zvažte konfiguraci back-endového fondu s vyrovnáváním zatížení.

Pole

Transformace SOAP-to-REST podporuje pouze zabalená pole zobrazená v následujícím příkladu:

    <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

V současné době neexistují žádné známé problémy s importem WADL.