Einschränkungen und bekannte Probleme beim Import von APIs

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Beim Importieren einer API stoßen Sie unter Umständen auf Einschränkungen oder Probleme, die behoben werden müssen, damit der Import erfolgreich ausgeführt werden kann. In diesem Artikel lernen Sie Folgendes:

  • Verhalten von API Management während des OpenAPI-Imports
  • OpenAPI-Importeinschränkungen und Funktionsweise des OpenAPI-Exports.
  • Anforderungen und Einschränkungen für WSDL- und WADL-Importe.

API Management während des OpenAPI-Imports

Während des OpenAPI-Imports werden von API Management folgende Aktionen durchgeführt:

  • Spezifische Suche nach Abfragezeichenfolgenparametern, die als erforderlich gekennzeichnet sind
  • Konvertiert standardmäßig die erforderlichen Abfragezeichenfolgenparameter in erforderliche Vorlagenparameter.

Wenn Sie bevorzugen, dass erforderliche Abfrageparameter in der Spezifikation in Abfrageparameter in API Management übersetzt werden, deaktivieren Sie die Einstellung Abfrageparameter in Vorgangsvorlagen einschließen, wenn Sie die API im Portal erstellen. Sie können dies auch mithilfe der REST-API APIs – Erstellen oder Aktualisieren erreichen, um die translateRequiredQueryParameters-Eigenschaft der API auf query festzulegen.

Bei GET-, HEAD- und OPTIONS-Vorgängen verwerfen API Management einen Anforderungstextparameter, wenn in der OpenAPI-Spezifikation definiert.

Einschränkungen für den OpenAPI/Swagger-Import

Wenn Sie beim Importieren Ihres OpenAPI-Dokuments Fehlermeldungen erhalten, stellen Sie sicher, dass Sie das Dokument zuvor wie folgt überprüft haben:

  • Mithilfe des Designers im Azure-Portal (Design > Front-End > OpenAPI-Spezifikations-Editor) oder
  • Mit einem Drittanbietertool, z. B. Swagger-Editor

Allgemein

Anforderungen für URL-Vorlagen

Anforderung BESCHREIBUNG
Eindeutige Namen für erforderliche Pfad- und Abfrageparameter In OpenAPI:
  • Ein Parametername muss nur an einem Ort (beispielsweise im Pfad, in der Abfrage oder im Header) eindeutig sein.
In API Management:
  • Vorgänge können sowohl nach Pfad- als auch nach Abfrageparametern unterschieden werden.
  • Da diese Unterscheidung von OpenAPI nicht unterstützt wird, müssen Parameternamen innerhalb der gesamten URL-Vorlage eindeutig sein.
Definierter URL-Parameter Muss Teil der URL-Vorlage sein.
Verfügbare Quelldatei-URL Wird auf relative Server-URLs angewendet.
\$ref-Zeiger Es können keine Verweise auf externe Dateien verwendet werden.

OpenAPI-Spezifikationen

Unterstützte Versionen

Von API Management wird nur Folgendes unterstützt:

  • OpenAPI-Version 2
  • OpenAPI-Version 3.0.x (bis Version 3.0.3)
  • OpenAPI-Version 3.1 (nur Importieren)

Größenbeschränkungen

Größenlimit BESCHREIBUNG
Bis zu 4 MB Gilt, wenn eine OpenAPI-Spezifikation inline in API Management importiert wird.
Anforderungsgröße für Azure Resource Manager-API Gilt, wenn ein OpenAPI-Dokument über eine URL eines Speicherorts bereitgestellt wird, auf den von Ihrem API Management-Dienst aus zugegriffen werden kann. Informationen hierzu finden Sie unter Einschränkungen für Azure-Abonnements.

Unterstützte Erweiterungen

Die einzigen unterstützten Erweiterungen sind:

Durchwahl BESCHREIBUNG
x-ms-paths
  • Ermöglicht das Definieren von Pfaden, die durch Abfrageparameter in der URL unterschieden werden.
  • Weitere Informationen finden Sie in der AutoRest-Dokumentation.
x-servers Eine Zurückportierung des OpenAPI 3-Objekts servers für OpenAPI 2.

Nicht unterstützte Erweiterungen

Durchwahl BESCHREIBUNG
Recursion API Management unterstützt keine rekursiven Definitionen.
Dies sind beispielsweise Schemas, die auf sich selbst verweisen.
Objekt Server Wird auf API-Vorgangsebene nicht unterstützt.
ProducesSchlüsselwort Beschreibt von einer API zurückgegebene MIME-Typen.
Wird nicht unterstützt.

Benutzerdefinierte Erweiterungen

  • Werden beim Importieren ignoriert
  • Werden nicht gespeichert oder für den Export beibehalten

Nicht unterstützte Definitionen

Inlineschemadefinitionen für API-Vorgänge werden nicht unterstützt. Schemadefinitionen:

  • Werden im API-Bereich definiert
  • Können in Anforderungs- oder Antwortbereichen von API-Vorgängen referenziert werden

Ignorierte Definitionen

Sicherheitsdefinitionen werden ignoriert.

Definitionseinschränkungen

Beim Importieren von Abfrageparametern wird nur die Standardmethode für die Arrayserialisierung (style: form, explode: true) unterstützt. Weitere Informationen zu Abfrageparametern in OpenAPI-Spezifikationen finden Sie in der Serialisierungsspezifikation.

In Cookies definierte Parameter werden nicht unterstützt. Sie können die Richtlinie weiterhin verwenden, um den Inhalt von Cookies zu entschlüsseln und zu überprüfen.

OpenAPI, Version 2

Die Unterstützung von OpenAPI Version 2 ist auf das JSON-Format beschränkt.

Parameter vom Typ „Formular“ werden nicht unterstützt. Sie können die Richtlinie weiterhin verwenden, um Nutzlasten vom Typ application/x-www-form-urlencoded und application/form-data zu decodieren und zu überprüfen.

OpenAPI-Version 3.x

API Management unterstützt die folgenden Spezifikationsversionen:

HTTPS-URLs

  • Wenn viele servers angegeben sind, verwendet API Management die erste ermittelte HTTPS-URL.
  • Falls keine HTTPS-URLs vorhanden sind, ist die Server-URL leer.

Unterstützt

  • example

Nicht unterstützt

Die folgenden Felder sind entweder in OpenAPI-Version 3.0.x oder OpenAPI-Version 3.1.x enthalten, werden aber nicht unterstützt:

Object Feld
OpenAPI externalDocs
Info summary
Komponenten
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Vorgang
  • externalDocs
  • callbacks
  • security
  • servers
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

OpenAPI-Import-, Update- und Exportmechanismen

Allgemein

Für API-Definitionen, die aus einem API Management-Dienst exportiert werden, gilt Folgendes:

  • Sie sind hauptsächlich für externe Anwendungen vorgesehen, die die im API Management-Dienst gehostete API aufrufen müssen.
  • Sie sind nicht für einen Import in denselben oder einen anderen API Management-Dienst gedacht.

Informationen zur Konfigurationsverwaltung von API-Definitionen in verschiedenen Diensten/Umgebungen finden Sie in der Dokumentation zur Verwendung des API Management-Diensts mit Git.

Hinzufügen einer neuen API über OpenAPI-Import

Für jeden Vorgang im OpenAPI-Dokument wird ein neuer Vorgang mit folgenden Merkmalen erstellt:

  • Der Azure-Ressourcenname wird auf operationId festgelegt.

    • Der Wert von operationId wird normalisiert.
    • Wenn operationId nicht angegeben ist (nicht vorhanden, null oder leer), wird der Wert des Azure-Ressourcennamens generiert, indem HTTP-Methode und Pfadvorlage kombiniert werden.
      • Beispiel: get-foo.

  • Der Anzeigename wird auf summary festgelegt.

    • Für den Wert summary gilt Folgendes:
      • Er wird unverändert importiert.
      • Seine Länge ist auf 300 Zeichen beschränkt.
    • Wenn summary nicht angegeben ist (nicht vorhanden, null oder leer), wird der Wert des Anzeigenamens auf operationId festgelegt.

Normalisierungsregeln für operationId

  • In Kleinschreibung konvertieren.
  • Jede Sequenz aus nicht alphanumerischen Zeichen wird durch einen einzelnen Bindestrich ersetzt.
    • Beispielsweise wird GET-/foo/{bar}?buzz={quix} in get-foo-bar-buzz-quix- transformiert.
  • Bindestriche auf beiden Seiten werden gekürzt.
    • get-foo-bar-buzz-quix- wird beispielsweise zu get-foo-bar-buzz-quix.
  • Kürzen Sie auf 76 Zeichen, vier Zeichen weniger als die Obergrenze für einen Ressourcennamen.
  • Verwenden Sie ggf. die restlichen vier Zeichen für ein Deduplizierungssuffix in Form von -1, -2, ..., -999.

Aktualisieren einer vorhandenen API über den OpenAPI-Import

Während des Imports geschieht für den bestehenden API-Vorgang Folgendes:

  • Er wird geändert, um der im OpenAPI-Dokument beschriebenen API zu entsprechen.
  • Er wird einem Vorgang im OpenAPI-Dokument zugeordnet, indem sein operationId-Wert mit dem Azure-Ressourcennamen des vorhandenen Vorgangs verglichen wird.
    • Wenn eine Übereinstimmung gefunden wird, werden die Eigenschaften vorhandener Vorgänge „direkt“ aktualisiert.
    • Wenn keine Übereinstimmung gefunden wird:
      • Es wird ein neuer Vorgang erstellt, indem HTTP-Methode und Pfadvorlage kombiniert werden, z. B. get-foo.
      • Beim Import wird für jeden neuen Vorgang versucht, Richtlinien von einem vorhandenen Vorgang mit der gleichen HTTP-Methode und Pfadvorlage zu kopieren.

Alle vorhandenen nicht übereinstimmenden Vorgänge werden gelöscht.

Beachten Sie die folgenden Leitfäden, um den Import vorhersagbarer zu machen:

  • Geben Sie die operationId-Eigenschaft für jeden Vorgang an.
  • Ändern Sie operationId nach dem ersten Import nicht mehr.
  • Ändern Sie operationId und HTTP-Methode oder Pfadvorlage niemals gleichzeitig.

Normalisierungsregeln für operationId

  • In Kleinschreibung konvertieren.
  • Jede Sequenz aus nicht alphanumerischen Zeichen wird durch einen einzelnen Bindestrich ersetzt.
    • Beispielsweise wird GET-/foo/{bar}?buzz={quix} in get-foo-bar-buzz-quix- transformiert.
  • Bindestriche auf beiden Seiten werden gekürzt.
    • get-foo-bar-buzz-quix- wird beispielsweise zu get-foo-bar-buzz-quix.
  • Kürzen Sie auf 76 Zeichen, vier Zeichen weniger als die Obergrenze für einen Ressourcennamen.
  • Verwenden Sie ggf. die restlichen vier Zeichen für ein Deduplizierungssuffix in Form von -1, -2, ..., -999.

Exportieren der API als OpenAPI

Für jeden Vorgang gilt:

  • Der Name der Azure-Ressource wird als operationId exportiert.
  • Der Anzeigename wird als summary exportiert.

Beachten Sie, dass die Normalisierung von operationId beim Import erfolgt, nicht beim Export.

WSDL

Sie können SOAP-Passthrough- und SOAP-to-REST-APIs mithilfe von WSDL-Dateien erstellen.

SOAP-Bindungen

  • Es werden nur SOAP-Bindungen der Codierungsstile „document“ und „literal“ unterstützt.
  • Der Stil „rpc“ und die SOAP-Codierung werden nicht unterstützt.

Imports und Includes

  • Die Direktiven wsdl:import, xsd:import und xsd:include werden nicht unterstützt. Führen Sie die Abhängigkeiten stattdessen in einem Dokument zusammen.

  • Ein Open-Source-Tool zum Auflösen und Zusammenführen von wsdl:import-, xsd:import- und xsd:include-Abhängigkeiten in einer WSDL-Datei finden Sie in diesem GitHub-Repository.

WS-*-Spezifikationen

WSDL-Dateien, die WS-*-Spezifikationen enthalten, werden nicht unterstützt.

Mehrteilige Nachrichten

Dieser Nachrichtentyp wird nicht unterstützt.

WCF wsHttpBinding

  • Für SOAP-Dienste, die mit Windows Communication Foundation erstellt wurden, sollte basicHttpBinding verwendet werden.
  • wsHttpBinding wird nicht unterstützt.

MTOM

  • Dienste, die MTOM verwenden, können funktionieren.
  • Eine offizielle Unterstützung wird derzeit nicht angeboten.

Rekursion

  • Rekursiv definierte Typen werden von API Management nicht unterstützt.
  • Ein Beispiel ist ein Array, das auf sich selbst verweist.

Mehrere Namespaces

In einem Schema können zwar mehrere Namespaces verwendet werden, aber nur der Zielnamespace kann zum Definieren von Nachrichtenteilen verwendet werden. Diese Namespaces werden verwendet, um andere Ein- oder Ausgabeelemente zu definieren.

Andere Namespaces als der Zielnamespace werden beim Exportieren nicht beibehalten. Sie können zwar ein WSDL-Dokument importieren, das Nachrichtenteile mit anderen Namespaces definiert, beim Exportieren haben jedoch alle Nachrichtenteile den WSDL-Zielnamespace.

Mehrere Endpunkte

WSDL-Dateien können mehrere Dienste und Endpunkte (Ports) durch ein oder mehrere wsdl:service- und wsdl:port-Elemente definieren. Das API-Verwaltungsgateway kann jedoch nur einen einzelnen Dienst und Endpunkt importieren und Proxyanforderungen verwenden. Wenn mehrere Dienste oder Endpunkte in der WSDL-Datei definiert sind, identifizieren Sie den Zieldienstnamen und den Endpunkt beim Importieren der API mithilfe der wsdlSelector-Eigenschaft.

Tipp

Wenn Sie für Anforderungen über mehrere Dienste und Endpunkte hinweg einen Lastenausgleich durchführen möchten, sollten Sie einen Back-End-Pool mit Lastenausgleich konfigurieren.

Arrays

Bei der SOAP-to-REST-Transformation werden nur umschlossene Arrays unterstützt. Dies ist im Beispiel unten dargestellt:

    <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

Derzeit sind keine Probleme beim Import im Format WADL bekannt.