Python API包装程序教程
作者：mailstore，更新时间：2020-07-16 15:19:34
重要提示：本网站上提供的MailStore Server Administration API的Python API包装程序代表了API客户端的示例实现。此包装程序应帮助系统管理员和开发人员快速了解MailStore Server的管理API的工作方式以及如何在自己的脚本中使用它。请理解，除了本文档之外，没有提供对Python API包装程序的进一步支持。除非另有说明，否则Pythin API包装器以及所有相关示例脚本均按照MIT许可的条款发布。
本文档介绍了MailStore Server管理API的Python API包装程序的安装和用法。为了防止数据丢失，服务中断或其他问题，强烈建议对本教程以及通常的脚本开发使用非生产性测试环境。
安装
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())"
在Windows中，可以通过打开cmd，在Python3安装目录中导航并执行以下命令来找到site-packages目录的位置：
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
实例化API客户端
在使用API包装器库之前，必须先通过以下方式导入它：
import mailstore
现在可以如下所示实例化mailstore.mgmt.ServerClient类：
serverClient = mailstore.mgmt.ServerClient(username="admin", password="admin", host="127.0.0.1", port=8463)
默认值可以省略。仅当从MailStore Server计算机本身连接到localhost时，才可以使用默认的管理员凭据（用户名和密码设置为admin）。在下表中找到所有默认值的列表：
| 参数 | 默认值 | 描述 |
|---|---|---|
| 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，则需要按照“自动令牌处理”部分中的说明进行手动令牌处理。
对于任何其他的StatusCode值比成功和运行中的错误的发生，必须假定，在该进一步的信息，如错误消息和错误细节是在词典中可用的误差如下所示：
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）的执行可能需要几分钟甚至几小时才能完成。有多种选项可用于处理这些长期运行的任务：
- 自动令牌处理
- 具有回调功能的自动令牌处理
- 手动令牌处理
通常，建议每个方法调用都可以成为长期运行的任务，因为这取决于waitTime值，被调用的方法以及服务器的整体负载。因此，建议在实例化API客户端时全局关闭自动令牌处理。
如果需要，可以通过将autoHandleToken = True / False添加到方法的参数列表来为每个调用的方法启用或禁用自动令牌处理。
使用手动令牌处理或回调函数调用方法后，可以使用CancelAsync方法取消该方法.
自动令牌处理
当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
访问内置文档，其中还包括所有方法及其参数的概述。