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 krijgt u meer informatie over:

• 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 deze instelling ook instellen 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

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

Ondersteunde extensies

De enige ondersteunde extensies zijn:

Niet-ondersteunde extensies

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

Wanneer u queryparameters importeert, wordt alleen de standaardmatrixserialisatiemethode (style: form, explode: true) ondersteund. Zie 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:

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 waarde van de weergavenaam ingesteld op operationId.

Normalisatieregels voor operationId

• Converteren naar kleine letters.
• Vervang elke reeks niet-phanumerische tekens door één streepje.
  • Wordt bijvoorbeeld GET-/foo/{bar}?buzz={quix} omgezet in get-foo-bar-buzz-quix-.
• Knip streepjes aan beide zijden.
  • Zo wordt get-foo-bar-buzz-quix- gewijzigd in 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 ter plaatse 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 de import beleidsregels te kopiëren van een bestaande bewerking met dezelfde HTTP-methode en 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-phanumerische 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.

De normalisatie van operationId wordt uitgevoerd tijdens 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 gebruiktMTOM, werken mogelijk.
• Officiële ondersteuning wordt momenteel niet aangeboden.

Recursie

• API Management biedt geen ondersteuning voor typen die recursief worden gedefinieerd.
• 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 API's en proxyaanvragen importeren naar slechts één service en eindpunt. 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 .

Reeksen

SOAP-naar-REST-transformatie ondersteunt alleen verpakte matrices die worden weergegeven in het volgende 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.