...
Mittels des Service-Layers werden Kern-Funktionalitäten von EFS für externe Anwendungen zur Verfügung gestellt. Zukünftig entstehende EFS-Funktionalitäten werden ebenfalls von außen ansteuerbar sein. Die Services können über HTTP oder HTTPS aufgerufen werden. Die Services können mittels verschiedener Datenaustauschformate (z.B. JSON) angesprochen werden. Der Service-Layer deckt das Leistungsspektrum der früheren SOAP-Services ab.
Services konfigurieren
Die auf Ihrer EFS-Installation verfügbaren Services können in einem speziell eingerichteten Konfigurations-Menü eingesehen und konfiguriert werden. Das Menü befindet sich im Administrationsbereich von EFS unter Optionen → Services → Service-Konfiguration. Es ist analog zu dem Menü für die SOAP-Services (Optionen → Services → Web Services) gestaltet. Das Menü Service-Konfiguration ist grundsätzlich nur verfügbar, wenn Questbacks Support-Team auf Ihrer Installation die Nutzung von Services freigeschaltet hat. Für den Zugang zum Menü ist entweder Schreibrecht auf das ACL-Recht webservice_conf oder Mitgliedschaft im Root-Team erforderlich.
...
Der jeweilige Service muss von Questbacks Support-Team hinzugefügt werden.
Der Service muss aktiviert werden. Falls erforderlich, können mit dem Button Alle Services aktivieren auch sämtliche auf der Installation vorhandenen Services en bloc aktiviert werden.
Das Mitarbeiterteam, zu dem der Account gehört, mit dem auf einen Service zugegriffen wird, muss Zugriffsrecht für diesen Service haben. Auf der Registerkarte Zugriffsgruppen können die Zugriffsrechte auf die einzelnen Services separat definiert werden.
Des Weiteren beinhalten viele Services eine Prüfung auf die Objektrechte des Mitarbeiterteams. Bei survey.questionnaire.createPage oder survey.questionnaire.deletePage beispielsweise benötigt das Mitarbeiterteam Schreibrecht auf das betreffende Projekt.
Auf der Registerkarte Zugriffslog werden alle Aufrufe geloggt. Die Einträge können nach IP-Adresse, Name des verwendeten Adminaccounts, Service-Name und Datum durchsucht werden.
Zugriffsmodi
Der Service-Layer bietet zwei Zugriffsmodi:
Beschreibung: In diesem Modus beschreibt sich der Service-Layer selbst. Es wird z. B. beim SOAP-Format eine WSDL erzeugt und ausgeliefert. Dieser Modus ist notwendig, damit Clients sich informieren können, welche Services angeboten werden und welche Parameter sie haben.
Transaktion: Hier wird eine Service-Methode aufgerufen und ausgeführt Je nach Format-Handler ist die Ansteuerung der Modi unterschiedlich.
Format-Handler
Der Service-Layer unterstützt aktuell HTTP/HTTPS und darin drei interne Formate:
PHP-serialized: Hier werden die Input- und Output-Parameter als serialisierte PHP-Arrays übergeben. Dies ist ideal, wenn der Client PHP ist.
Der Handler wird über den URL-Parameter "handler" mit Wert "php" aktiviert.
Der Name der aufgerufenen Methode wird im URL-Parameter "method" übergeben. Der Methodenname hat den Aufbau MODULNA- ME.ACTORNAME.METHODNAME (mit Punkten getrennt).
Wenn der Request ein HTTP GET-Request ist, wird der Beschreibungsmodus getriggert. Andernfalls wird der Transaktionsmodus verwendet.
JSON: Daten werden JSON-encoded übergeben. Siehe Beispiel unten.
Der Handler wird über den URL-Parameter "handler" mit Wert "json" aktiviert.
Der Name der aufgerufenen Methode wird im URL-Parameter "method" übergeben. Der Methodenname hat den Aufbau MODULNA- ME.ACTORNAME.METHODNAME (mit Punkten getrennt).
Wenn der Request ein HTTP GET-Request ist, wird der Beschreibungsmodus getriggert. Andernfalls wird der Transaktionsmodus verwendet.
SOAP: Daten werden mittels SOAP übertragen. Siehe Beispiel unten.
Der Handler wird über den URL-Parameter "handler" mit Wert "soap" aktiviert.
Der Methodenname hat den Aufbau MODULNA- ME_ACTORNAME_METHODNAME (mit Unterstrichen getrennt).
Wenn im Request der URL-Parameter "wsdl" gesetzt ist, wird der Beschrei- bungsmodus getriggert und eine WSDL generiert. Andernfalls wird der Transaktionsmodus verwendet.
Authentifizierung
Folgende Authentifizierungsmechanismen können verwendet werden:
Tokens: Questbacks Support-Team kann für Sie und Ihre Mitarbeiter Tokens generieren. Diese Tokens können dann beim Aufruf des Service zur Authentifizierung genutzt werden (Parametername: "token").
Accountname und Passwort für den EFS-Adminbereich: Da jeder Mitarbeiter mit Adminbereichs-Zugang über diese Daten verfügt, ist dies die einfachste Möglichkeit, sich für die Services zu authentifizieren. Beachten Sie bitte: Bei Authentifizierung über http werden Accountname und Passwort unverschlüsselt übertragen, d.h. man kann sie auf Proxies u.U. mitloggen. Dies würde beispielsweise Zugriff auf den Adminbereich ermöglichen. Daher empfiehlt Questback, Tokens zu verwenden oder die Services über SSL aufzurufen.
Aufruf der Service-Beschreibung
Selbstbeschreibung des PHP-Handlers:
...
| Info |
|---|
Da die Rechte für jeden Service und jedes Mitarbeiterteam individuell einstellbar sind, ist die Liste der Services beim Zugriff auf den Service-Layer nun auch komplett dynamisch. Es gibt nicht mehr eine zentrale WSDL-Datei, sondern die WSDL- Datei wird anhand der Rechte des Aufrufers jedes Mal dynamisch generiert. So sieht der Aufrufer eine WSDL für diejenigen Services, die er tatsächlich benutzen kann. |
Wichtige Parameter
Die wichtigsten Parameter im Überblick:
handler: Name des Format-Handlers (php, json, soap).
method: Name der aufgerufenen Methode bei PHP- und JSON-Handler.
version: Optionale Versionsnummer der Service-API.
token: Enthält das Token für die Authentifizierung.
wsdl: Generiert die WSDL bei Nutzung des SOAP-Handlers.
Beispiele
Im Folgenden finden Sie zwei Beispiele. Im ersten Beispiel wird JSON-Aufruf mit http-Authentifizierung vorgeführt und im zweiten der SOAP-Aufruf mit http-Authentifizierung.
...
$req = $s->__getLastRequest();
Übersicht über REST API
Neben den bisherigen Anpassungen SOAP, PHP und JSON-RPC wurde ein neuer Handler implementiert, der dem RESTful-Services-Paradigma folgt. Die neue REST Api wird von URLs adressiert, die mehr als 3 Pfad-Elemente enthalten(beispielsweise: https://eigeneInstallation.questback.com/service/survey/surveys/).
...