REST-Webserviceaktivitäten erstellen

Verwenden Sie dieses Verfahren, um eine benutzerdefinierte REST-Webserviceaktivität für Orchestration zu erstellen.

Vorbereitungen

Erforderliche Rolle: web_service_admin, activity_admin, activity_creator

Warum und wann dieser Vorgang ausgeführt wird

So erstellen und verwenden Sie eine Workflows-Aktivität für REST-Webservices:

• Erstellen Sie eine REST-Nachricht erstellen, wenn noch keine entsprechende konfiguriert ist.
• Weisen Sie jedem Benutzer, der eine benutzerdefinierte REST-Aktivität erstellen oder bearbeiten muss, die Rolle „web_service_admin“ zu.
• Bestimmen Sie eine Anwendung oder einen Anwendungsbereichfür diese Aktivität.
• Bestimmen Sie die REST-Nachricht erstellen, die für die Aktivität verwendet werden soll. Verwenden Sie diesen Wert, um den in der REST-Nachricht konfigurierten Endpunkt zu überschreiben.
• Erstellen Sie optional Anmeldeinformationen für die Basic Authentication. Verwenden Sie diesen Wert, um die in der SOAP-Nachricht konfigurierten Berechtigungsnachweise zu überschreiben.

Prozedur

1. Erstellen Sie eine benutzerdefinierte Aktivität.
   Diese Aktion erstellt eine benutzerdefinierte Aktivität mithilfe einer Vorlage.
2. Nachdem Sie allgemeine Eigenschaften eingerichtet und Eingabevariablen erstellthaben, konfigurieren Sie den Ausführungsbefehl für den REST-Webservice.

   Option	Bezeichnung
   Ordnen Sie die Eingabevariablen zu	Verwenden Sie die von Ihnen erstellten Variablen, um den Befehl zu konfigurieren, den Orchestration ausführt.
   REST-Nachricht	Name einer vorhandenen REST-Nachricht, die in dieser Aktivität verwendet werden soll
   REST-Nachrichtenfunktion	REST-Nachrichtenfunktion für diese Aktivität
   Endpunkt	Endpunkt-URL für den von dieser Aktivität verwendeten REST-Webservice. Geben Sie einen Endpunkt in dieses Feld ein, um den in der REST-Nachricht konfigurierten Endpunkt zu überschreiben. Klicken Sie auf das Schlosssymbol, um das Eingabefeld zu öffnen.
   Variablensubstitutionen	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. Parametern, die in der REST-Nachricht definiert sind und ${} verwenden, können Daten aus dieser Aktivitätsvorlage zugewiesen werden. Verwenden Sie die Spalte Zusätzliches Attribut, um das System so zu konfigurieren, dass der Text nicht mit Escape-Zeichen versehen wird. Der an die REST-Nachricht gesendete Text wird standardmäßig mit Escape-Zeichen versehen. Wenn die Benutzer Variablen mithilfe der Variablensubstitution in ausgehenden REST-Nachrichten in der REST-Nachricht bereitgestellt haben, wird die Spalte Name automatisch ausgefüllt.
   Zusätzliche Header	Zusätzliche HTTP-Headerparameter für die ausgewählte REST-Nachricht. Sie können diese Werte auch verwenden, um Parameter zu überschreiben, die von der REST-Nachricht geerbt wurden.
   Zusätzliche Abfrageparameter	Zusätzliche Abfrageparameter für die ausgewählte REST-Nachricht. Sie können diese Werte auch verwenden, um Parameter zu überschreiben, die von der REST-Nachricht geerbt wurden.
   MID Server verwenden	Kontrollkästchen, das festlegt, ob ein MID Server zum Aufrufen des REST-Webservice verwendet werden muss. Hinweis: Wenn die REST-Webservice-Nachrichtenfunktion einen MID Server definiert, wird dieser MID Server anstelle des hier ausgewählten verwendet.
   Erforderliche MID Server-Fähigkeiten	MID Server mit den entsprechenden MID Server-Fähigkeiten für die Verbindung mit dem REST-Endpunkt. Standardmäßig wählt das System einen MID Server mit REST-Fähigkeiten aus. Dieses Feld ist verfügbar, wenn die Checkbox MID-Server verwenden aktiviert ist.
   Zeitüberschreitung	Zulässige Dauer der REST-Webserviceanforderung vor der Zeitüberschreitung in Sekunden. Der Standardwert ist 10.
   Authentifizierung	Bestimmt, welche Art von Authentifizierung für den Endpunkt erforderlich ist. Die Optionen sind: Vorhandene Anmeldeinformationen in REST-Nachricht verwenden: Verwendet Anmeldeinformationsdefinitionen aus der REST-Nachrichtendefinition. Mit Anmeldeinformationender Standardauthentifizierung überschreiben: Verwendet die Standardauthentifizierung für ausgehende SOAP- Anmeldeinformationen, um die Anmeldeinformationen in der REST-Nachrichtendefinition zu überschreiben. Anmeldeinformationen für die Standardauthentifizierung müssen bereitgestellt werden, bevor sie zur Auswahl verfügbar sind. Mit Anmeldeinformationen für Zertifikatsauthentifizierung überschreiben: Verwendet ein Zertifikat, z. B. einen privaten Key, zum Überschreiben der Anmeldeinformationen in der REST-Nachrichtendefinition. Mit Anmeldeinformationen für Basic Authentication und Zertifikatsauthentifizierung überschreiben: Verwendet sowohl Anmeldeinformationen der Basic Authentication als auch der Zertifikatauthentifizierung, um die Anmeldeinformationen in der REST-Nachrichtendefinition zu überschreiben. Mit OAuth-Anmeldeinformationen überschreiben: Verwendet OAuth 2.0-Anmeldeinformationen zum Überschreiben der Anmeldeinformationen in der REST-Nachrichtendefinition. Für die für diese Aktivität ausgewählte REST-Nachricht muss das OAuth 2.0-Tutorial – Erstellen einer REST-Nachricht auf OAuth 2.0 festgelegt und die OAuth-Profile und -Bereiche entsprechend konfiguriert sein.
   Berechtigungen	Erforderliche Anmeldeinformationen für Basic Authentication für den REST-Endpunkt. Dieses Feld ist verfügbar, wenn im Feld Authentifizierung Mit Anmeldeinformationen für Basic Authentication überschreiben ausgewählt ist. In der Auswahlliste werden nur Anmeldeinformationen für Basic Authentication angezeigt, die in der Instanz gespeicherte Anmeldeinformationen und Anmeldeinformations-IDs eines externen Speichersystems umfassen. Wenn Sie Anmeldeinformationen verwenden, die in einem CyberArk-Tresor gespeichert sind, können Sie den in der MID Server-Konfigurationsdatei definierten Standardtresor überschreiben. Details finden Sie unter Konfigurieren der MID Server für CyberArk. Fügen Sie der Anmeldeinformations-ID den Namen eines anderen Tresors als Präfix getrennt durch einen Doppelpunkt hinzu. Beispielsweise newsafe:orch-test-f5.
   Protokollprofil	Zu verwendende Zertifikatsauthentifizierung. Dieses Feld ist verfügbar, wenn im Feld Authentifizierung entweder Mit Anmeldeinformationen für Zertifikatsauthentifizierung überschreiben oder Mit Anmeldeinformationen für Basic Authentication und Zertifikatsauthentifizierung überschreiben ist.
   OAuth-Profil	Profil für den OAuth-Anbieter für diese REST-Nachricht. Weitere Informationen finden Sie unter OAuth-Profil angeben.

   Hinweis:

   Sie können Parameterwerte in einem Test-Payload Variablen auf der Registerkarte Ausgaben automatisch zuordnen. Siehe Ausgabevariablen automatisch zuordnen.

Nächste Maßnahme

Beenden Sie die Erstellung Ihrer REST-Webservice-Aktivität, indem Sie Ausgabevariablenerstellen, eine Analyseregel erstellenoder Bedingungenerstellen. Im Thema Benutzerdefinierte Aktivitäten erstellen finden Sie Informationen zu den Vorlagenoptionen.

Automatische Zuordnung von REST-Aktivitätsausgabevariablen

Mit dem ServiceNow-Aktivitätsdesigner können Sie Parameterwerte in einem REST-Test-Payload automatisch Variablen in der Stufe Ausgaben zuordnen.

Vorbereitungen

Erforderliche Rolle: web_service_admin, activity_admin, activity_creator

Warum und wann dieser Vorgang ausgeführt wird

Hinweis:

Sie können Eingabevariablen von jeder Stufe des Aktivitätendesigners aus testen, wenn Sie genügend Informationen für Orchestration angegeben haben, um den Endpunkt zu kontaktieren und Daten zurückzugeben. Normalerweise ist die Stufe Ausführungsbefehl der Punkt, an dem Eingaben zum Testen bereit sind.

Prozedur

1. Fahren Sie im Aktivitätsdesigner mit der Stufe Ausführungsbefehl fort.
2. Definieren Sie bei Bedarf einen geeigneten MID-Server.
   Der Test schlägt fehl, wenn der MID-Server nicht gefunden wird oder keine Verbindung zum Ziel hergestellt werden kann.
3. Klicken auf Testeingaben, um die Eingabeparameter zu testen.
   Wenn Sie tatsächliche Werte für die Parameter und Felder hinzugefügt haben, führt das System diese Werte für das angegebene Ziel aus und gibt das resultierende Payload zurück. Wenn Sie den Feldern und Parametern Eingabevariablen zugeordnet haben, zeigt das System ein Dialogfeld an, in dem Sie diesen Variablen Testwerte zuweisen können.
4. Geben Sie ggf. Testwerte an, und klicken Sie auf OK, um das Payload anzuzeigen.
   Die gesamte Payload wird auf der Registerkarte Rohausgabe des Antwortformulars angezeigt.

   

5. Wählen Sie eine dieser Optionen für die automatische Zuordnung aus.
   • Automatisch lokalen Variablen zuordnen: Ordnet Werte direkt einer lokalen Variable zur Verwendung in der Aktivität zu.
   • Automatisch Ausgabevariablen zuordnen: Ordnet Werte direkt der Ausgabevariable zu, um sie an andere Aktivitäten im Workflow zu übergeben. Durch die automatische Zuordnung zu einer Ausgabevariable wird ein Array mit Objekten erstellt, wobei jedes Objekt die Spaltennamen aus dem Abfrageergebnis enthält.

Ausführungsparameter für REST-Vorlagen

Sie verwenden Ausführungsparameter, um das Eingabeprozessskript im Formular Vorverarbeitung des Aktivitätendesigners zu erstellen.

Beschreibungen der REST-Webservice-Befehlsfelder finden Sie unter REST-Ausführungsbefehle konfigurieren.

Hinweis:

Sie müssen das Präfix executionParam. mit allen Variablen in dieser Tabelle verwenden.

Tabelle : 1. Ausführungsparameter für REST-Vorlagen

Name	Variable	Typ	Verwendung
Webservicenachricht	web_service_message	Referenz	Die sys_id der entsprechenden Webservicenachricht
Webservice-Nachrichtenfunktion	web-service_message_function	Referenz	Die sys_id der REST-Nachrichtenfunktion
Webservice-Endpunkt	web_service_endpoint	Zeichenfolge	URL des REST-Endpunkts
Parameters	parameters	Array von JavaScript-Objekten	Array von JavaScript-Objekten, ausgedrückt mit dem Präfix executionParam.. Anweisungen zum Erstellen von Arrays mit diesem Parameter finden Sie unter JavaScript-Arrays in REST-Vorlagen erstellen.
MID Server verwenden	use_mid_server	Boolesch	Legt fest, ob der MID-Server verwendet werden soll oder nicht. Mit dem Wert wahr wird der MID-Server verwendet, und mit dem Wert falsch wird der MID-Server nicht verwendet.
MidCapabilities	midCapabilities	Zeichenfolge (durch Kommas getrennt)	Liste der Referenzen für die erforderlichen MID Server-Fähigkeiten
Time out	time-out	Zeichenfolge	Zulässige Dauer der Zeitüberschreitung, ausgedrückt in Sekunden
ValueCapabilities	valueCapabilities	Hashmap-Array	Fähigkeitswerte zur Auswahl des MID Servers. Weitere Informationen finden Sie unter MID Server-Fähigkeiten. Verwenden Sie dieses Beispiel, um die Auswahl des MID Servers anzupassen, wenn zusätzliche Fähigkeiten nach Wert zugewiesen werden: var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);
Auth Type	auth-type	Boolesch	Typ der zu verwendenden Anmeldeinformationen. Die Auswahlmöglichkeiten sind: basic_auth_pick_credentials use_existing_credentials
Berechtigungen	credentials	Referenz	Enthält die Anmeldeinformationen, die für diese REST-Nachricht verwendet werden sollen, wenn auth_type basic_auth_pick_credentials ist.

JavaScript-Arrays in REST-Vorlagen erstellen

Dies sind Anweisungen zum Erstellen von JavaScript-Arrays mit REST-Ausführungsparametern.

Vorbereitungen

Erforderliche Rolle: web_service_admin, activity_admin, activity_creator

Warum und wann dieser Vorgang ausgeführt wird

Um dem Parameter-Array weitere Name-Wert-Paare hinzuzufügen, hängen Sie die Werte an das vorhandene Array an.

Prozedur

1. Erstellen Sie ein JavaScript-Objekt mit der folgenden Syntax, und fügen Sie es dem Array executionParam.parameter hinzu:

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
   executionParam.parameters.push(newParameter);

   Durch das Hinzufügen des neuen JavaScript-Objekts zu dem Array stellen Sie sicher, dass alle bereits im Array verfügbaren Elemente nicht betroffen werden.

2. Legen Sie den Wert in der Spalte Zusätzliches Attribut im Eingabefeld REST-Nachrichtenparameter auf Do not escape text fest.

   In diesem Fall versieht das System den für das Attribut value angegebenen Wert nicht mit Escape-Zeichen. Ein Beispiel dafür ist:

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
   executionParam.parameters.push(newParameter);

   Hinweis:

   Wenn der Wert für das Feld Zusätzliches Attribut None lautet, dann versieht das System den durch das Attribut value angegebenen Wert mit Escape-Zeichen. Im ersten Beispiel wird parameterValue mit Escape-Zeichen versehen.

Nachverarbeitungsparameter für REST-Vorlagen

Verwenden Sie diese Parameter, um ein Nachverarbeitungsskript zu erstellen.

Tabelle : 2. Nachverarbeitungsparameter des Aktivitätendesigners

Name	Variable	Typ	Verwendung
Status code	status_code	Ganzzahl	Enthält den vom REST-Webservice zurückgegebenen Statuscode
Header	header	Hashmap eines JavaScript-Objekts	Hashmap mit den Key-Wert-Paaren, die den an den Webservice übergebenen Headerwerten zugeordnet ist. Sie können auf jeden Wert mit executionResult.header[keyName] zugreifen.
Body	body	Zeichenfolge	Enthält einen Zeichenfolgewert, der die Ausgabe der REST-Nachricht darstellt
Error	error	Zeichenfolge	Gibt die Fehlerzeichenfolge vom REST-Webservice zurück, außer es liegen keine Fehler vor. In diesem Fall wird null zurückgegeben.

REST-Ausführungsbefehle konfigurieren

Verwenden Sie die von Ihnen erstellten Eingabevariablen, um den Befehl zu konfigurieren, den Orchestration auf dem REST-Endpunkt ausführt.

Vorbereitungen

Erstellen Sie im Formular Eingaben die benötigten Eingabevariablen, bevor Sie mit der Stufe Ausführungsbefehl fortfahren.

Erforderliche Rolle: web_service_admin, activity_admin, activity_creator

Hinweis:

Sie können die REST-Verbindung zwischen dem MID Server und dem Endpunkt testen, ohne die Aktivität in einem Workflow-Kontext ausführen zu müssen. Details dazu finden Sie unter Vorlagenausgaben testen.

Prozedur

1. Ziehen Sie Variablen aus der Liste der Eingaben, und legen Sie sie in den Befehlsfeldern ab.
   Das System formatiert die Variablen in der richtigen Syntax für den Befehl.

   Abbildung : 1. REST-Ausführungsbefehl

   

2. Füllen Sie die in der Tabelle angegebenen Felder aus.

   Tabelle : 3. Felder für den REST-Ausführungsbefehl

   Feld	Beschreibung
   Eingabe	Generator für Eingabevariablen. Eingabevariablen erstellen, um sie verfügbaren Feldern zuzuordnen.
   REST-Nachricht	Name einer vorhandenen REST-Nachricht, die in dieser Aktivität verwendet werden soll Benutzer müssen über die Rolle web_service_admin verfügen, um dieses Feld konfigurieren zu können.
   REST-Nachrichtenfunktion	REST-Nachrichtenfunktion für diese Aktivität Benutzer müssen über die Rolle web_service_admin verfügen, um dieses Feld konfigurieren zu können.
   Endpunkt	Endpunkt-URL für den von dieser Aktivität verwendeten REST-Webservice. Geben Sie einen Endpunkt in dieses Feld ein, um den in der REST-Nachricht konfigurierten Endpunkt zu überschreiben. Klicken Sie auf das Schlosssymbol, um das Eingabefeld zu öffnen.
   Variablensubstitutionen	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. Parametern, die in der REST-Nachricht definiert sind und ${} verwenden, können Daten aus dieser Aktivitätsvorlage zugewiesen werden. Verwenden Sie die Spalte Zusätzliches Attribut, um das System so zu konfigurieren, dass der Text nicht mit Escape-Zeichen versehen wird. Der an die REST-Nachricht gesendete Text wird standardmäßig mit Escape-Zeichen versehen. Die Spalte Name wird automatisch ausgefüllt, wenn die Benutzer Variablen mithilfe der Variablensubstitution in ausgehenden REST-Nachrichten in der REST-Nachricht bereitgestellt haben.
   Zusätzliche Header	Zusätzliche HTTP-Headerparameter für die ausgewählte REST-Nachricht. Sie können diese Werte auch verwenden, um Parameter zu überschreiben, die von der REST-Nachricht geerbt wurden.
   Zusätzliche Abfrageparameter	Zusätzliche Abfrageparameter für die ausgewählte REST-Nachricht. Sie können diese Werte auch verwenden, um Parameter zu überschreiben, die von der REST-Nachricht geerbt wurden.
   MID Server verwenden	Kontrollkästchen, das festlegt, ob ein MID Server zum Aufrufen des REST-Webservice verwendet werden muss. Hinweis: Wenn die REST-Webservice-Nachrichtenfunktion einen MID Server definiert, wird dieser MID Server anstelle des hier ausgewählten verwendet.
   Erforderliche MID Server-Fähigkeiten	MID Server mit den entsprechenden MID Server-Fähigkeiten für die Verbindung mit dem REST-Endpunkt. Standardmäßig wählt das System einen MID Server mit REST-Fähigkeiten aus. Dieses Feld ist verfügbar, wenn die Checkbox MID-Server verwenden aktiviert ist.
   Zeitüberschreitung	Zulässige Dauer der REST-Webserviceanforderung vor der Zeitüberschreitung in Sekunden. Der Standardwert ist 10.
   Authentifizierung	Bestimmt, welche Art von Authentifizierung für den Endpunkt erforderlich ist. Die Optionen sind: Vorhandene Anmeldeinformationen in REST-Nachricht verwenden: Verwendet Anmeldeinformationsdefinitionen aus der REST-Nachrichtendefinition. Mit Anmeldeinformationender Standardauthentifizierung überschreiben: Verwendet die Standardauthentifizierung für ausgehende SOAP- Anmeldeinformationen, um die Anmeldeinformationen in der REST-Nachrichtendefinition zu überschreiben. Anmeldeinformationen für die Standardauthentifizierung müssen bereitgestellt werden, bevor sie zur Auswahl verfügbar sind. Mit Anmeldeinformationen für Zertifikatsauthentifizierung überschreiben: Verwendet ein Zertifikat, z. B. einen privaten Key, zum Überschreiben der Anmeldeinformationen in der REST-Nachrichtendefinition. Mit Anmeldeinformationen für Basic Authentication und Zertifikatsauthentifizierung überschreiben: Verwendet sowohl Anmeldeinformationen der Basic Authentication als auch der Zertifikatauthentifizierung, um die Anmeldeinformationen in der REST-Nachrichtendefinition zu überschreiben. Mit OAuth-Anmeldeinformationen überschreiben: Verwendet OAuth 2.0-Anmeldeinformationen zum Überschreiben der Anmeldeinformationen in der REST-Nachrichtendefinition. Für die für diese Aktivität ausgewählte REST-Nachricht muss das OAuth 2.0-Tutorial – Erstellen einer REST-Nachricht auf OAuth 2.0 festgelegt und die OAuth-Profile und -Bereiche entsprechend konfiguriert sein.
   Berechtigungen	Erforderliche Anmeldeinformationen für Basic Authentication für den REST-Endpunkt. Dieses Feld ist verfügbar, wenn im Feld Authentifizierung Mit Anmeldeinformationen für Basic Authentication überschreiben ausgewählt ist. In der Auswahlliste werden nur Anmeldeinformationen für die Standardauthentifizierung angezeigt, die in der Instanz gespeicherte Anmeldeinformationen und Anmeldeinformations-IDs eines externen Speichersystems umfassen. Wenn Sie Anmeldeinformationen verwenden, die in einem CyberArk-Safe gespeichert sind, können Sie die in der MID Server-Konfigurationsdatei definierte Konfiguration des MID Servers für CyberArk überschreiben, indem Sie der Anmeldeinformations-ID den Namen eines anderen Safes als Präfix hinzufügen, getrennt durch einen Doppelpunkt. Zum Beispiel newsafe:orch-test-f5.
   Protokollprofil	Zu verwendende Zertifikatsauthentifizierung. Dieses Feld ist verfügbar, wenn im Feld Authentifizierung entweder Mit Anmeldeinformationen für Zertifikatsauthentifizierung überschreiben oder Mit Anmeldeinformationen für Basic Authentication und Zertifikatsauthentifizierung überschreiben ist.
   OAuth-Profil	Profil für den OAuth-Anbieter für diese REST-Nachricht. Weitere Informationen finden Sie unter OAuth-Profil angeben.

3. Klicken Sie auf Speichern.
4. Klicken Sie auf Fortsetzen, um mit der Stufe Ausgaben fortzufahren.