Benutzerlisten via REST erstellen und in einem VARA-Objekt speichern

Ein externes System enthält eine komplexe Liste, die Sie in die Automation Engine importieren möchten, weil Sie diese in verschiedenen Objekten verwenden möchten. Anstelle die Daten manuell in ein statisches VARA-Objekt einzugeben, möchten Sie diese automatisch abrufen, parsen und in das VARA-Objekt schreiben, damit Sie sie in anderen Objekten verwenden können.

Diese Seite beinhaltet Folgendes:

Was werde ich lernen?

Wie man eine externe Lösung über den REST Web Service mit der Automation Engine verbindet.
Wie man Daten von dieser Lösung abrufen, und diese den eigenen Bedürfnissen entsprechend parsen kann.
Wie man diese Daten für die weitere Verwendung in ein VARA-Objekt schreibt.

Was wird in diesem Anwendungsfall beschrieben?

In diesem Anwendungsfall ist das externe System ein TeamCity-Server. Sie möchten die Liste der TeamCity-Benutzer über REST auslesen und sie zusammen mit den wichtigen Benutzerdaten für die weitere Verwendung in verschiedenen Automation Engine-Objekten speichern.

Zu diesem Zweck erstellen Sie einen WEBSERVICE-Job vom Typ REST, in dem Sie die Anfrage definieren, die Sie an den TeamCity-Server senden möchten - also die Ressource, die Sie auslesen möchten. Sie müssen auch die Antwort definieren, die Sie erwarten. In diesem Fall ist das eine strukturierte XML-Datei, das Ihren Bedürfnissen entsprechend geparst wird. Abschließend enthält der Job das Script, das die Daten extrahiert (in diesem Fall Benutzername, Name und Benutzer-ID) und in ein statisches VARA-Objekt schreibt, das Sie davor erstellt haben. Auf diese Weise können Sie die Liste der TeamCity-Benutzer in jedem beliebigen Objekt in Ihrem Automation Engine-System verwenden.

Zusätzlich zu dem WebServices-REST-Job und dem VARA-Objekt brauchen Sie ein Verbindungsobjekt (CONN), das die Verbindung zum REST-Service und einem WebService-REST-Agenten definiert.

Voraussetzungen

Sie müssen Folgendes definieren:

ein Verbindungsobjekt, das den Endpunkt, die Authentifizierung und die Ressourcen bereitstellt

Verbindungsobjekte stellen die Parameter zur Verfügung, die die Verbindung zwischen bestimmten Lösungen und der Automation Engine herstellen, und VARA-Objekten so ermöglichen, Werte aus externen Systemen abzurufen.
den REST-Job
ein VARA-Objekt
einige Scripts

Akteure des Anwendungsfalls

Erstellen des Verbindungsobjekts

Erstellen Sie ein Verbindungsobjekt vom Typ "WEBSERVICE - REST". In unserem Fall heißt es CONN.REST.TC.
Definieren Sie das Objekt in der Perspektive Process Assembly. In diesem Beispiel werden wir uns nicht näher mit der Definition allgemeiner Objekt-Einstellungen befassen (Seite "Allgemein", Seite "Versionsmanagement", Seite "Dokumentation"), sondern uns auf die objektspezifischen Einstellungen konzentrieren.
Nehmen Sie die folgenden Einstellungen im Abschnitt Allgemein vor:
- Geben Sie den URL-Endpunkt ein. In unserem Fall ist das http://vviebuildsrv01/httpAuth/app/rest/.
- Geben Sie den im externen System (also dem TeamCity-Server) definierten Benutzernamen und das zugehörige Passwort ein.
Definieren Sie die Ressource im Abschnitt Ressourcen. Die Ressource ist ein Objekt mit einem Typ, zugehörigen Daten, Beziehungen zu anderen Ressourcen und einigen Methoden, die darauf angewendet werden. In unserem Fall werden wir eine GET-Anfrage an die Ressource /users des REST API von TeamCity senden, um die Liste der TeamCity-Benutzer abzurufen. Obwohl in diesem Verbindungsobjekt zwei Ressourcen angegeben wurden, werden wir in diesem Anwendungsfall nur users verwenden:

Erstellen eines VARA-Objekts

Erstellen Sie ein statisches VARA-Objekt, in dem Sie die Liste speichern möchten, die Sie von TeamCity ausgelesen haben. In unserem Fall heißt es VARA.TC.USERS:

Erstellen eines WebServices-Jobs

Erstellen Sie einen WebServices-Job vom Typ "REST". In unserem Fall heißt er JOBS.REST.TC.USERS.XML.
Weisen Sie im Abschnitt "Ausführungseinstellungen" auf der Seite Attribute des Jobs den Agenten zu, in dem die Dienste ausgeführt werden sollen.

Hinweis: Da Sie die Kontrollkästchen Antwort: in Job-Log schreiben und Antwortreport erstellen aktiviert haben, wird die Benutzerliste nach Ausführung des Jobs sowohl in Form eines Reports online als auch als XML-Datei, die Sie herunterladen und lokal speichern können, zur Verfügung stehen. Klicken Sie in der Symbolleiste auf Letzter Report. In dem Fenster Reports, das daraufhin angezeigt wird, können Sie Folgendes tun:
- Wählen Sie in der Dropdown-Liste Report (REP) aus, um sich den Report online anzusehen.
- Wählen Sie Verzeichnis aus, um die XML-Datei herunterzuladen.
Geben Sie auf der Hauptseite des Web Service allgemeine Verbindungseinstellungen an und legen Sie fest, ob das Protokoll und der Report direkt vom User Interface aus zugänglich sind:
1. Wählen Sie das soeben erstelle Verbindungsobjekt aus.
2. (Optional) Aktivieren Sie das Kontrollkästchen Response: write to Job Log.
  
  Diese Option schreibt die Details der Datenübertragung in den Report (REP), auf den Sie einfach über das Automic Web Interface zugreifen können, indem Sie in der Symbolleiste Process Assembly auf die Schaltfläche Letzter Report klicken und in dem sich öffnenden Dialog Report (REP) auswählen.
3. (Optional) Aktivieren Sie das Kontrollkästchen Create Response Report.
  
  Mit dieser Option können Sie auch innerhalb des Automic Web Interface auf die von TeamCity abgerufene strukturierte XML-Datei zugreifen, indem Sie auf die Schaltfläche Letzter Report klicken, anschließend in dem sich öffnenden Dialog Verzeichnis auswählen und die Datei herunterladen.
4. Geben Sie auf der Unterseite Eingabeaufforderung der Seite Web Service den gewünschten Service an:
  1. Wählen Sie im Abschnitt Request Settings die Ressource aus, die Sie verwenden möchten. In diesem Fall ist das users.
  2. Verwenden Sie die voreingestellte Methode, also GET.
5. Die Benutzerliste, die Ihnen von der gerade im VARA-Objekt definierten Anfrage zur Verfügung gestellt wird, muss entsprechend geparst werden. Das Ziel ist hierbei, die erhaltene XML in eine Script-Variable zu schreiben, die später während des Post-Scripts weiterverarbeitet wird. Geben Sie dazu den gewünschten Service auf der Unterseite Response der Seite Web Service an. Fügen Sie im Abschnitt Parse a Single Part Response den Ausdruck zu der Antwort hinzu und geben Sie folgendes an:
  1. Wählen Sie unter Parsing Typ den Eintrag XPath aus, da Sie eine XML-Datei extrahieren möchten.
  2. Wählen Sie unter Output-Typ die Option Als Variable speichern aus.
  3. Geben Sie unter Output-Name den Ausdruck &TC_USER# ein.
  4. Geben Sie den Ausdruck ein. In unserem Fall also /users.
  5. Ignorieren Sie die Checkbox Array verwenden.
  6. Führen Sie den Job nun aus, um zu überprüfen, ob Sie die erwartete Antwort erhalten. Dadurch können Sie außerdem die Schaltfläche "Ersetzen" im Response Expression Tester verwenden, um die letzte Antwort auf die Testeingabe zu lesen, und damit zu beginnen, den Ausdruck zu erstellen.
  7. Klicken Sie auf die Schaltfläche Test, um die letzte Antwort zu erhalten:
    Hier können Sie die Parsing-Optionen so lange konfigurieren und testen, bis Sie die gewünschten Ergebnisse erhalten.
6. Geben Sie das folgende Script auf der Seite Post-Script des Jobs ein, um die Benutzerdaten in das zuvor erstellte VARA-Objekt zu schreiben:
  
  :SET&OUTVARA# = "VARA.TC.USERS"
  
  ! XML-Funktionen verwenden, um XML zu öffnen
  
  :SET&XML# = xml_open('STRING',&TC_USERS#)
  
  !Ausgabe der Anzahl gefundener Benutzer
  
  :SET&NR# = XML_GET_CHILD_COUNT(&XML#)
  
  :PRINT"Anzahl der gefundenen Benutzer: &NR#"
  
  !Durchläuft die Benutzereinträge, um Sie dem VARA hinzuzufügen
  
  :if&NR# > 0
  
  :  SET &HND# = XML_GET_FIRST_CHILD(&XML#)
  
  :   WHILE &HND# <> ""
  
  :      SET &USERNAME# = XML_GET_ATTRIBUTE(&HND#,'@username')
  
  :      SET &NAME# = XML_GET_ATTRIBUTE(&HND#,'@name')
  
  :      SET &ID# = XML_GET_ATTRIBUTE(&HND#,'@id')
  
  :      PRINT "Benutzername: &USERNAME#"
  
  :      PUT_VAR&OUTVARA#, &USERNAME#, &NAME#, &ID#
  
  :      SET &HND# = XML_GET_NEXTSIBLING(&HND#)
  
  :   ENDWHILE
  
  :endif
  
  :XML_CLOSE

Hinweis: Sie haben nun alle erforderlichen Schritte durchgeführt.

Wenn Sie den Job nun ausführen, werden nicht nur ein Jobprotokoll und ein herunterladbarer Report erstellt, sondern auch das von Ihnen erstellte VARA-Objekt (VARA_TC_USERS) mit folgenden Daten gefüllt, die Sie in jedem anderen Automation Engine-Objekt weiterverwenden können:

Schlüssel: Benutzername
Wert 1: vollständiger Name des Benutzers
Wert 2: Benutzer-ID

Beispiel

Nützliche Links

Dieser Anwendungsfall enthält Referenzen zu einigen Funktionen, über die Sie vielleicht mehr erfahren möchten.