管理和使用API
作者：mailstore，更新时间：2020-07-16 15:16:18
在本章中，您可以找到MailStore服务器管理API的描述。使用Administration API，可以从中央位置远程控制管理任务，例如管理用户或存储位置。通过HTTPS使用Web请求完成与Administration API的通信。
出于安全原因，默认情况下已禁用MailStore服务器管理API，必须使用MailStore服务器服务配置来激活它。当您连接到API并使用除localhost或127.0.0.1之外的其他主机名时，必须先更改管理员用户的密码
。
执行常规API函数
要执行常规的Management API函数，请将HTTP POST请求发送到以下URL：
https://<邮件存储服务器>:8463/api/invoke/<function>
对于对API的每个请求，必须遵循RFC 2617中描述的HTTP基本身份验证规范，提交MailStore管理员的用户名和密码。当功能需要其他数据时，必须使用urlencode发送该数据。应该设置HTTP标头Content-Type：application/x-www-form-urlencoded。
例
HTTP请求
POST /api/invoke/GetServerInfo HTTP/1.1 Authorization: Basic YWRtaW46UGFzc3cwcmQ= User-Agent: curl/7.35.0 Host: mailstore.example.com:8463 Accept: */* Content-Length: 0
HTTP响应
HTTP/1.1 200 OK Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0 Pragma: no-cache Content-Length: 251 Content-Type: application/json Expires: Wed, 25 Jun 2014 14:13:43 GMT Server: Microsoft-HTTPAPI/2.0 Date: Thu, 26 Jun 2014 14:13:43 GMT { "error": null, "token": null, "statusVersion": 2, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": { "version": "9.0.0.9702", "machineName": "MAILSTORE" }, "logOutput": null }
要获取所有可用功能的列表，请将POST请求发送到https：// <mailstore-server>：8463 / api / get-metadata。
长时间运行的流程
一些API函数会启动一个长期运行的过程，可能需要几分钟甚至几小时才能完成。为了跟踪进度，在初始请求时会返回一个唯一的令牌，该令牌可用于定期轮询状态更新。
整个过程如下：
- 将HTTP POST发送到https://<mailstore-server>:8463/api/invoke/VerifyStore，以执行该功能。
- 检查服务器的响应以获取密钥令牌，statusCode和statusVersion。
- 要检索状态更新，请使用以下参数定期向https://<mailstore-server>:8463/api/ get-status发送请求：
| 名称 | 描述 |
|---|---|
| token | 接收到的唯一令牌的过程。 |
| lastKnownStatusVersion | 来自上次响应的statusVersion的值。 |
| 毫秒超时 | 直到服务器停止等待新状态更新发送之前的时间（以毫秒为单位）。如果有新的状态更新可用，它将立即发送到客户端，否则将重复上一个状态。 |
- 4.当statusCode未运行时，该过程完成。
例
初始HTTP请求
POST /api/invoke/VerifyStore HTTP/1.1 Authorization: Basic YWRtaW46UGFzc3cwcmQ= User-Agent: curl/7.35.0 Host: mailstore.example.com:8463 Accept: */* Content-Length: 5 Content-Type: application/x-www-form-urlencoded id=11
初始HTTP响应
HTTP/1.1 200 OK Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0 Pragma: no-cache Content-Length: 290 Content-Type: application/json Expires: Wed, 25 Jun 2014 14:15:41 GMT Server: Microsoft-HTTPAPI/2.0 Date: Thu, 26 Jun 2014 14:15:41 GMT { "error": null, "token": "b3af0ebae4dd755d1a54b9756817baee", "statusVersion": 3, "statusCode": "running", "percentProgress": 0, "statusText": null, "result": null, "logOutput": "Verifying file group #11...\r\nCreating a list of messages to be verified...\r\n" }
定期HTTP进度请求
POST /api/get-status HTTP/1.1 Authorization: Basic YWRtaW46UGFzc3cwcmQ= User-Agent: curl/7.35.0 Host: spe.example.com:8474 Accept: */* Content-Length: 90 Content-Type: application/x-www-form-urlencoded token=b3af0ebae4dd755d1a54b9756817baee&lastKnownStatusVersion=3&millisecondsTimeout=5000
HTTP对定期进度请求的响应
HTTP/1.1 200 OK Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0 Pragma: no-cache Content-Length: 242 Content-Type: application/json Expires: Wed, 25 Jun 2014 14:08:15 GMT Server: Microsoft-HTTPAPI/2.0 Date: Thu, 26 Jun 2014 14:08:15 GMT { "error": null, "token": "b3af0ebae4dd755d1a54b9756817baee", "statusVersion": 9, "statusCode": "running", "percentProgress": 0, "statusText": null, "result": null, "logOutput": " 400 messages verified...\r\n" }
最终HTTP响应
HTTP/1.1 200 OK Cache-Control: no-cache,private,no-store,must-revalidate,max-stale=0,post-check=0,pre-check=0 Pragma: no-cache Content-Length: 242 Content-Type: application/json Expires: Wed, 25 Jun 2014 15:08:15 GMT Server: Microsoft-HTTPAPI/2.0 Date: Thu, 26 Jun 2014 15:08:15 GMT { "error": null, "token": null, "statusVersion": 269, "statusCode": "succeeded", "percentProgress": null, "statusText": null, "result": null, "logOutput": null }
错误处理
除了处理协议特定的问题（例如HTTP或TCP错误）之外，如果请求未成功，开发人员还会从API本身接收详细信息。
如果成功处理了请求，则响应将包含：
"error": null
否则，如果发生故障，错误密钥将具有以下结构
"error": { "message": string, "details": string }
允许开发人员显示有意义的错误消息和更多技术细节。