SOAP API

Die Abkürzung SOAP steht für das Simple Object Access Protocol. Die meisten aktuellen Programmiersprachen unterstützen SOAP. Zusätzlich dient eine von LiveConfig bereitgestellte WSDL-Datei (Web Service Description Language) zur automatischen Erkennung der zur Verfügung stehenden Funktionen und Datentypen, so dass oft eine nahtlose Integration in eigene Anwendungen möglich ist.

Die Kommunikation für den SOAP-Zugriff erfolgt in Form von XML-Nachrichten über „ganz normale“ HTTP(S)-Verbindungen. Beispielsweise sieht der Aufruf der SOAP-Funktion TestSayHello so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns1="urn:LiveConfig">
  <SOAP-ENV:Body>
    <ns1:TestSayHello>
      <ns1:auth>
        <ns1:login>admin</ns1:login>
        <ns1:timestamp>2009-12-22T19:20:59.000Z</ns1:timestamp>
        <ns1:token>7juGMfg7N/F1G4t+S7XW99nRidg=</ns1:token>
      </ns1:auth>
      <ns1:firstname>Manfred</ns1:firstname>
      <ns1:lastname>Mustermann</ns1:lastname>
    </ns1:TestSayHello>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Bei einem erfolgreichen Aufruf sieht die Antwort so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <TestSayHelloResponse xmlns="urn:LiveConfig">
      <greeting>Hello, Manfred Mustermann</greeting>
    </TestSayHelloResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Tritt während der Verarbeitung einer Anfrage ein Fehler auf, wird eine SOAP-Exception erzeugt. Diese enthält eine aussagekräftige Fehlermeldung. Die Fehlermeldung für einen abgelaufenen (ungültigen) Zeitstempel sieht beispielsweise so aus:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Server</faultcode>
      <faultstring>Authentication timestamp too far in past or future</faultstring>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Voraussetzungen

Die SOAP-Schnittstelle von LiveConfig ist über die URL /liveconfig/soap zu erreichen. Die SOAP-Aufrufe müssen im document/literal-Stil formuliert sein (nicht als RPC/encoded).

Zudem benötigen Sie

  • eine LiveConfig Standard®- oder LiveConfig® Business-Lizenz (die SOAP-API ist nicht mit der Basic- oder Light-Lizenz verfügbar)

  • Zugriff auf den LiveConfig® admin-Account

  • ein eingerichtetes SOAP-Passwort für den admin-Account (siehe nächster Abschnitt)

Authentifizierung

Alle SOAP-Funktionen erfordern die Übermittlung eines auth-Parameters, welcher den Benutzernamen, einen Zeitstempel und das SOAP-Token enthält. Das Token ist eine Base64-codierte HMAC-SHA1-Prüfsumme über den Begriff „LiveConfig“, den eigenen Benutzernamen, den aufzurufenden Funktionsnamen und den Zeitstempel; als Schlüssel wird das SOAP-Passwort verwendet.

Um das SOAP-Passwort zu setzen, führen Sie liveconfig --initpw aus und setzen Sie die Umgebungsvariable LCINITSOAP auf das gewünschte Passwort:

#> LCINITSOAP="SoAp_pAsSwOrD" liveconfig --initpw

Folgendes Beispiel demonstriert die Erzeugung des auth-Parameters in PHP:

<?php
$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # SOAP method to call

# create timestamp, e.g. '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# generate token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts,
                                 $pass,
                                 true
                                )
                      );

# generate "auth" parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token
             );
?>

Der im auth-Parameter angegebene Zeitstempel darf nicht mehr als 15 Minuten von der aktuellen Serverzeit auf dem LiveConfig-Server abweichen - ansonsten erfolgt eine Fehlermeldung. Die Uhrzeit muss als UTC/GMT-Zeit angegeben werden.

Funktionen mit Kundenrechten ausführen

Sie können alle SOAP-Funktionen auch mit den Berechtigungen eines beliebigen Kunden ausführen. Das ist beispielsweise bei der Arbeit mit Wiederverkäufer-Accounts hilfreich.

Für diesen Fall wird vor Berechnung des Tokens noch die (codierte) Kundennummer angefügt, und das optionale Feld customer im auth-Parameter gesetzt.

Bemerkung

Der Kunde, mit dem eine Funktion aufgerufen wird, muss auch für diese Funktion berechtigt sein.

So können Sie z.B. keine weiteren Kunden anlegen, wenn der Benutzer mit dem Sie arbeiten keine Wiederverkäufer-Berechtigung hat.

Beispiel in PHP zur Ausführung mit Kundenrechten:

<?php
$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # SOAP method to call
$cust = 'c9R4hQp.T-rF';  # encoded customer id

# create timestamp, e.g. '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# generate token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts . $cust,
                                 $pass,
                                 true
                                )
                      );

# generate "auth" parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token,
              'customer'  => $cust
             );
?>

WSDL-Beschreibung

LiveConfig stellt eine WSDL-Beschreibung mit allen für den jeweiligen Benutzer erlaubten Funktionen und den dazugehörigen Datentypen bereit. Fügen Sie hierfür den Parameter ?wsdl sowie den Benutzernamen und das SOAP-Passwort an die SOAP-URL an.

Das folgende Beispiel zeigt die Erzeugung eines SOAP-Clients mit PHP anhand einer WSDL-Datei:

<?php
$user = 'admin';         # User name
$pass = 'PaSsWoRt';      # SOAP password

# Construct WSDL URL
$url = 'https://your.liveconfig.server:8443/liveconfig/soap'
      .'?wsdl'  # request WSDL
      .'&l=' . urlencode($user)
      .'&p=' . urlencode($pass);

# Create SOAP client
$client = new SoapClient($url,
                         array('style' => SOAP_DOCUMENT,
                               'use'   => SOAP_LITERAL,
                              )
                        );
?>

Vorsicht

Derzeit wird das SOAP-Passwort für den WSDL-Abruf im Klartext an die WSDL-URL angefügt. Die Übertragung zum Server erfolgt über das HTTPS-Protokoll dennoch verschlüsselt, und im access_log von LiveConfig wird das Passwort ausgeblendet. In einer späteren Version von LiveConfig soll statt des Passworts auch ein Hash verwendet werden. Solange jedoch manche Programmierumgebungen (z.B. der WebService-Wizzard von C#) die direkte Eingabe einer WSDL-URL erwarten, wäre eine manuelle Hash-Berechnung unzumutbar.

Codebeispiel

Im Folgenden finden Sie für die gängigsten Programmiersprachen kleine Beispielprogramme, welche die Verwendung der SOAP-Schnittstelle demonstrieren.

PHP

PHP hat eine integrierte SOAP-Unterstützung. Die einzige Voraussetzung ist, dass das SOAP-Modul geladen ist (wenn Sie PHP selbst compilieren, verwenden Sie die Option --enable-soap). Ob SOAP-Unterstützung aktiviert ist, sehen Sie in der Ausgabe von phpinfo():

SOAP section of phpinfo() output

Das folgende Beispielprogramm zeigt alle notwendigen Schritte zur Ausführung einer SOAP-Anfrage an LiveConfig:

<?php

  # Configuration parameters:
  $user = 'admin';
  $pass = 'PaSsWoRd';
  $url  = 'https://your.liveconfig.server:8443/liveconfig/soap';

  # Construct WSDL URL
  $wsdl_url = $url
             .'?wsdl'
             .'&l=' . urlencode($user)
             .'&p=' . urlencode($pass);

  # Create SOAP client
  $client = new SoapClient($wsdl_url,
                           array('style'    => SOAP_DOCUMENT,
                                 'use'      => SOAP_LITERAL,
                                )
                          );

  # Construct SOAP token:
  $ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";
  $token = base64_encode(hash_hmac('sha1',
                                   'LiveConfig' . $user . 'TestSayHello' . $ts,
                                   $pass,
                                   true
                                  )
                        );

  $auth = array('login'     => $user,
                'timestamp' => $ts,
                'token'     => $token);

  $params = array('auth'      => $auth,
                  'firstname' => 'John',
                  'lastname'  => 'Doe');

  try {
    $response = $client->TestSayHello($params);
  } catch (SoapFault $soapFault) {
    die("Error while calling Web Service: " . $soapFault->faultstring . "\n");
  }

  echo "Response: " . $response->greeting . "\n";

?>

Zuletzt aktualisiert am 29.06.2020.
weiter: ContactAdd
zurück: API