OpenAPI-Schritt

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Importieren Sie die OpenAPI-Spezifikation eines ausgehenden REST-Webservices einer Drittpartei, und erstellen Sie eine Integration mit dem Webservice. Die Anforderungsdetails für den zugrunde liegenden REST-API-Vorgang werden aus der OpenAPI-Spezifikation abgeleitet.

    Für den JSON-Ausgabeantworttext erstellt das System eine komplexe Datenobjektausgabe aus der OpenAPI-Spezifikation.

    Hinweis:
    OpenAPI-Schritt ist im Basissystem nicht verfügbar und erfordert das Abonnement ServiceNow® IntegrationHub. Nachdem das erforderliche Plugin aktiviert wurde, wird der Schritt unter Integrationen angezeigt.

    Rollen und Verfügbarkeit

    Verfügbar als Aktionsdesigner-Aktionsschritt. Benutzer mit den Rollen „action_designer“ und „open_api_admin“ oder „admin“ können eine benutzerdefinierte Aktion mit einem oder mehreren Aktionsschritten erstellen.

    Felder

    Feld Beschreibung
    Verbindungsalias Datensatz des Alias für Verbindungen und Anmeldeinformationen, den das System zum Ausführen des Aktionsschritts verwendet. Benutzer mit den Rollen „action_designer“ und „connection_admin“ oder „admin“ können einen zugeordneten Verbindungsalias-Datensatz auswählen. Wenn Sie einen Alias verwenden, müssen Sie nicht mehrere Anmeldeinformations- und Verbindungsinformationsprofile konfigurieren, wenn Sie eine Aktion in mehreren Umgebungen verwenden. Ebenso müssen Sie Ihre benutzerdefinierte Aktion nicht aktualisieren, wenn sich die Verbindungsinformationen ändern. Weitere Informationen zu Verbindungen und Anmeldeinformationen finden Sie unter Anmeldeinformationen, Verbindungen und Aliasnamen.
    Basis-URL Basis-URL aus dem Verbindungsalias für die REST-Anforderung.
    API-Quelle

    Option zur Auswahl einer OpenAPI v2.0- und v3.0-Spezifikation, die zum Erstellen der Anforderung verwendet wird, oder Auswahl von OpenAPI importieren, um eine neue OpenAPI-Spezifikation zu importieren. Sie können Spezifikationen importieren, indem Sie eine URL und Anmeldeinformationen für YAML oder JSON angeben oder Inhalte kopieren und einfügen.
    API-Vorgang

    Option zum Auswählen eines Vorgangs aus der Liste. Verfügbare Vorgänge werden von der OpenAPI-Spezifikation im Feld API-Quelle bereitgestellt.
    Resource Path Pfad für die Ressource.
    HTTP-Methode Zur Verarbeitung der Anforderung verwendete HTTP-Methode.
    • GET
    • POST
    • PUT
    • PATCH
    • LÖSCHEN
    Abfrageparameter

    Name-Wert-Paare, die an den REST-Endpunkt übergeben werden sollen. Sie können diese Parameter manuell erstellen oder Eingabevariablen in die Parameterfelder ziehen und dann einen Wert zuweisen.

    Unterstützt REST-Schrittanforderungen, die doppelte Abfrageparameternamen enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Abfrageparameternamen enthält, fügt Flow Designer die Abfrageparameter der Anforderung in der Reihenfolge hinzu, in der Sie sie definiert haben.

    Hinweis:
    Beim Importieren einer OpenAPI-Spezifikation fügt das System dem REST-Schritt alle in der Spezifikation enthaltenen Parameter und Header hinzu. Überprüfen Sie die endgültigen REST-Schrittwerte, und entfernen Sie Parameter, die Sie in der Anforderung nicht senden möchten. Wenn die API beispielsweise Inhaltstypheader für JSON und XML akzeptiert, fügt das System beide Header dem REST-Schritt hinzu. Entfernen Sie je nach Inhaltstyp, den Sie in der Antwort erhalten möchten, einen der Header.
    Header

    Header, die mit der Anforderung gesendet werden sollen. Sie können Header manuell erstellen oder Eingabevariablen in die Parameterfelder ziehen und dann einen Wert zuweisen.

    Unterstützen Sie REST-Schrittanforderungen, die doppelte Anforderungskopfzeilen enthalten. Wenn Sie eine REST-Anforderung erstellen, die doppelte Anforderungskopfzeilen enthält, werden die Kopfzeilen in der Reihenfolge gesendet, in der Sie sie definiert haben.

    Hinweis:
    Beim Importieren einer OpenAPI-Spezifikation fügt das System dem REST-Schritt alle in der Spezifikation enthaltenen Parameter und Header hinzu. Überprüfen Sie die endgültigen REST-Schrittwerte, und entfernen Sie Parameter, die Sie in der Anforderung nicht senden möchten. Wenn die API beispielsweise Inhaltstypheader für JSON und XML akzeptiert, fügt das System beide Header dem REST-Schritt hinzu. Entfernen Sie je nach Inhaltstyp, den Sie in der Antwort erhalten möchten, einen der Header.
    Anhang Anhangsdatensatz, der die Anforderung enthält. Sie können diesen Datensatz in einem vorherigen Schritt suchen oder erstellen und ihn als Eingabevariable definieren. Erstellen Sie sie mithilfe der APIs JSONStreamingBuilder und XMLStreamingBuilder im Skriptschritt.
    Hinweis:
    Dieses Feld ist verfügbar, wenn Sie Binär in der Liste „Anforderungstyp“ auswählen.
    Wiederholungsrichtlinie aktivieren Option zum Aktivieren der Wiederholungsrichtlinie. Weitere Informationen finden Sie unter Wiederholungsrichtlinie.
    Standardrichtlinie für Alias überschreiben Option zum Überschreiben der Standardwiederholungsrichtlinie. Dieses Kontrollkästchen ist nicht verfügbar, wenn in der Verbindungsliste die Option Verbindung inline definieren ausgewählt ist.
    Wiederholungsrichtlinie Standardwiederholungsrichtlinie, die dem Verbindungsalias zugeordnet ist. Wenn Standardrichtlinie für Alias überschreiben ausgewählt ist, können Sie die Standardwiederholungsrichtlinie überschreiben und eine andere vorhandene Neuversuchsrichtlinie basierend auf Ihrer Anforderung auswählen.

    Felder für Aktionsfehlerauswertung

    Feld Beschreibung
    Wenn dieser Schritt fehlschlägt Option, um mit der Ausführung des nächsten Schritts fortzufahren oder zur Fehlerauswertung zu wechseln. Informationen zur Verwendung des Schrittstatuscodes oder der Meldung für eine Fehlerbedingung für eine benutzerdefinierte Aktion finden Sie unter Action error evaluation.
    Felder im Schritt „API öffnen“.

    Felder für Aktionsfehlerauswertung

    Feld Beschreibung
    Wenn dieser Schritt fehlschlägt Option, um mit der Ausführung des nächsten Schritts fortzufahren oder zur Fehlerauswertung zu wechseln. Informationen zur Verwendung des Schrittstatuscodes oder der Meldung für eine Fehlerbedingung für eine benutzerdefinierte Aktion finden Sie unter Action error evaluation.

    Bekannte Einschränkungen

    Erstellen Sie einen OpenAPI-Schritt aus einer OpenAPI-Spezifikation mit diesen Einschränkungen.

    Medientypen des Anforderungstexts
    Der Anforderungstext unterstützt nur JSON-Medientypen.
    Hinweis:
    Ein Ausgabeobjekt vom Typ Zeichenfolge wird erstellt, wenn das OpenAPI-Schema zusätzliche Eigenschaften oder keine Eigenschaften aufweist.
    OpenAPI 3.0-Komponenten

    OpenAPI 3.0 fügt neue Komponenten zu SWAGGER 2.0 hinzu, um eine API detaillierter zu beschreiben. OpenAPI-Support im OpenAPI-Schritt unterstützt einige, aber nicht alle dieser Komponenten. Der OpenAPI-Schritt unterstützt diese Komponenten derzeit nicht.

    • Schemaobjekt: additionalProperties-Eigenschaften
    • Diskriminatorobjekt
    • Info-Objekt: „termsOfService“, „Kontakt“, „Lizenz“-Felder
    • Beispielobjekt
    • Link-Objekt
    • Rückrufobjekt
    • Sicherheitsschemaobjekt
    • Sicherheitsanforderungsobjekt
    • Tag-Objekt
    • Externes Dokumentationsobjekt
    • Serverobjekt
    • Spezifikationserweiterungen
    • Rekursive Referenzen

    Weitere Informationen zu diesen Komponenten finden Sie in der OpenAPI-Dokumentation. Weitere Informationen finden Sie unter OpenAPI-Spezifikation.

    Maximale Anzahl der unterstützten Vorgänge
    Die Anzahl der API-Vorgänge ist standardmäßig auf 500 beschränkt. Mit der Systemeigenschaft glide.rest.openapi.max_operation_limitkönnen Sie jedoch die Anzahl der Vorgänge von 1 bis 1000 konfigurieren.