API-importbeperkingen en bekende problemen

VAN TOEPASSING OP: Alle API Management-tiers

Bij het importeren van een API kunnen er beperkingen optreden of problemen identificeren en verhelpen voordat u de api kunt importeren. In dit artikel leert u het volgende:

• Het gedrag van API Management tijdens het importeren van OpenAPI.
• OpenAPI-importbeperkingen en hoe OpenAPI-export werkt.
• Vereisten en beperkingen voor WSDL- en WADL-import.

API Management tijdens het importeren van OpenAPI

Tijdens het importeren van OpenAPI, API Management:

• Hiermee wordt specifiek gecontroleerd op querytekenreeksparameters die zijn gemarkeerd als vereist.
• Converteert standaard de vereiste queryreeksparameters naar de vereiste sjabloonparameters.

Als u liever dat vereiste queryparameters in de specificatie worden vertaald naar queryparameters in API Management, schakelt u de instelling Queryparameters opnemen in bewerkingssjablonen uit bij het maken van de API in de portal. U kunt dit ook doen met behulp van de API's : REST API maken of bijwerken om de eigenschap van translateRequiredQueryParameters de API in te stellen op query.

Voor GET-, HEAD- en OPTIONS-bewerkingen negeert API Management een aanvraagbodyparameter als deze is gedefinieerd in de OpenAPI-specificatie.

OpenAPI/Swagger-importbeperkingen

Als er fouten optreden tijdens het importeren van uw OpenAPI-document, controleert u of u het vooraf hebt gevalideerd door:

• Gebruik de ontwerper in de Azure-portal (Ontwerp > Front End > OpenAPI Specification Editor) of
• Met een hulpprogramma van derden, zoals Swagger Editor.

Algemeen

Vereisten voor URL-sjablonen

Vereiste	Beschrijving
Unieke namen voor vereiste pad- en queryparameters	In OpenAPI: Een parameternaam hoeft alleen uniek te zijn binnen een locatie, bijvoorbeeld pad, query, header. In API-beheer: We staan toe dat bewerkingen worden gediscrimineerd door zowel pad- als queryparameters. OpenAPI biedt geen ondersteuning voor deze discriminatie. Daarom moeten parameternamen uniek zijn binnen de volledige URL-sjabloon. Namen zijn hoofdletterongevoelig.
Gedefinieerde URL-parameter	Moet deel uitmaken van de URL-sjabloon.
Beschikbare URL van bronbestand	Toegepast op relatieve server-URL's.
\$ref Pointers	Kan niet verwijzen naar externe bestanden.

OpenAPI-specificaties

Ondersteunde versies

API Management biedt alleen ondersteuning voor:

• OpenAPI versie 2
• OpenAPI-versie 3.0.x (maximaal versie 3.0.3)
• OpenAPI-versie 3.1 (alleen importeren)

Beperkingen voor grootte

Maximale grootte	Beschrijving
Maximaal 4 MB	Wanneer een OpenAPI-specificatie inline wordt geïmporteerd in API Management.
Azure Resource Manager API-aanvraaggrootte	Wanneer een OpenAPI-document wordt opgegeven via een URL naar een locatie die toegankelijk is vanuit uw API Management-service. Zie limieten voor Azure-abonnementen.

Ondersteunde extensies

De enige ondersteunde extensies zijn:

Extensie	Beschrijving
x-ms-paths	Hiermee kunt u paden definiëren die verschillen door queryparameters in de URL. In de AutoRest-documentatie behandeld.
x-servers	Een backport van het servers voor OpenAPI 2.

Niet-ondersteunde extensies

Extensie	Beschrijving
Recursion	API Management biedt geen ondersteuning voor definities die recursief zijn gedefinieerd. Schema's die bijvoorbeeld naar zichzelf verwijzen.
Server object	Niet ondersteund op het niveau van de API-bewerking.
Produces trefwoord	Beschrijft MIME-typen die worden geretourneerd door een API. Wordt niet ondersteund.

Aangepaste extensies

• Worden genegeerd bij importeren.
• Worden niet opgeslagen of bewaard voor export.

Niet-ondersteunde definities

Inlineschemadefinities voor API-bewerkingen worden niet ondersteund. Schemadefinities:

• Worden gedefinieerd in het API-bereik.
• Kan worden verwezen in api-bewerkingsaanvraag- of antwoordbereiken.

Genegeerde definities

Beveiligingsdefinities worden genegeerd.

Definitiebeperkingen

Bij het importeren van queryparameters wordt alleen de standaardmatrixserialisatiemethode (style: form, explode: true) ondersteund. Raadpleeg de serialisatiespecificatie voor meer informatie over queryparameters in OpenAPI-specificaties.

Parameters die in cookies zijn gedefinieerd, worden niet ondersteund. U kunt nog steeds beleid gebruiken om de inhoud van cookies te decoderen en te valideren.

OpenAPI versie 2

Ondersteuning voor OpenAPI versie 2 is beperkt tot alleen JSON-indeling.

Parameters van het type Formulier worden niet ondersteund. U kunt nog steeds beleid gebruiken om application/x-www-form-urlencoded en application/form-data payloads te decoderen en te valideren.

OpenAPI-versie 3.x

API Management ondersteunt de volgende specificatieversies:

• OpenAPI 3.0.3
• OpenAPI 3.1.0 (alleen importeren)

HTTPS-URL's

• Als er meerdere servers zijn opgegeven, gebruikt API Management de eerste HTTPS-URL die wordt gevonden.
• Als er geen HTTPS-URL's zijn, is de server-URL leeg.

Ondersteund

• example

Niet ondersteund

De volgende velden zijn opgenomen in OpenAPI-versie 3.0.x of OpenAPI versie 3.1.x, maar worden niet ondersteund:

Voorwerp	Veld
OpenAPI	externalDocs
Info	summary
Onderdelen	responses parameters examples requestBodies headers securitySchemes links callbacks
Item	trace servers
Bewerking	externalDocs callbacks security servers
Parameter	allowEmptyValue style explode allowReserved
Server sjablonen	API Server and Base URL

OpenAPI-import-, update- en exportmechanismen

Algemeen

API-definities die zijn geëxporteerd vanuit een API Management-service zijn:

• Voornamelijk bedoeld voor externe toepassingen die de API moeten aanroepen die worden gehost in de API Management-service.
• Niet bedoeld om te worden geïmporteerd in dezelfde of andere API Management-service.

Raadpleeg de documentatie met betrekking tot het gebruik van de API Management-service met Git voor configuratiebeheer van API-definities in verschillende services/omgevingen.

Nieuwe API toevoegen via OpenAPI-import

Voor elke bewerking in het OpenAPI-document wordt een nieuwe bewerking gemaakt met:

• Azure-resourcenaam ingesteld op operationId.

  • operationId de waarde is genormaliseerd.
  • Als operationId niet is gespecificeerd (niet aanwezig, null, of leeg), wordt de Azure-resourcenaam gegenereerd door de HTTP-methode en het pad-template te combineren.
    • Bijvoorbeeld: get-foo.

• Weergavenaam ingesteld op summary.

  • summary waarde:
    • Geïmporteerd als zodanig.
    • De lengte is beperkt tot 300 tekens.
  • Als summary niet is opgegeven (niet aanwezig of nullleeg), wordt de weergavenaamwaarde ingesteld op operationId.

Normalisatieregels voor operationId

• Converteren naar kleine letters.
• Vervang elke reeks niet-alfanumerieke tekens door één streepje.
  • Wordt bijvoorbeeld GET-/foo/{bar}?buzz={quix} omgezet in get-foo-bar-buzz-quix-.
• Knip streepjes aan beide zijden.
  • Bijvoorbeeld: get-foo-bar-buzz-quix- wordt get-foo-bar-buzz-quix
• Afkappen op 76 tekens, vier teken minder dan de maximumlimiet voor een resourcenaam.
• Gebruik de resterende vier tekens voor een achtervoegsel voor ontdubbeling, indien nodig, in de vorm van -1, -2, ..., -999.

Een bestaande API bijwerken via OpenAPI-import

Tijdens het importeren wordt de bestaande API-bewerking uitgevoerd:

• Wijzigingen die overeenkomen met de API die wordt beschreven in het OpenAPI-document.
• Komt overeen met een bewerking in het OpenAPI-document door de waarde van operationId te vergelijken met de Azure-resourcenaam van de bestaande bewerking.
  • Als er een overeenkomst wordt gevonden, worden de eigenschappen van de bestaande bewerking direct bijgewerkt.
  • Als er geen overeenkomst is gevonden:
    • Er wordt een nieuwe bewerking gemaakt door bijvoorbeeld een HTTP-methode en padsjabloon get-foote combineren.
    • Voor elke nieuwe bewerking probeert het importeren beleidsregels te kopiëren van een bestaande bewerking met dezelfde HTTP-methode en dezelfde padsjabloon.

Alle bestaande niet-gerelateerde bewerkingen worden verwijderd.

Volg deze richtlijnen om het importeren voorspelbaarder te maken:

• Geef operationId de eigenschap op voor elke bewerking.
• Verander operationId niet na de initiële import.
• operationId Wijzig nooit de http-methode of padsjabloon tegelijkertijd.

Normalisatieregels voor operationId

• Converteren naar kleine letters.
• Vervang elke reeks niet-alfanumerieke tekens door één streepje.
  • Wordt bijvoorbeeld GET-/foo/{bar}?buzz={quix} omgezet in get-foo-bar-buzz-quix-.
• Knip streepjes aan beide zijden.
  • Bijvoorbeeld: get-foo-bar-buzz-quix- wordt get-foo-bar-buzz-quix
• Afkappen op 76 tekens, vier teken minder dan de maximumlimiet voor een resourcenaam.
• Gebruik de resterende vier tekens voor een achtervoegsel voor ontdubbeling, indien nodig, in de vorm van -1, -2, ..., -999.

API exporteren als OpenAPI

Bij elke bewerking geldt het volgende:

• De azure-resourcenaam wordt geëxporteerd als een operationId.
• De weergavenaam wordt geëxporteerd als een summary.

Houd er rekening mee dat de normalisatie van operationId wordt uitgevoerd bij het importeren, niet bij het exporteren.

WSDL

U kunt SOAP Pass Through- en SOAP-to-REST-API's maken met WSDL-bestanden.

SOAP-bindingen

• Alleen SOAP-bindingen van 'document' en 'letterlijke' coderingsstijl worden ondersteund.
• Geen ondersteuning voor de stijl 'rpc' of SOAP-Encoding.

Importeert en omvat

• De wsdl:import, xsd:import en xsd:include richtlijnen worden niet ondersteund. In plaats daarvan voegt u de afhankelijkheden samen in één document.

• Zie deze wsdl:import voor een opensource-hulpprogramma om xsd:import, xsd:include, en afhankelijkheden in een WSDL-bestand op te lossen en samen te voegen.

"WS-*" specificaties

WSDL-bestanden met WS-* specificaties worden niet ondersteund.

Berichten met meerdere onderdelen

Dit berichttype wordt niet ondersteund.

WCF wsHttpBinding

• SOAP-services die zijn gemaakt met Windows Communication Foundation moeten basicHttpBinding gebruiken.
• wsHttpBinding wordt niet ondersteund.

MTOM

• Services die worden gebruikt MTOM, werken mogelijk .
• Officiële ondersteuning wordt momenteel niet aangeboden.

Recursie

• Typen die recursief worden gedefinieerd, worden niet ondersteund door API Management.
• Raadpleeg bijvoorbeeld een matrix van zichzelf.

Meerdere naamruimten

Hoewel meerdere naamruimten in een schema kunnen worden gebruikt, kan alleen de doelnaamruimte worden gebruikt om berichtonderdelen te definiëren. Deze naamruimten worden gebruikt om andere invoer- of uitvoerelementen te definiëren.

Andere naamruimten dan de doelnaamruimte blijven niet behouden tijdens export. Hoewel u een WSDL-document kunt importeren dat berichtonderdelen definieert met andere naamruimten, hebben alle berichtonderdelen de WSDL-doelnaamruimte bij export.

Meerdere eindpunten

WSDL-bestanden kunnen meerdere services en eindpunten (poorten) definiëren met behulp van een of meer wsdl:service-elementen en wsdl:port-elementen. De API Management-gateway kan echter aanvragen slechts naar één service en eindpunt importeren en doorsturen als proxy. Als er meerdere services of eindpunten zijn gedefinieerd in het WSDL-bestand, identificeert u de naam en het eindpunt van de doelservice bij het importeren van de API met behulp van de eigenschap wsdlSelector .

Aanbeveling

Als u verzoeken wilt verdelen over meerdere services en eindpunten, overweeg dan om een load-balanced back-endpool te configureren.

Reeksen

SOAP-naar-REST-transformatie ondersteunt alleen verpakte matrices die worden weergegeven in het onderstaande voorbeeld:

    <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

Er zijn momenteel geen bekende PROBLEMEN met het importeren van WADL.