XML-RPC

English version

Das OGo XML-RPC API nutzen

Nahezu alle OpenGroupware Aktionen, die über das Web-GUI ausgeührt werden können, lassen sich mit Hilfe von XML-RPC aufrufen durchführen. Hierbei sind allerdings einige kleine Fallen verborgen, die ich hier kurz auflisten möchte. Falls nicht ausdrücklich gekennzeichnet treten die Effekte bei Aufrufen der XML-RPC Funktionen bei Nutzung des Perl SOAP::Lite Moduls auf. Es ist jedoch warscheinlich, daß diese Probleme unabhängig von den Clientbibliotheken und -Sprachen auftreten.

Fallen

• Umlaute
  

  Umlaute müssen im Unicode (UTF-8) Format übermittelt werden.

• Integerwerte
  

  Reine Integerzahlen werden vom SOAP::Lite Modul im XML-RPC Request als Integer gekennzeichnet. Damit die OpenGroupware Datenbank diese Werte annimmt, müssen sie vor dem Aufruf in den Datentyp String konvertiert werden. Dieses wird mit der Methode type der Klasse SOAP::Data

          SOAP::Data->type(string => 123);
      

  erreicht.

• Hashes (Python Dictionaries)
  Die in der API-Dokumentation beschriebenen Python Dictionaries werden in Perl als Hashreferenzen abgebildet. Diese können direkt in Perl Objekte überführt werden (s.a. das RPC::Ogo Modul als Beispiel).

Benutzer anlegen

Mit Hilfe des XML-RPC APIs von OGo können weite Teile des Systems von externen Programmen angesprochen werden. Für die Personen, die die XML-RPC Funktionalität noch nicht kennen, habe ich hier ein kurzes Beispiel des grundsätzlichen Handlings aufgeührt

Das Beispiel ist in Perl, kann aber auch relativ einfach in Python oder einer anderen Sprache ausgeführt werden. Die bei Python 2.2 mitgelieferte xmlrpclib.py Bibliothek unterstüzt allerdings noch keine HTTP Basic Authentication, die für die Anmeldung am OGo xml-rpc Daeomn zwingend notwendig ist. Die Firma Skyrix hat eine gepatchte Version der Bibliothek unter http://developer.skyrix.com/02_skyrix/xmlrpc/xmlrpclib.py zum Download bereitgestellt.

Beispiel

Das XML-RPC Beispiel ist zweistufig aufgebaut. Eine zentrale Klasse stellt die Verbindung zum XML-RPC Server her. Von dieser Klasse erben alle Klassen, die auf einzelnen Methoden des XML-RPC API zugreifen wollen.

Zentrale Komponente

    package OGo;

    use XMLRPC::Lite;
    use Carp;
    use strict;


    sub new {
        my $this = shift;
        my $pass = shift;

        croak "Missing OGo root password\n" unless $pass;

        my $class = ref($this) || $this;
        my $self = {};
        bless $self, $class;

        $self->{'ogo'} = XMLRPC::Lite
            ->proxy("http://root:$pass\@localhost:20001/x/xmlrpc");

        return $self;
    }


    ### EOP ###
    1;

Über diese Klasse kann mit Hilfe des XMLRPC::Lite Moduls auf auf alle Methoden des XML-RPC Servers zugegriffen werden.

Funktionsspezifische Komponente

Die Funktionsspezifische Komponente soll einen OGo Benutzer anlegen können. Sie wird von der oben definierten OGo Klasse abgeleitet. Die call Methode ruft die jeweilige Methode auf dem XML-RPC Server auf.

    package OGo::User;

    use Carp;
    use strict;

    use base qw(OGo);

    sub create {
        my ($self,$login,$pass,$name,$firstname) = @_;

        croak "Missing login name\n";

        $data = {
                 login     => $login
                 firstname => $firstname,
                 name      => $name,
               };

        my $account = $self->_insert($data);
        $self->_setPassword($account->{'number'},$pass);
    }


    sub _insert {
        my $self = shift;
        my $data = shift;
        $self->call('account.insert',$data);
    }


    sub _setPassword {
        my ($self,$uid,$pass) = @_;

        my $salt = join '',
                   ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]);
        $cpass = crypt $pass,$salt;

        $self->call('account.setPassword',$uid,$pass,'true');
    }


    ### EOP ###
    1;

Neben diesem Modul können beliebige Module für spezifische Anwendungsfälle geschrieben werden. Diese stellen dann die Schnittstelle zu anderen Programmen dar. Hier wird ein kleines Programm die Module aufrufen um einen Benutzer zu erstellen.

Anwendung der Module

Das kleine Script erstellt einen Benutzer. Es könnte weitere spezifische Klassen einbinden, die das XML-RPC API abstrahieren und deren Funktionalität über für den automatisierten Zugriff auf OGo Daten nutzen. Weitere Beispiele sind in der Dokumentation zum RPC::Ogo Modul aufgeführt.

    #!/usr/bin/perl
    #
    #
    use OGo::User;

    # create user in OGo via XML-RPC
    my $ogo =  OGo::User->new($ogorootpw);
    $ogo->create($login,$userpass,$name,$firstname);

Beispiel in Python

Mit Python läst sich der Zugriff eben so einfach bewerkstelligen.

    #!/usr/bin/env python2.2

    import xmlrpclib

    server = xmlrpclib.Server('http://localhost:20001/x/xmlrpc',
                              login='root',password='secret')

    result = server.account.insert (
                   {
                   'login'         : "martin",
                   'firstname'     : "Martin",
                   'name'          : "Werthmöller",
                   }
           )

< zurück  | weiter >