Dela via

API-importbegränsningar och kända problem

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

När du importerar ett API kan du stöta på vissa begränsningar eller behöva identifiera och åtgärda problem innan du kan importera. I den här artikeln får du lära dig:

  • API Managements beteende under OpenAPI-import.
  • OpenAPI-importbegränsningar och hur OpenAPI-export fungerar.
  • Krav och begränsningar för WSDL- och WADL-import.

API Management under OpenAPI-import

Under OpenAPI-import gör API Management följande:

  • Söker specifikt efter frågesträngsparametrar som har markerats som obligatoriska.
  • Som standard konverterar de obligatoriska frågesträngsparametrarna till nödvändiga mallparametrar.

Om du föredrar att obligatoriska frågeparametrar i specifikationen översätts till frågeparametrar i API Management inaktiverar du inställningen Inkludera frågeparametrar i åtgärdsmallar när du skapar API:et i portalen. Du kan också göra detta genom att använda API:erna – Skapa eller uppdatera REST API för att ange API:ets translateRequiredQueryParameters egenskap till query.

För GET-, HEAD- och OPTIONS-åtgärder tar API Management bort en parameter för begärandetext om den definieras i OpenAPI-specifikationen.

Importbegränsningar för OpenAPI/Swagger

Om du får fel när du importerar ditt OpenAPI-dokument kontrollerar du att du har verifierat det i förväg genom att antingen:

  • Använda designern i Azure-portalen (Design > Front End > OpenAPI Specification Editor) eller
  • Med ett verktyg från tredje part, till exempel Swagger Editor.

Allmänt

Krav för URL-mall

Krav Beskrivning
Unika namn för sökväg och frågeparametrar som krävs I OpenAPI:
  • Ett parameternamn behöver bara vara unikt på en plats, till exempel sökväg, fråga, rubrik.
I API Management:
  • Vi tillåter att åtgärder diskrimineras av både sökvägs- och frågeparametrar.
  • OpenAPI stöder inte den här diskrimineringen, så vi kräver att parameternamn är unika i hela URL-mallen. Namn är skiftlägesokänsliga.
Definierad URL-parameter Måste vara en del av URL-mallen.
Url för tillgänglig källfil Tillämpas på relativa server-URL:er.
\$ref Pekare Det går inte att referera till externa filer.

OpenAPI-specifikationer

Versioner som stöds

API Management stöder endast:

  • OpenAPI version 2.
  • OpenAPI version 3.0.x (upp till version 3.0.3).
  • OpenAPI version 3.1 (endast import)

Storleksbegränsningar

Storleksgräns beskrivning
Upp till 4 MB När en OpenAPI-specifikation importeras infogat till API Management.
Storlek på Azure Resource Manager API-begäran När ett OpenAPI-dokument tillhandahålls via en URL till en plats som är tillgänglig från DIN API Management-tjänst. Se Begränsningar för Azure-prenumerationer.

Tillägg som stöds

De enda tillägg som stöds är:

Tillägg beskrivning
x-ms-paths
  • Gör att du kan definiera sökvägar som särskiljs av frågeparametrar i URL:en.
  • Beskrivs i AutoRest-dokumenten.
x-servers En backport för OpenAPI 3-objektet servers för OpenAPI 2.

Tillägg som inte stöds

Tillägg beskrivning
Recursion API Management stöder inte definitioner som definierats rekursivt.
Till exempel scheman som refererar till sig själva.
Server objekt Stöds inte på API-åtgärdsnivå.
Produces nyckelord Beskriver MIME-typer som returneras av ett API.
Stöds ej.

Anpassade tillägg

  • Ignoreras vid import.
  • Sparas inte eller bevaras inte för export.

Definitioner som inte stöds

Infogade schemadefinitioner för API-åtgärder stöds inte. Schemadefinitioner:

  • Definieras i API-omfånget.
  • Kan refereras till i API-åtgärdsbegäran eller svarsomfång.

Ignorerade definitioner

Säkerhetsdefinitioner ignoreras.

Definitionsbegränsningar

När du importerar frågeparametrar stöds endast standardmetoden för serialisering av matriser (style: form, explode: true). Mer information om frågeparametrar i OpenAPI-specifikationer finns i serialiseringsspecifikationen.

Parametrar som definieras i cookies stöds inte. Du kan fortfarande använda principen för att avkoda och verifiera innehållet i cookies.

OpenAPI version 2

OpenAPI version 2-stöd är endast begränsat till JSON-format.

Parametrar av typen "Formulär" stöds inte. Du kan fortfarande använda principen för att avkoda och verifiera application/x-www-form-urlencoded och application/form-data nyttolaster.

OpenAPI version 3.x

API Management stöder följande specifikationsversioner:

HTTPS-URL:er

  • Om flera servers anges använder API Management den första HTTPS-URL som hittas.
  • Om det inte finns några HTTPS-URL:er är server-URL:en tom.

Stöds

  • example

Stöd saknas

Följande fält ingår i antingen OpenAPI version 3.0.x eller OpenAPI version 3.1.x, men stöds inte:

Objekt Fält
OpenAPI externalDocs
Information summary
Komponenter
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Åtgärd
  • externalDocs
  • callbacks
  • security
  • servers
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

OpenAPI-mekanismer för import, uppdatering och export

Allmänt

API-definitioner som exporteras från en API Management-tjänst är:

  • Främst avsett för externa program som behöver anropa API:et som finns i API Management-tjänsten.
  • Inte avsett att importeras till samma eller annan API Management-tjänst.

Information om konfigurationshantering av API-definitioner i olika tjänster/miljöer finns i dokumentationen om hur du använder API Management-tjänsten med Git.

Lägga till nytt API via OpenAPI-import

För varje åtgärd som finns i OpenAPI-dokumentet skapas en ny åtgärd med:

  • Azure-resursnamn inställt på operationId.

    • operationId värdet normaliseras.
    • Om operationId inte har angetts (inte finns, nulleller är tomt) genereras värdet för Azure-resursnamn genom att kombinera HTTP-metoden och sökvägsmallen.
      • Exempel: get-foo

  • Visningsnamnet är inställt på summary.

    • summary värde:
      • Importerad som den är.
      • Längden är begränsad till 300 tecken.
    • Om summary inte har angetts (inte finns, nulleller är tomt) anges visningsnamnets värde till operationId.

Normaliseringsregler för operationId

  • Konvertera till gemener.
  • Ersätt varje sekvens med icke-alfanumeriska tecken med ett enda bindestreck.
    • Omvandlas till exempel GET-/foo/{bar}?buzz={quix} till get-foo-bar-buzz-quix-.
  • Trimma bindestreck på båda sidor.
    • Till exempel get-foo-bar-buzz-quix- blir get-foo-bar-buzz-quix
  • Trunkera för att passa 76 tecken, fyra tecken mindre än maxgränsen för ett resursnamn.
  • Använd återstående fyra tecken för ett dedupliceringssuffix, om det behövs, i form av -1, -2, ..., -999.

Uppdatera ett befintligt API via OpenAPI-import

Under importen utförs den befintliga API-åtgärden:

  • Ändringar som matchar API:et som beskrivs i OpenAPI-dokumentet.
  • Matchar en åtgärd i OpenAPI-dokumentet genom att jämföra dess operationId värde med den befintliga åtgärdens Azure-resursnamn.
    • Om en matchning hittas uppdateras den befintliga åtgärdens egenskaper "på plats".
    • Om en matchning inte hittas:
      • En ny åtgärd skapas genom att kombinera HTTP-metoden och sökvägsmallen, till exempel get-foo.
      • För varje ny åtgärd försöker importen kopiera principer från en befintlig åtgärd med samma HTTP-metod och sökvägsmall.

Alla befintliga omatchade åtgärder tas bort.

Följ dessa riktlinjer för att göra importen mer förutsägbar:

  • Ange operationId egenskap för varje åtgärd.
  • Avstå från att ändra operationId efter den första importen.
  • Ändra operationId aldrig och HTTP-metod eller sökvägsmall på samma gång.

Normaliseringsregler för operationId

  • Konvertera till gemener.
  • Ersätt varje sekvens med icke-alfanumeriska tecken med ett enda bindestreck.
    • Omvandlas till exempel GET-/foo/{bar}?buzz={quix} till get-foo-bar-buzz-quix-.
  • Trimma bindestreck på båda sidor.
    • Till exempel get-foo-bar-buzz-quix- blir get-foo-bar-buzz-quix
  • Trunkera för att passa 76 tecken, fyra tecken mindre än maxgränsen för ett resursnamn.
  • Använd återstående fyra tecken för ett dedupliceringssuffix, om det behövs, i form av -1, -2, ..., -999.

Exportera API som OpenAPI

För varje åtgärd är det:

  • Azure-resursnamnet exporteras som en operationId.
  • Visningsnamnet exporteras som en summary.

Observera att normaliseringen av operationId görs vid import, inte vid export.

WSDL

Du kan skapa SOAP-direkt - och SOAP-till-REST-API :er med WSDL-filer.

SOAP-bindningar

  • Endast SOAP-bindningar av kodningsformatet "document" och "literal" stöds.
  • Inget stöd för rpc-format eller SOAP-kodning.

Importerar och inkluderar

  • Direktiven wsdl:import, xsd:importoch xsd:include stöds inte. Sammanfoga i stället beroendena till ett dokument.

  • Ett verktyg med öppen källkod för att lösa och sammanfoga wsdl:import, xsd:importoch xsd:include beroenden i en WSDL-fil finns i den här GitHub-lagringsplatsen.

WS-* specifikationer

WSDL-filer som innehåller WS-*-specifikationer stöds inte.

Meddelanden med flera delar

Den här meddelandetypen stöds inte.

WCF wsHttpBinding

  • SOAP-tjänster som skapats med Windows Communication Foundation bör använda basicHttpBinding.
  • wsHttpBinding stöds inte.

MTOM

  • Tjänster som använder MTOM kan fungera.
  • Officiell support erbjuds inte just nu.

Rekursion

  • Typer som definieras rekursivt stöds inte av API Management.
  • Se till exempel en matris med sig själva.

Flera namnområden

Flera namnområden kan användas i ett schema, men endast målnamnområdet kan användas för att definiera meddelandedelar. Dessa namnområden används för att definiera andra indata- eller utdataelement.

Andra namnområden än målet bevaras inte vid export. Du kan importera ett WSDL-dokument som definierar meddelandedelar med andra namnområden, men alla meddelandedelar har WSDL-målnamnområdet vid export.

Flera slutpunkter

WSDL-filer kan definiera flera tjänster och slutpunkter (portar) med ett eller flera wsdl:service wsdl:port element. API Management-gatewayen kan dock importera och proxybegäranden till endast en enda tjänst och slutpunkt. Om flera tjänster eller slutpunkter definieras i WSDL-filen identifierar du måltjänstens namn och slutpunkt när du importerar API:et med hjälp av egenskapen wsdlSelector .

Dricks

Om du vill lastbalansera begäranden över flera tjänster och slutpunkter kan du överväga att konfigurera en belastningsutjämningsserverdelspool.

Matriser

SOAP-till-REST-transformering stöder endast omslutna matriser som visas i exemplet nedan:

    <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

För närvarande finns det inga kända WADL-importproblem.