Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 70 Next »

 INHALTSVERZEICHNIS

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.

Die folgenden Schritte müssen ausgeführt werden, um einen bestimmten Service nutzen zu können:

  • 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:

http://your-domain-com/service/?handler=php

WSDL aufrufen:

http://your-domain.com/service/?handler=soap&wsdl=1

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.

JSON-Aufruf mit http-Authentifizierung

/**

*Bitte anpassen **/

$baseUrl="http://your.server.name/"; $userName="user1"; $passwd="topsecret";
/* *********************** */

/**

*ggf. bitte anpassen */

set_include_path(get_include_path().':'.dirname(__FILE__).'/../wcp/3rd/');

/* **************** */

require 'Zend/Http/Client.php';

$call = array('method'=>'efs.system.getLoad','params'=>array());

$url=$baseUrl."service/index.php?handler=json";

$client=new Zend_Http_Client(); $client->setUri($url); $client->setAuth($userName,$passwd); $client->setMethod(Zend_Http_Client::POST);

$client->setRawData (json_encode(array('method'=>$call['method'],'jsonrpc'=>'2.0','id'=>1,'params'=>$call['pa rams'])));

$response=$client->request();

/**

  • Get JSON result */

$return=$response->getBody();

SOAP-Aufruf mit http-Authentifizierung

/**

*Bitte anpassen **/

$baseUrl="http://your.server.name/"; $userName="user1"; $passwd="topsecret";
/* *********************** */

ini_set("soap.wsdl_cache_enabled",0); ini_set("default_socket_timeout",10);

/**

*ggf. bitte anpassen */

set_include_path(get_include_path().':'.dirname(__FILE__).'/../wcp/3rd/');

/* **************** */

$call = array('method'=>'efs.system.getLoad','params'=>array());

$client = new SoapClient($baseUrl."service/index.php?handler=soap&wsdl=1",array( "style"=>SOAP_RPC,

"use"=>SOAP_ENCODED, "encoding"=>"UTF-8", "login"=>$userName, "password"=>$passwd, "trace"=>1,

));

$r=call_user_func_array(array($client,str_replace('.','_',$call['method'])),$call['params']);

/**

  • Get result as XML String

  • */

$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/).

  • Das /service/-Element ist obligatorisch, um den Service-Layer anzusprechen.

  • Falls weitere Pfad-Elemente vorhanden sind, wird automatisch der REST-Adapter verwendet:

  • /service/survey/surveys/ → Rest-Adapter wird automatisch verwendet und der handler-Paramter wird nicht benötigt

  • /service/index.php → Dieses Format wird verwendet, um auf SOAP, PHP und JSON-RPC API zuzugreifen. Der REST-Adapter wird nicht verwendet. Der handler-Paramter muss festgelegt werden (beispielsweise: /service/index.php?handler=soap).

Die REST API liefert eine Service-Beschreibung im RAML 0.8-Format.

  • Die Beschreibung wird ausgegeben, wenn die Parameter raml=1 und hander=reset in der URL angegeben werden.

    • https://eigeneInstallation.questback.com/service/?handler=rest&raml=1

  • Diese Beschreibung kann verwendet werden, um automatisch Testanwendungen und Service-Stellen für verschiedene Programmiersprachen zu erzeugen (siehe für weitere Informationen: http://raml.org/).

  • Die Beschreibung wird dynamisch erzeugt und beinhaltet nur Methoden, die für die in dieser Zeit eingeloggten Service-Layer-Nutzer*innen zugänglich sind.

  • Wie bei anderen Service-Layer-Adaptern müssen die einzelnen Services für die Nutzer*innen und Gruppen aktiviert werden, um von diesen Nutzer*innen und Gruppen verwendet werden zu können (Siehe System → Optionen → Services)

Der Inhaltstyp aller Anfragen, die den HTTP-Body beinhalten, muss application/json sein.

  • Das bedeutet, dass der Body-Inhalt JSON-Encoded sein muss.

  • No labels

© 2024 Tivian XI GmbH