API-importbegränsningar och kända problem

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 lär du dig mer om:

• 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 den här inställningen med hjälp av API:et – 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 Portal (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

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

Tillägg som stöds

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

Tillägg som inte stöds

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:

• OpenAPI 3.0.3
• OpenAPI 3.1.0 (endast import)

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:

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) är visningsnamnets värde inställt på operationId.

Normaliseringsregler för operationId

• Konvertera till gemener.
• Ersätt varje sekvens med icke-numeriska 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 blir get-foo-bar-buzz-quix-get-foo-bar-buzz-quix.
• Trunkera för att passa 76 tecken, fyra tecken mindre än maxgränsen för ett resursnamn.
• Använd de återstående fyra tecknen 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-numeriska 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 de återstående fyra tecknen 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.

Normaliseringen av operationId görs vid import, inte vid export.

WSDL (på engelska)

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 (MTOM)

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

Rekursion

• API Management stöder inte typer som definieras rekursivt.
• 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:servicewsdl:port element. API Management-gatewayen kan dock importera API:er 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 .

Matriser

SOAP-till-REST-transformering stöder endast omslutna matriser som visas i följande exempel:

    <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 (på engelska)

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