REST-Skripte
BITTE BEACHTEN SIE:
Der folgende Beitrag enthält möglicherweise Verweise auf die benutzerdefinierten Skriptfunktionen der IndySoft-Produktreihe. Einige Aspekte der besprochenen Funktionen sind für Endkunden möglicherweise nicht zugänglich. Zur Orientierung: Die betroffenen Funktionen enthalten die Begriffe „Skript“ oder „benutzerdefiniertes Skript“.Weitere Informationen zu benutzerdefinierten Skripten sowie zu deren Implementierung und Unterstützung im Produkt finden Sie im Abschnitt „Übersicht über benutzerdefinierte Skripte“.
Beachten Sie außerdem, dass für den Webzugriff auf die IndySoft-Datenbank mittels REST-Skripten die Registrierung des Produkts „IndySoft REST Scripting“ im IndySoft-Registrierungsmodul erforderlich ist. Wenden Sie sich für weitere Informationen an den IndySoft-Vertrieb. Wenn „IndySoft REST Scripting“ als Produkt registriert wurde (mithilfe des IndySoft Registration Utility), können Sie über die Registerkarte „REST Scripts“ Skripte bearbeiten und den zugehörigen IndySoft REST-Dienst einrichten. REST-Skripte ermöglichen den skriptgesteuerten Webzugriff auf die IndySoft-Datenbank. Die Funktionalität wird vollständig durch die Skripte gesteuert, die auf dieser Registerkarte erstellt und gepflegt werden. REST ist einfach ein Architekturstil für HTTP-Anfragen und -Antworten. Wenn der IndySoft REST Server läuft und ein oder mehrere REST-Skripte erstellt wurden, kann IndySoft über diesen Dienst auf bestimmte HTTP-Anfragen warten und entsprechend darauf reagieren.
Hier ist ein ganz einfaches Beispiel. Angenommen, Sie besitzen die Domain „myurl.com“ und möchten, dass eine bestimmte Webanfrage das Fälligkeitsdatum für die Kalibrierung eines bestimmten Objekts zurückgibt. (Das ist ein ganz einfaches Beispiel!). Zunächst würden Sie ein REST-Skript einrichten, das bei bestimmten HTTP-Anfragen ausgelöst wird. Dieses Skript liest bei jeder Anfrage die erforderlichen Parameter ein und gibt anschließend eine HTTP-Antwort zurück. Der Name des Skripts würde dem letzten Teil der URL in der Anfrage entsprechen. Anschließend würden Sie den IndySoft-REST-Dienst installieren bzw. ausführen (mit Verweis auf Ihre myurl.com-Domain, die auf einem bestimmten Port läuft, usw. Die REST-Skriptfunktion in IndySoft ermöglicht den Zugriff auf alle Eigenschaften von HTTP-Anfragen (URL, Port, IP usw.), den Anfragetyp („GET“, „POST“, „PUT“, „DELETE“), alle Header, alle Abfrageparameter sowie den Nachrichtentext (entweder als Text oder als Binärdaten). Für die Rückgabe der einzelnen Elemente stehen spezielle Skriptfunktionen zur Verfügung. Nehmen wir in unserem Beispiel an, dass unsere Webanfrage von der Client-Seite vollständig in der URL enthalten ist (in diesem Client-Beispiel ist kein Nachrichtentext erforderlich):
http://myurl.com:9001/IndyScripts/ReturnDueDate?Company=ABC+COMPANY&Id=ABC123
Aus der oben genannten Beispiel-URL geht hervor, dass unser IndySoft-REST-Server über HTTP (nicht HTTPS) läuft, die Domain, auf der er eingerichtet ist, myurl.com lautet und die relative URI (wie im Setup konfiguriert) „IndyScripts“ ist. Der Name des aufgerufenen Skripts lautet „ReturnDueDate“. Schließlich werden zwei Abfrageparameter übergeben: „Company“ und „Id“. Nur HTTP-Anfragen, die an „[http://myurl.com:9001/IndyScripts]“ (http://myurl.com:9001/IndyScripts') gesendet werden, erreichen den IndySoft-REST-Server. Außerdem wird ein Skript nur dann ausgeführt, wenn der Anfrage (in der URL) ein Skriptname folgt, wie beispielsweise bei „[http://myurl.com:9001/IndyScripts/ReturnDueDate]“ (http://myurl.com:9001/IndyScripts/ReturnDueDate'), wodurch das Skript „ReturnDueDate“ ausgeführt wird. Schließlich liest das Skript die Abfrageparameter (sowie gegebenenfalls weitere Details) ein und reagiert entsprechend. Nachfolgend finden Sie ein Beispiel für das REST-Server-Skript:
sCompany = RequestQueryParameter("Company")
sID = RequestQueryParameter("Id")
if tdDoSQLRecords(1, "SELECT SCHED_DUE_DATE FROM SCHEDGI WHERE COMPANY = '" & sCompany & "' AND GAGE_SN = '" & sID & "' AND SCHED_TYPE = 'CALIBRATION'") then
sDueDate = tdFieldbyNameAsString(1, "SCHED_DUE_DATE")
ResponseStatusCode(700)
ResponseBodyAsText(sDueDate)
Else
sDueDate = ""
ResponseStatusCode(800)
ResponseBodyAsText(sDueDate)
End If
Das ist also ein ganz einfaches Beispiel. Das Skript liest die URL-Abfrageparameter für „Company“ und „Id“ aus. Beachten Sie, dass prozentkodierte Zeichen automatisch durch die Funktion RequestQueryParameter ersetzt werden (aus „ABC+COMPANY“ wird „ABC COMPANY“). Wird für dieses Objekt ein Fälligkeitsdatum für die Kalibrierung gefunden, wird dieses Datum als Text zurückgegeben – zusammen mit einem HTTP-Statuscode von 700. Wird kein Fälligkeitsdatum gefunden, werden ein leerer Text und der HTTP-Statuscode 800 zurückgegeben. In den meisten Skripten wäre die Textantwort eine vollständige HTML-Seite. Oder die Antwort würde eine XML-Datei im Hauptteil der Antwortnachricht enthalten, die weitere Details zur abgeschlossenen Transaktion enthält. Das sind jedoch die Grundlagen: Sende eine HTTP-Anfrage an eine URL + relative URI + Skript + optionale Parameter. Fügen Sie dieser Anfrage optionale Header und/oder den Nachrichtentext bei. Das Server-Skript reagiert auf gültige Anfragen, liest die Details der Nachricht und sendet eine entsprechende Antwort. HTTP-Antworten enthalten einen Antwortcode und einen Text- oder Binär-Nachrichtenkörper. Der HTTP-Client sollte in der Lage sein, entsprechend zu reagieren (wenn die Antwort eine HTML-Datei ist, wird sie angezeigt; wenn sich im Nachrichtentext eine PDF-Datei befindet, wird diese angezeigt usw.)
Einrichtung des IndySoftRESTServer
Der erste Schritt (nach der Registrierung von „IndySoft REST Scripting“ im IndySoft-Registrierungsprogramm) besteht darin, den IndySoft-REST-Dienst auf Ihrem Webserver einzurichten. Dieser Dienst beantwortet alle entsprechenden Webanfragen für diese Domain. Um den Einrichtungsbildschirm zu öffnen, klicken Sie auf die Schaltfläche „IndySoftRESTServer Setup“ oberhalb der Tabelle „REST-Skripte“:
IndySoftRESTServer-Einrichtung
IndySoft REST-Server-Einstellungen
Über dieses Dialogfeld können Sie den IndySoft REST-Dienst installieren bzw. deinstallieren, den Dienst starten bzw. beenden sowie alle zugehörigen Einstellungen vornehmen und speichern. WICHTIG: Es sind Windows-Administratorrechte erforderlich, wenn dieser Dialog zur Installation oder Deinstallation des Dienstes oder zur automatischen Reservierung eines Namensraums für den Host/die URI verwendet wird. Beenden Sie unbedingt IndySoftSyncOptions.exe und starten Sie die Datei unter Windows mit „Als Administrator ausführen“ neu, bevor Sie fortfahren.
·Dienst installieren / Dienst deinstallieren: Über die Schaltfläche oben im Dialogfeld können Sie den Dienst je nach Bedarf installieren oder deinstallieren. Bitte beachten Sie, dass für diese Aktion entsprechende Windows-Berechtigungen erforderlich sind. Nach der Installation wird der Dienst unter den Windows-Diensten als „IndySoft REST Server“ aufgeführt. Nach der Installation oder Deinstallation wird das Dialogfeld geschlossen. Hinweis: Sie sollten vor der Installation des Dienstes noch einmal die Schaltfläche „Erweiterte Einstellungen“ überprüfen. Nach der Installation kann der Dienst über die Schaltflächen am unteren Rand des Dialogfelds gestartet bzw. gestoppt werden. Der Dienst kann natürlich auch direkt über die Windows-Dienste gestoppt bzw. gestartet werden.
·Verwendeter Port: Geben Sie den gewünschten Port für den IndySoft-REST-Dienst ein. Dieser Port kann in der HTTP-Anfrage hinter der Host-Domain angegeben werden, gefolgt von einem Doppelpunkt (siehe Beispiel im Dialogfeld).
·HTTPS verwenden: Aktivieren Sie dieses Kontrollkästchen, wenn Sie HTTPS-Anfragen anstelle von HTTP bevorzugen. Wenn HTTPS verwendet wird, muss ein Zertifikat angegeben werden. Sobald Sie die Einstellungen speichern (durch Klicken auf „OK“), fordert IndySoft Sie automatisch auf, über Windows ein Zertifikat auszuwählen. Dieser Vorgang findet statt, wenn IndySoft versucht, den angegebenen Host zu registrieren.
·Host: Geben Sie den Namen Ihrer Host-Domain für diesen Server ein.Hinweis: Sobald die Einstellungen gespeichert sind (durch Klicken auf die Schaltfläche „OK“), versucht IndySoft, diesen URL-Namensraum automatisch zu registrieren. Der IndySoft REST Server basiert auf dem Kernel-Modus-hHTTPsys, was bedeutet, dass das Betriebssystem alle HTTP-Anfragen verarbeitet. In dieser Architektur leitet der Kernel die HTTP-Anfragen entsprechend der angeforderten URL weiter. Damit dies funktioniert, müssen wir zunächst einen URL-Namensraum reservieren. Durch eine Namespace-Reservierung werden die Rechte für einen Teil des HTTP-URL-Namensraums einer bestimmten Gruppe von Windows-Benutzern zugewiesen. Eine Reservierung gibt diesen Benutzern das Recht, Dienste zu erstellen, die auf diesen Teil des Namensraums abhören. Nehmen wir also an, dass Ihr Server auf Grundlage der in diesem Dialogfeld festgelegten Einstellungen unter der Adresse „[http://myurl.com:9001/IndyScripts/]“ (http://myurl.com:9001/IndyScripts/' ) läuft. In diesem Fall versucht IndySoft, diesen Namensraum zu reservieren, um sicherzustellen, dass Windows HTTP-Anfragen an diese Adressen akzeptiert, anstatt sie abzuweisen. Falls Sie diese Regeln manuell konfigurieren müssen, fordern Sie das Tool „IndyHTTPConfig.exe“ beim IndySoft-Support an. Beachten Sie, dass dasselbe Tool „IndyHTTPConfig.exe“ bereits im 3-Tier-Anwendungsserver enthalten ist (sofern dieser Dienst auf demselben Server installiert ist).
·Relative URI: Geben Sie den Namen der relativen URI ein. Dies ist der Teil des Namensraums, der auf den Host folgt, zum Beispiel der Teil „IndyScripts“ der vollständigen URL „http://myurl.com:9001/IndyScripts/ScriptNameHere“
·Beispiel: Dieser schreibgeschützte Text fügt die oben genannten vier Einstellungen in dem Format an, das für die Client-Anfrage erforderlich ist. Beachten Sie, dass der letzte Teil der URL einen Verweis auf das jeweilige Skript enthält (gefolgt von optionalen Abfrageparametern). Über die kleine Schaltfläche rechts neben diesem Eingabefeld wird die angegebene URL aufgerufen. Ihr Standardbrowser wird die Anfrage bearbeiten. Hinweis: Dieser Weblink ist nicht unbedingt vollständig – da in der Regel zusätzliche Abfrageparameter oder ein Nachrichtentext erforderlich sind, dient er lediglich als Ausgangspunkt.
·Anmeldung für den Server: Der IndySoft REST Server führt die Skripte über eine Datenbank-Client-Verbindung aus. Das bedeutet, dass bestimmte Einstellungen, wie beispielsweise die E-Mail-Einstellungen, den Benutzer- und Standorteinstellungen entsprechen. Aus diesem Grund ist es wichtig, einen Benutzernamen anzugeben, der beim Start des IndySoft REST Servers zum Laden dieser Einstellungen verwendet werden soll. Es wird der Standard-Speicherort für diesen Benutzer verwendet.
·Skripte vorladen: Wenn dieses Kontrollkästchen aktiviert ist, werden beim Start des IndySoft REST-Servers alle Skripte in den Arbeitsspeicher geladen. Dadurch lassen sich die einzelnen Webanfragen etwas schneller ausführen. Der Nachteil ist, dass bei einer Änderung des Skripts (aus dem IndySoft DataSync Utility… REST-Skripte) der Dienst angehalten und neu gestartet werden muss, bevor die Funktionsänderungen wirksam werden. Wenn dieses Kontrollkästchen nicht aktiviert ist, wird das Skript bei jeder Anfrage aus der Datenbank geladen.
·Alle Anfragen protokollieren: Diese Option wird in der Regel nur beim Debuggen eines neuen Skripts aktiviert. Wenn diese Option aktiviert ist, werden alle Anfragen auf der Registerkarte „Verlauf/Status“ protokolliert. Das Anforderungsprotokoll enthält eine vollständige Auflistung aller Eigenschaften, Header, Abfrageparameter und Nachrichtentexte, die als Referenz für Skripte zur Verfügung stehen. Die Werte werden im Protokoll in demselben Format festgehalten, in dem sie (falls gewünscht) innerhalb des Skripts abgerufen werden können.
·Erweiterte Einstellungen: In diesem Dialogfeld können Sie optional Dienstabhängigkeiten und Anmeldedaten festlegen. Hinweis: Diese Einstellungen gelten erst nach der Installation für den Dienst
·Dienst starten/beenden: Verwenden Sie die beiden Schaltflächen unten links im Dialogfeld, um den IndySoft REST Server zu starten bzw. zu beenden.
REST-Skripte Grid 
REST-Skript hinzufügen/bearbeiten/löschen – Verwenden Sie diese Optionen, um ein REST-Skript hinzuzufügen, zu bearbeiten oder zu löschen. Diese Optionen sind nur zulässig, wenn „IndySoft REST Scripting“ ein registriertes Produkt ist. Andernfalls werden Sie zur Eingabe eines Antwortcodes aufgefordert, den Sie nur vom IndySoft-Support erhalten können.
REST-Skripte drucken – Mit dieser Option können Sie schnell eine aktuelle Liste der REST-Skripte ausdrucken.
Nur REST-Skript anzeigen – Verwenden Sie diese Schaltfläche, um das aktuell ausgewählte REST-Skript ohne Bearbeitungsrechte anzusehen. Diese Option ist nützlich, wenn Sie keine Bearbeitungsrechte haben, aber die Funktionalität des ausgewählten Skripts überprüfen müssen.
REST-Skript importieren/exportieren – Verwenden Sie diese Optionen, um ein REST-Skript aus einer ZIP-Datei zu importieren (die zuvor über die Exportoption erstellt wurde) oder das aktuell ausgewählte Skript in eine ZIP-Datei zu exportieren.
Einrichtung des IndySoft-REST-Servers – Wählen Sie diese Option, um das Einstellungsfenster für den REST-Server zu öffnen.
REST-Skript hinzufügen/bearbeiten
· Skriptname – Der eindeutige Name des REST-Skripts. Dieser Name wird im Protokollverlauf sowie in allen E-Mails angezeigt, die über das Skript versendet werden oder als Reaktion auf Skriptfehler verschickt werden.
·Aktiv – Gibt an, ob das Skript vom IndySoft-REST-Dienst geladen bzw. ausgeführt wird. Das Skript kann nur über den Bildschirm „IndySoftSyncOptions“ getestet werden, wenn diese Option deaktiviert ist.
·VBScript/Pascal – Jedes Skript kann entweder in VBScript- oder in Pascal-Syntax geschrieben werden
·Kodierter Name (für URL) – Der Name des Skripts (links unter „Script Name“) muss verwendet werden, um dieses Skript über eine HTTP-Anfrage im Web aufzurufen. Wenn der Name des Skripts Zeichen enthält, die nicht in eine URL eingegeben werden können, muss die kodierte Version des Skriptnamens verwendet werden (wie hier automatisch angezeigt). Beispielsweise würde der Skriptname „WEB SCRIPT“ in einer URL als „WEB%20SCRIPT“ kodiert werden.
·Beschreibung – Eine ausführlichere Beschreibung des Skripts
·Skriptfehler an – Hier können eine oder mehrere E-Mail-Adressen angegeben werden. Diese Personen erhalten automatisch eine E-Mail, falls das Skript bei der Ausführung einen Fehler ausgibt. Beachten Sie, dass diese Fehler mit der Kompilierung des Skripts zusammenhängen und nicht unbedingt Fehler innerhalb des Skripts sind, die dort abgefangen werden könnten. Wenn das Skript beispielsweise Syntaxfehler enthält, werden diese E-Mail-Adressen benachrichtigt (da das Skript nicht kompiliert werden kann). Wenn Ihr Skript jedoch beispielsweise eine XML-Datei lädt und diese XML-Datei ein fehlerhaftes Format aufweist, das einen Fehlercode zurückgibt, reagiert die Logik Ihres Skripts möglicherweise auf diesen Fehlercode – oder auch nicht; das hängt vom Autor des Skripts ab. Wenn Ihr Skript also den Fehlercode ausliest, können Sie die Funktion „SendEMail“ innerhalb des Skripts aufrufen, um auf diesen Fehler zu reagieren. Wenn Sie diese „Send Errors To“-Adressen aus dem Skript heraus zurückgeben möchten, verwenden Sie die Funktion „SendScriptErrorsTo“.
Rechts neben dem Skript befindet sich die Registerkarte „Prozeduren/Funktionen“, die den Benutzer an die verfügbaren Prozeduren und Funktionen erinnert. Benutzer können diese Funktionen/Prozeduren per Drag & Drop in den Skriptbereich ziehen. Auf der Registerkarte „Debugging-Protokoll“ werden alle Syntaxfehler protokolliert, die beim Testen des Skripts auftreten. Außerdem kann dieser Text im „Debugging-Protokoll“ durch Aufruf der Funktion DebugLog mit Debug-Notizen aus dem Skript selbst gefüllt werden.
Hilfe und Informationen zu den verfügbaren REST-bezogenen Skriptprozeduren und -funktionen finden Sie in den Abschnitten zu den REST-Skriptfunktionen in der IndySoft Custom Scripting-Hilfe. |