SOAP API¶

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 --init aus und setzen Sie die Umgebungsvariable LCINITSOAP auf das gewünschte Passwort:

#> LCINITSOAP="SoAp_pAsSwOrD" liveconfig --init

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.

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,
                              )
                        );
?>

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():

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";

?>

SOAP-Referenz¶