管理和使用API

更新时间：2020-05-14 14:53:25

在本章中，您可以找到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
 }

允许开发人员显示有意义的错误消息和更多技术细节。