REST-API-Auslöser

Freigeben Version: Washingtondc

Aktualisiert 1. Februar 2024

4 Minuten Lesedauer

Starten Sie einen Flow aus einem eingehenden API-Aufruf oder Webhook aus einem externen System. Konfigurieren Sie die Auslöserstartbedingungen, ohne benutzerdefinierten Code schreiben oder pflegen zu müssen.

Sie können beispielsweise einen Flow erstellen, der startet, wenn ein IT-Ticket-Nachverfolgungssystem einer Drittpartei eine eingehende Anforderung an die Instanz sendet. Sie können dann die Daten aus der eingehenden REST-Anforderung in ein komplexes Datenobjekt analysieren und die Werte verwenden, um einen Incident in Ihrer Instanz zu öffnen.

Sobald Sie den Flow aktiviert haben, wird der von Ihnen erstellte Endpunkt im API-Explorer unter dem von Ihnen erstellten Namespace angezeigt. Sie können diese Seite verwenden, um den Webhook in Ihrem Drittanbietersystem zu definieren und Ihren Flow zu testen.

Weitere Informationen zu Flow-Auslösern finden Sie unter Flow Designer Auslösertypen.

Hinweis:

Verwenden Sie den REST-API-Auslöser, um Flows aus REST-Aufrufen von externen Systemen zu starten. Um einen Flow aus einem Skript oder API-Aufruf aus derselben Instanz zu starten, verwenden Sie einen Subflow, ein Code-Snippet oder die Flow Designer -API. Siehe API-Zugriff auf Flow Designer und Codefragmente für Flows, Subflows und Aktionen erstellen.

Verfügbare Datenpillen

Je nachdem, wie Sie den Endpunkt konfigurieren, haben Flow Designer über den Auslöser Zugriff auf die folgenden Datenpillen:

Pfadparameter: Ein Objekt, das Pfadparameter in der eingehenden Anforderung enthält.
Abfrageparameter: Ein Objekt, das Abfrageparameter in der eingehenden Anforderung enthält.
Anforderungsheader: Ein Objekt, das Kopfzeilen in der eingehenden Anforderung enthält.
Anforderungstext: Komplexes Datenobjekt, das die Textstruktur der eingehenden Anforderung definiert. Weitere Informationen zu komplexen Objekten finden Sie unter Complex data.

Definieren Sie beim Einrichten des Auslösers, wie die eingehenden Daten aussehen sollen. Sie können dann die zugehörigen Datenpillen innerhalb der Aktionen in Ihrem Flow verwenden. Wenn das System eine eingehende Anforderung erhält, die den Flow startet, verwendet es die in der Anforderung gesendeten Laufzeitwerte.

Erstellen Sie einen Flow mit dem REST-API-Auslöser

Erstellen Sie einen Flow, der gestartet wird, wenn ein Drittanbietersystem eine REST-Anforderung an Ihre Instanz sendet.

Vorbereitungen

Erforderliche Rolle: flow_designer oder admin.

Hinweis:

Diese Funktion erfordert ein IntegrationHub Enterprise-Abonnement. Weitere Informationen finden Sie unter IntegrationHub anfordern.

Prozedur

Öffnen Sie Flow Designer, und erstellen Sie einen Flow.

Weitere Informationen finden Sie unter Flow erstellen.

Beachten Sie, dass der Umfang Ihres Flow in dem von Ihnen erstellten REST-Endpunkt enthalten ist.
Wählen Sie im Abschnitt TRIGGER den Auslöser REST API - Asynchron aus.
Legen Sie im Feld HTTP-Methode die HTTP-Methode für den Endpunkt fest.
Verfügbare Optionen:
- POST
- GET
- LÖSCHEN
- PUT
- PATCH
Erstellen Sie alle für den Endpunkt erforderlichen Pfadparameter, und fügen Sie sie dem relativen Pfad im Feld Pfad hinzu.
Der relative Pfad zum Endpunkt weist das Format /api/auf.<flow-application-scope> /<flow-name> /<path-parameters> .
Sie können auf Kopieren klicken, um den vollständigen Pfad zum Endpunkt zu kopieren. Verwenden Sie diesen Pfad, wenn Sie den Endpunkt für den REST-Aufruf in Ihrem Drittanbietersystem konfigurieren.
1. Erstellen Sie Variablen im Abschnitt „ Pfad-Parameter “.
2. Ziehen Sie die Datenpille, die den Pfadparameter darstellt, in die leere Eingabe im Feld Pfad.
  
  Dieses Feld akzeptiert nur Datenpillen aus dem Abschnitt „ Pfad-Parameter “.
Wählen Sie Erfordert Authentifizierung aus, um Authentifizierungskopfzeilen in der eingehenden REST-Anforderung zu erfordern.
Wenn Authentifizierung erforderlich ausgewählt ist, fügen Sie im Feld Erfordert Rollen die für die Autorisierung der Anforderung erforderlichen Rollen hinzu.
Erstellen Sie im Feld Textkörper unter dem Abschnitt Anforderungsinhalt ein komplexes Datenobjekt, das die Textstruktur der eingehenden Anforderung definiert.

Weitere Informationen zum Erstellen eines komplexen Objekts finden Sie unter Komplexe Daten.

Hinweis:
Der Abschnitt „ Inhalt anfordern “ wird nur angezeigt, wenn die HTTP-Methode POST, PUT oder PATCH lautet.

In diesem Beispieltext wird das Feld Beschreibung in einer eingehenden Nutzlast gesucht, die Ticketinformationen aus einem Ticket-Nachverfolgungssystem einer Drittpartei enthält.
Definieren Sie im Feld Header die Header, die in der eingehenden Anforderung gesendet werden sollen.
Sie können Erforderlich auswählen, um festzulegen, dass die eingehende Anforderung sie enthalten muss.
Definieren Sie im Feld Abfrageparameter die Abfrageparameter, die in der eingehenden Anforderung gesendet werden sollen.
Sie können Erforderlich auswählen, um festzulegen, dass die eingehende Anforderung sie enthalten muss.
Fügen Sie Ihrem Flow Aktionen hinzu, die ausgeführt werden, wenn der Endpunkt aufgerufen wird.

Sie können die Datenpillen aus dem REST-API-Auslöser in Ihren Flow-Aktionen verwenden.

Mit dieser Aktion wird ein Incident-Datensatz erstellt und die Felder Beschreibung und Zuweisungsgruppe aus der eingehenden Nutzlast dem Incident zugeordnet.
Testen und aktivieren Sie den Flow.
Weitere Informationen finden Sie unter Flows testen und Flows aktivieren.
Nach der Aktivierung wird der Endpunkt im REST-API-Explorer angezeigt. Sie können diese Seite verwenden, um Ihren Endpunkt weiter zu testen, oder die Anforderung über Ihr Drittanbietersystem konfigurieren.

Konfigurieren Sie die REST-Anforderung über Ihr Drittanbietersystem.

Sie können beispielsweise diese cURL-Anforderung senden, um den in den vorherigen Schritten definierten Flow auszulösen.

curl "https:your-instance.servicenow.com/api/now/create_incident_from_external_event/assignment_group/287ebd7da9fe198100f92cc8d1d2154e" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
fields: {
   description: \"Major outage with data loss\"
   }
}" \
--user 'username':'password'

Ergebnisse

Der Flow wird ausgeführt, und die REST-Anforderung gibt die Ausführungs-ID zurück.

{
  "result": {
    "executionId": "ndoxeRhshDSezldeGfbYlviFSeFnBjCO"
  }
}

Nächste Maßnahme

Kopieren Sie die Ausführungs-ID in das Ergebnis, und navigieren Sie in Flow Designer zur Registerkarte Ausführungen. Sie können nach Ausführungs-ID filtern, um die Ausführungsdetails zu suchen und den Status der Ausführung anzuzeigen.

Um Probleme zu beheben, können Sie die REST-Abfrage debuggen oder die Details der Flow-Ausführung überprüfen. Weitere Informationen finden Sie unter REST-Abfragen debuggen und Flow-Ausführungsdetails.