Python API包装程序教程
更新时间：2020-05-14 16:46:06
安装
API包装程序库针对Python 3.2和更高版本进行了测试，并且与32位和64位版本的Python兼容。 可以从Python下载页面下载各种操作系统的Python二进制文件，或者使用大多数Linux发行版的软件包管理器进行安装。 另外，在Python的site-packages目录中创建一个文件夹“mailstore”，并将文件从Python API包装程序库中提取到该文件夹中。 在类似UNIX的操作系统中，可以通过在shell中执行以下命令来找到site-packages目录的位置：python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
实例化API客户端
在使用API包装器库之前，必须先通过以下方式导入它： import mailstore
serverClient = mailstore.mgmt.ServerClient(username="admin", password="admin", host="127.0.0.1", port=8463)
| 参数 | 默认值 | 描述 |
|---|---|---|
| username | admin | 用于连接到API的用户名。 |
| password | admin | 用于连接API的密码。 |
| host | 127.0.0.1 | MailStore服务器计算机的主机名或IP地址。 |
| port | 8463 | MailStore服务器在其上侦听API请求的TCP端口。 |
| autoHandleToken | True | 如果设置为True，则调用者无需处理长时间运行的任务的令牌，而必须等待结果。当设置为False并且statusCode正在运行时，将返回状态令牌，并且必须由方法的调用者对其进行适当处理。 |
| waitTime | 1000 | 指定API等待最终结果的毫秒数。否则，该进程将被视为正在运行，在这种情况下，有必要按照autoHandleToken状态定义令牌处理。 |
| callback | None | 长时间运行任务的临时状态应传递给此回调函数。即使启用了autoHandleToken，这也可以跟踪任务的进度 。为了通知用户有关进度的信息而不必从整体上处理令牌逻辑，这可能非常有用。 |
| logLevel | 2 | 必须在0到4的范围内，其中0（NONE）的详细程度最低，4（DEBUG）的详细程度最低。日志级别按以下顺序（从低到高的详细程度）定义：NONE，ERROR，WARNING，INFO和DEBUG。日志条目将始终打印到stdout。 |
| ignoreInvalidSSLCerts | False | 必须设置为True或False。如果使用了不受信任的证书，则必须启用它，否则在使用最新的Python版本（> = 3.4.3）时会发生错误。 |
调用API方法
成功实例化API客户端后，可以轻松调用API方法。当调用该方法是成功的，所述的StatusCode被成功并且将结果存储在词典结果如下面的例子所示：print(serverClient.GetServerInfo())
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': None, 'token': None, 'result': {'machineName': 'WIN-2012-R2-X64', 'version': '9.0.3.9857'}, 'statusVersion': 2, 'statusCode': 'succeeded'}
如果autoHandleToken设置为False并且statusCode返回running，则需要按照“自动令牌处理”部分中的说明进行手动令牌处理。
userInfo = serverClient.GetUserInfo("john.doe")
if userInfo["statusCode"] == 'succeeded':
print(userInfo["result"]["emailAddresses"])
else:
print(userInfo["error"]["message"])
例子
创建并打印分配给MailStore用户的所有电子邮件地址的列表。serverClient = mailstore.mgmt.ServerClient()
addresses = list()
for user in serverClient.GetUsers()["result"]:
addresses += serverClient.GetUserInfo(user["userName"])["result"]["emailAddresses"]
print("\n".join(sorted(set(addresses))))
serverClient = mailstore.mgmt.ServerClient()
privileges_map = dict()
for user in serverClient.GetUsers()["result"]:
user_info = serverClient.GetUserInfo(user["userName"])["result"]
if "privilegesOnFolders" in user_info:
for privilege in user_info["privilegesOnFolders"]:
if privilege["folder"] not in privileges_map:
privileges_map[privilege["folder"]] = {user["userName"]: privilege["privileges"]}
else:
privileges_map[privilege["folder"]].update({user["userName"]: privilege["privileges"]})
for archive, user_dict in privileges_map.items():
print("Archive: {}".format(archive))
for username, priv in user_dict.items():
print("\tUser: {}: {}".format(username, ", ".join(priv)))
serverClient = mailstore.mgmt.ServerClient()
admins = list()
for user in serverClient.GetUsers()["result"]:
if "admin" in serverClient.GetUserInfo(user["userName"])["result"]["privileges"]:
admins.append(user["userName"])
print("\n".join(admins))
长时间运行的任务
某些API方法（如VerifyStore）的执行可能需要几分钟甚至几小时才能完成。有多种选项可用于处理这些长期运行的任务：- 自动令牌处理
- 具有回调功能的自动令牌处理
- 手动令牌处理
自动令牌处理
当autoHandleToken设置为True（默认值）时，包装器将在后台自动轮询长时间运行的任务的状态，并在进程结束时返回最终结果。代码
import mailstore
serverClient = mailstore.mgmt.ServerClient(autoHandleToken=True)
storeID = 1
print(serverClient.VerifyStore(storeID))
输出
{'logOutput': None, 'statusText': None, 'error': None, 'percentProgress': 100, 'token': 'd242d822a59bd4db308eef8b85af7d2a', 'result': None, 'statusVersion': 71, 'statusCode': 'succeeded'}
具有回调功能的自动令牌处理
如果调用者想跟踪长时间运行的任务的进度（即，将进度通知用户），尽管启用了自动令牌处理，但他可以将函数作为回调参数传递给API客户端实例。代码
import mailstore
def showProgress(progress):
print(progress["logOutput"], end="", flush=True)
serverClient = mailstore.mgmt.ServerClient(autoHandleToken=True, callback=showProgress)
storeID = 3
print(serverClient.VerifyStore(storeID))
输出
Verifying file group #3... Creating a list of messages to be verified... 1249 messages are about to be verified. Verifying... 100 messages verified... 200 messages verified... 300 messages verified... 400 messages verified... 500 messages verified... 600 messages verified... 700 messages verified... 800 messages verified... 900 messages verified... 1000 messages verified... 1100 messages verified... 1200 messages verified... 1249 messages verified. Finished. No errors have been found. {'error': None, 'result': None, 'logOutput': ' 1000 messages verified...\r\n 1100 messages verified...\r\n 1200 messages verified...\r\n 1249 messages verified.\r\nFinished. No errors have been found.\r\n', 'token': 'c56f032d9db263133c1a413f79744b84', 'statusVersion': 71, 'statusText': None, 'percentProgress': 100, 'statusCode': 'succeeded'}
手动令牌处理
如果autoHandleToken设置为False，则调用者必须独自处理长时间运行的任务以及相应的令牌。要轮询状态更新，必须定期调用GetStatus方法，并将最后返回的结果作为参数传递。GetStatus将提取状态令牌本身，轮询最新更新，然后将接收到的数据再次返回给调用方。当statusCode更改为不同于running时，主调用已结束。在不传递状态令牌的情况下调用GetStatus将导致异常。代码
import mailstore
import time
serverClient = mailstore.mgmt.ServerClient(autoHandleToken=False)
storeID = 3
status = serverClient.VerifyStore(storeID)
while True:
if status["statusCode"] != "running":
break
print(status["logOutput"], end="", flush=True)
status = serverClient.GetStatus(status)
time.sleep(1)
输出
Verifying file group #3... Creating a list of messages to be verified... 1249 messages are about to be verified. Verifying... 100 messages verified... 200 messages verified... 300 messages verified... 400 messages verified... 500 messages verified... 600 messages verified... 700 messages verified... 800 messages verified... 900 messages verified... 1000 messages verified... 1100 messages verified... 1200 messages verified... 1249 messages verified. Finished. No errors have been found.
取消长时间运行的任务
使用回调方法或手动令牌处理调用的任务可以随时通过使用CancelAsync方法取消。请注意，API无法确认取消请求的成功。而是，调用者必须继续监视已取消方法的statusCode。代码
import mailstore
import time
serverClient = mailstore.mgmt.ServerClient(autoHandleToken=False)
storeID = 3
status = serverClient.VerifyStore(storeID)
while True:
if status["statusCode"] != "running":
break
print(status["logOutput"], end="")
status = serverClient.GetStatus(status)
time.sleep(1)
serverClient.CancelAsync(status)
输出
Verifying file group #3... Creating a list of messages to be verified... 1249 messages are about to be verified. Verifying... 100 messages verified... 200 messages verified... 300 messages verified... 400 messages verified... 500 messages verified... 600 messages verified... 700 messages verified... 800 messages verified... 900 messages verified... 1000 messages verified... 1100 messages verified...
方法概述
函数参考中列出的所有方法都在Python API库中实现。用 pydoc3 mailstore.mgmt.ServerClient
访问内置文档，其中还包括所有方法及其参数的概述。