Share via

API-importbeperkingen en bekende problemen

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

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:

  • De ontwerpfunctie gebruiken in 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 Management:
  • 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 niet hoofdlettergevoelig.
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 worden onderscheiden door queryparameters in de URL.
  • Behandeld in de AutoRest-documenten.
x-servers Een backport van het OpenAPI 3-object 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 nettoladingen te decoderen en application/form-data te validerenapplication/x-www-form-urlencoded.

OpenAPI-versie 3.x

API Management ondersteunt de volgende specificatieversies:

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:

Object Veld
OpenAPI externalDocs
Info summary
Onderdelen
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Bewerking
  • externalDocs
  • callbacks
  • security
  • servers
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

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 deze waarde niet is opgegeven (niet aanwezig of nullleeg), wordt de waarde van de Azure-resourcenaam gegenereerd door de HTTP-methode en padsjabloon 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 tekens kleiner 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 ervan te vergelijken met operationId de Naam van de Azure-resource van de bestaande bewerking.
    • Als er een overeenkomst wordt gevonden, worden de eigenschappen van de bestaande bewerking 'in-place' 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.
  • Onthoud dat u operationId na de initiële import wijzigt.
  • 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 tekens kleiner 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

Voor elke bewerking is 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 de bewerking wordt uitgevoerd bij het operationId importeren, niet bij export.

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

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 worden gebruikt basicHttpBinding.
  • 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 het doel blijven niet behouden bij 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 door een of meer wsdl:service elementen wsdl:port . De API Management-gateway kan echter aanvragen importeren en proxy's 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 .

Tip

Als u aanvragen wilt verdelen over meerdere services en eindpunten, kunt u overwegen om een back-endpool met gelijke taakverdeling te configureren.

Matrices

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.