Freigeben über

Einschränkungen und bekannte Probleme beim Import von APIs

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 verwirft API Management einen Anforderungstextparameter, wenn er in der OpenAPI-Spezifikation definiert ist.

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

Wenn beim Importieren des OpenAPI-Dokuments Fehler angezeigt werden, stellen Sie sicher, dass Sie es vorher durch eine der folgenden Aktionen ü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. Bei Namen wird die Groß-/Kleinschreibung nicht berücksichtigt.
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.
Maximale URL-Länge DIE API-URL muss weniger als 128 Zeichen lang sein.

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.
Server Objekt Wird auf API-Vorgangsebene nicht unterstützt.
Produces Schlü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 standardmäßige Array serialisierungsmethode (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 mehrere servers angegeben sind, verwendet die API-Verwaltung die erste gefundene 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:

Objekt Feld
OpenAPI externalDocs
Informationen summary
Komponenten
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Vorgang
  • externalDocs
  • callbacks
  • security
  • servers
  • deprecated
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved
  • deprecated
Servervorlagenerstellung
  • API Server and Base URL

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 Anzeigenamenwert auf operationId gesetzt.

Normalisierungsregeln für operationId

  • In Kleinschreibung konvertieren.
  • Ersetzen Sie jede Sequenz von nichtalphanumerischen Zeichen durch einen einzelnen Bindestrich.
    • Beispielsweise wird GET-/foo/{bar}?buzz={quix} in get-foo-bar-buzz-quix- transformiert.
  • Bindestriche auf beiden Seiten werden gekürzt.
    • Beispielsweise wird get-foo-bar-buzz-quix- zu get-foo-bar-buzz-quix.
  • Kürzen Sie auf 76 Zeichen, vier Zeichen weniger als die Obergrenze für einen Ressourcennamen.
  • Verwenden Sie die verbleibenden vier Zeichen für ein Deduplizierungssuffix, falls erforderlich, 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.
      • Für jeden neuen Vorgang versucht der Import, Richtlinien aus einem vorhandenen Vorgang mit derselben 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.
  • Ersetzen Sie jede Sequenz von nichtalphanumerischen Zeichen durch einen einzelnen Bindestrich.
    • 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 die verbleibenden vier Zeichen für ein Deduplizierungssuffix, falls erforderlich, 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.

Die Normalisierung des Vorgangs operationId erfolgt beim Import, 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 des Codierungsstils "document" und "literal" unterstützt.
  • Keine Unterstützung für "rpc"-Stil oder SOAP-Codierung.

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 MTOMverwendet werden, könnten funktionieren.
  • Eine offizielle Unterstützung wird derzeit nicht angeboten.

Rekursion

  • Die API-Verwaltung unterstützt keine Typen, die rekursiv definiert sind.
  • 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 APIs und Proxyanforderungen nur in einen einzelnen Dienst und Endpunkt importieren. 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

Die SOAP-zu-REST-Transformation unterstützt nur umhüllte Arrays, wie im folgenden Beispiel gezeigt:

    <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.

  • Last updated on