Python API-Wrapper Tutorial

Dieses Dokument stellt die Python API Bibliothek vor, mit der sich der MailStore Server administrieren lässt.

Installation

Die API Bibliothek wurde mit den Python Versionen 3.2 bis 3.4 getestet. Sie ist kompatibel mit der 32-Bit sowie der 64-Bit Version von Python.

Das Python Installationspaket kann von der Python Download Seite heruntergeladen werden. Alternativ kann Python über den Paket Manager der Distribution installiert werden.

Zusätzlich wird die MailStore Python API Bibliothek benötigt. Diese muss in das mailstore-Verzeichnis des site-packages-Verzeichnisses der Python-Installation kopiert werden. Der Ort des site-packages-Verzeichnisses lässt sich mittels

 python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"

herausfinden.

Log in

Die Bibiliothek kann mittels

 import mailstore

importiert werden. Nun kann die mailstore.server.Client Klasse instanziiert werden.

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)

Standardwerte können ausgelasen werden.

Die verfügbaren Parameter und die Standardwerte sind

 username = "admin"
 password = "admin"
 host = "127.0.0.1"
 port = 8463
 autoHandleToken = True
 waitTime = 1
 logLevel = 2

Wenn autoHandleToken aktiviert ist, muss man sich nicht manuell um die Verarbeitung des zurückgegebenen Tokens kümmern. Die Bibliothek kümmert sich darum. Nach Beendigung der Methode wird das Ergebnis zurückgeliefert. Wenn autoHandleToken deaktiviert ist, wird das Token zurückgegeben, welches den Aufruf identifiziert. Mehr dazu später.

Der waitTime Wert gibt die Zeit in Sekunden an, die die Bibliothek zwischen zwei aufrufen von get-status wartet. get-status wird aufgerufen, wenn der Status einer Methode abgerufen werden soll, die ein Token zurückgeliefert hat.

logLevel muss im Bereich von 0 bis 4 liegen. Die Loglevel sind wie folgt definiert

0 : "NONE"
1 : "ERROR"
2 : "WARNING"
3 : "INFO" 
4 : "DEBUG"

Log-Einträge werden auf stdout ausgegeben.

Einfache Aufrufe

Einfache Aufrufe liefern das Ergebnis sofort zurück

 print(serverClient.GetServerInfo())
 
 {'machineName': 'WIN2012MS', 'version': '8.1.2.9268'}

Wenn der Aufruf erfolgreich war, wird der Ergebnis in Form eines Python Dictionarys zurückgegeben. Wenn der Aufruf misslang, wird ein HTTP Fehler geworfen.

Fehlerbehandlung

Wenn ein Fehler auftrit, wirft die aufrufende Methode eine Exception. Alle MailStore Fehlerklassen sind von der Basisklasse mailstore.errors.MailStoreBaseError abgeleitet, welche ihrerseits von Exception abgeleitet ist.

 try:
     print(serverClient.GetUserInfo("not_such_user"))
 except mailstore.errors.MailStoreBaseError as e:
     print(e)
 
 ERROR ('internal MailStore Server error',)
 500 Internal Server Error https://127.0.0.1:8463/JSON/Invoke/GetUserInfo POST userName=not_such_user Command in MethodList: True

Einfache Beispiele

Um die detaillierten Informationen aller Benutzer zu erhalten:

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 for user in serverClient.GetUserList():
     print(serverClient.GetUserInfo(user["userName"]))

Eine Liste aller zugewiesenen E-Mail-Adressen erhält man mit:

 serverClient = mailstore.server.Client(username="admin", password="admin", host="127.0.0.1", port=8463)
 emailaddresses = list()
 for user in serverClient.GetUserList():
     emailaddresses += serverClient.GetUserInfo(user["userName"])['emailAddresses']
 print(emailaddresses)

Lang laufende Methoden

Lang laufende Methoden wie VerifyStore laufen asynchron im Hintergrund auf dem Server. Wenn autoHandleToken auf True (Standardwert) gesetzt ist, fragt die Bibliothek den Server automatisch, periodisch nach Statusänderungen ab und gibt das Ergebnis zurück, sobald dieses vorliegt. Ist autoHandleToken deaktiviert, wird das Token zurückgegeben. In diesem Fall muss man sich um die Statusaktuelisierungen manuell kümmern. Dafür existieren Hilfsmethoden.

autoHandleToken ist aktiviert, das Ergebnis wird nach einiger Zeit zurückgegen:

 serverClient = mailstore.server.Client(autoHandleToken=True)
 storeID = 1
 print(serverClient.VerifyStore(storeID))
 
 {'status': 'succeeded', 'progressPercentage': 100, 'messages': [{'text': 'Verifying file group #2...', 'type': 'line'}, {'text': 'Creating a list of messages to be verified...', 'type': 'line'}, {'text': '234 messages are about to be verified.', 'type': 'line'}, {'text': 'Verifying...', 'type': 'line'}, {'text': '  100 messages verified...', 'type': 'line'}, {'text': '  200 messages verified...', 'type': 'line'}, {'text': '  234 messages verified.', 'type': 'line'}, {'text': 'Finished. No errors have been found.', 'type': 'line'}]}

Es ist möglich, die Statusaktualisierung manuell durchzuführen, dazu muss das Token an die GetStatus Methode übergeben werden. Der Aufruf ist beendet wenn der status nicht mehr running ist. Der im Beispiel gezeigte Wartezeitraum (time.sleep(1)) entspricht dem waitTime-Wert, der der Klasse mitgegeben werden kann.

 import time

 serverClient = mailstore.server.Client(autoHandleToken=False)   
 storeID = 2
 token = serverClient.VerifyStore(storeID)
 print(token)
 while True:
     time.sleep(1)
     status = serverClient.GetStatus(token)
     print(status)
     if status["status"] != "running":
         break

 {'statusUrl': '/JSON/Status/243fc983-89c3-19ef-196a-dbe082894cc5', 'statusToken': '243fc983-89c3-19ef-196a-dbe082894cc5'}
 {'progressPercentage': 0, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}], 'status': 'running'}
 {'progressPercentage': 100, 'messages': [{'type': 'line', 'text': 'Verifying file group #2...'}, {'type': 'line', 'text': 'Creating a list of messages to be verified...'}, {'type': 'line', 'text': '234 messages are about to be verified.'}, {'type': 'line', 'text': 'Verifying...'}, {'type': 'line', 'text': '  100 messages verified...'}, {'type': 'line', 'text': '  200 messages verified...'}, {'type': 'line', 'text': '  234 messages verified.'}, {'type': 'line', 'text': 'Finished. No errors have been found.'}], 'status': 'succeeded'}

Man kann das Token an die HandleToken-Methode übergeben. In diesem Fall entspricht das Verhalten exakt dem, als wenn man autoHandleToken bereits initial auf True gesetzt hätte.

 serverClient = mailstore.server.Client(autoHandleToken=False)
 storeID = 2
 token = serverClient.VerifyStore(storeID)
 print(token)
 print(serverClient.HandleToken(token))

Das Verhalten des Token-Handlings kann global und lokal gesetzt werden. Wenn die Klasse mit autoHandleToken=True instanziiert wird, von einzelne Methoden jedoch das Token benötigt wird, kann der Methode der zusätzliche Parameter autoHandleToken=False übergeben werden. Umgekehrt ist dies genauso möglich. Die Klasse wird mit autoHandleToken=False instanziiert, die einzene Methode kann dennoch mit dem Parameter autoHandleToken=True aufgerufen werden. Methoden die nicht lang laufend sind, akzeptieren den autoHandleToken-Parameter nicht.

 serverClient = mailstore.server.Client(autoHandleToken=False)
 storeID = 2
 token = serverClient.VerifyStore(storeID, autoHandleToken=True)
 print(token)

 {'status': 'succeeded', 'messages': [{'text': 'Verifying file group #2...', 'type': 'line'}, {'text': 'Creating a list of messages to be verified...', 'type': 'line'}, {'text': '234 messages are about to be verified.', 'type': 'line'}, {'text': 'Verifying...', 'type': 'line'}, {'text': '  100 messages verified...', 'type': 'line'}, {'text': '  200 messages verified...', 'type': 'line'}, {'text': '  234 messages verified.', 'type': 'line'}, {'text': 'Finished. No errors have been found.', 'type': 'line'}], 'progressPercentage': 100}

Abbrechen lang laufender Methoden

Aktuell können lang laufende Methoden nicht abgebrochen werden. Dies ist keine Limitierung der Python Bibliothek sondern der Management API als solches. Dieser Umstand wird in der nächsten MailStore Server Hauptversion behoben werden.

Formatierung der Ausgabe

Es gibt eine Hilfsfunktion, die die zurückgelieferten Dictionarys formatiert ausgeben kann.

 mailstore.pprint(serverClient.GetUserInfo("admin"))

 authentication integrated
 distinguishedName 
 privileges
    admin
 fullName Administrator
 userName admin

Funktionsübersicht

Alle Methoden die in der Übersicht aufgelistet sind, sind auch implementiert.

Zusätzliche Methoden

Zusätzliche Methoden sind verfügbar. Bitte schauen Sie in den Quellcode der Bibliothek, um mehr Details zu erfahren.