PowerShell API包装程序教程

作者:mailstore,发布时间:2020-05-14 16:28:09

重要提示:本网站上提供的MailStore Server Administration API的PowerShell API包装程序应视为API客户端的示例实现。此包装程序应帮助系统管理员和开发人员快速了解MailStore Server管理API调用的工作方式以及如何在自己的脚本中使用它们。
请理解,除了本文档之外,没有提供对Powershell API包装程序的进一步支持。除非另有说明,否则,PowerShell API包装程序以及所有相关示例脚本均根据MIT许可证的条款和条件发布。

 

本教程旨在通过简单的Windows PowerShell示例脚本来说明管理API的用法。必须具备MailStore Server,Windows和PowerShell的基础知识。为了防止数据丢失,服务中断或其他问题,强烈建议对本教程以及通常的脚本开发使用非生产性测试环境。

 

安装必要的组件

此处演示的示例使用MailStore PowerShell API包装程序,并且与Windows PowerShell 3.0及更高版本兼容。根据您的Windows版本,可能需要先下载并安装兼容版本的PowerShell。您可以在这里找到本教程所需的组件:

请注意系统要求以及有关Windows Management Framework各个版本的进一步通知。

重要声明:不支持在需要特定版本的Windows PowerShell的系统(例如Microsoft Exchange Server)上安装Windows Management Framework,这可能会导致大量系统故障和数据丢失。

下载并安装Windows PowerShell后(如有必要),请解压缩MailStore PowerShell API包装程序和示例脚本(默认情况下解压缩到C:\MailStore Server Scripting Tutorial\PowerShell\)。

MailStore PowerShell API包装程序和示例脚本均未进行数字签名,因此必须在管理PowerShell会话中使用以下命令启用此类脚本的执行:

  Set-ExecutionPolicy -ExecutionPolicy Unrestricted

导入MailStore PowerShell API包装程序

MailStore PowerShell API包装程序实现为PowerShell脚本模块(MS.PS.Lib.psm1),因此可以使用Import-Module通过其清单(MS.PS.Lib.psd1)导入 PowerShell会话中。

请打开PowerShell会话并使用以下命令导入API包装程序模块:

  Import-Module "C:\MailStore Server Scripting Tutorial\PowerShell\API-Wrapper\MS.PS.Lib.psd1"

获取有关MailStore PowerShell API包装程序的信息

MailStore PowerShell API包装程序提供了一些功能和变量,以遵循PowerShell约定来访问MailStore Server管理API。输入以下命令以获取有关这些功能的信息:

  Get-Module MS.PS.Lib | fl

可通过模块的属性获得更多详细信息。例如,

  (Get-Module MS.PS.Lib).ExportedFunctions

返回模块提供的功能。通过

  Get-Help *MSApi*

MailStore PowerShell API包装程序将为其所有功能返回内联帮助。

调用API包装程序函数

以下示例脚本(教程包中的Example1.ps1)说明了MailStore PowerShell API包装程序函数的基本用法。

 Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'
  $msapiclient = New-MSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -IgnoreInvalidSSLCerts
  $return = Invoke-MSApiCall $msapiclient "GetServerInfo"
  $return | fl

函数New-MSApiClient创建一个新的API客户端对象,Invoke-MSApiCall函数将其用于API调用。为值-Username,-Password,-MailStoreServer和-Port在脚本使用的是该函数的默认值,仅开关-IgnoreInvalidSSLCerts具有如果使用不受信任的证书将被设置; 否则会发生错误。

除API客户端对象外,Invoke-MSApiCall还需要API命令及其参数(如果适用)。脚本中的命令GetServerInfo没有任何参数,并返回JSON对象,如下所示:

 PS C:\MailStore Server Scripting Tutorial\PowerShell\Scripts>$return | fl
 error : 
 token : 
 statusVersion : 2
 statusCode : succeeded
 percentProgress : 
 statusText : 
 result : @{version=9.1.0.10258; machineName=PC001}
 logOutput : 

如果调用成功,则状态对象的result属性包含另一个JSON对象,该对象具有该函数返回的数据:

 PS C:\MailStore Server Scripting Tutorial\PowerShell\Scripts>$return.result | fl
 version : 9.1.0.10258
 machineName : PC001

提供参数

对于大多数MailStore Server管理API命令,您需要提供参数。当然,如以下脚本所示(教程包中的Example2.ps1),MailStore PowerShell API包装程序的Invoke-MSApiCall函数可以提交这些参数:

  Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'
  $msapiclient = New-MSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -IgnoreInvalidSSLCerts
  $users = (Invoke-MSApiCall $msapiclient "GetUsers").result
  foreach ($user in $users) {(Invoke-MSApiCall $msapiclient "GetUserInfo" @{userName = $user.userName}).result | fl}
脚本列出了有关在MailStore Server中创建的用户的详细信息。由于MailStore PowerShell API包装程序将MailStore Server Management API响应转换为对象,因此可以直接在脚本的工作流中使用其属性。

脚本中使用的API命令 GetUserInfo需要一个参数userName。Invoke-MSApiCall函数期望参数作为哈希表,例如@ {parametername1 = value1; parametername2 = value2; …}。参数名称区分大小写。

首先,使用API​​命令GetUsers请求MailStore Server的用户列表,该命令 返回用户条目的数组,如下所示:

 userName : abby.hernandez
 fullName : Abby Hernandez
 distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com

现在,脚本使用每个条目的userName属性作为API命令GetUserInfo的参数 在此数组上进行迭代。对于上面列出的条目,结果可能如下:

 userName : abby.hernandez
 fullName : Abby Hernandez
 distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com
 authentication : directoryServices
 emailAddresses : {abby.hernandez@example.com}
 pop3UserNames : {}
 privileges : {login}
 privilegesOnFolders : {@{folder=abby.hernandez; privileges=System.Object[]}}
如在privilegesOnFolders属性中可以看到的,返回的对象可能是嵌套的,并且可能还包含其他对象。

处理异步API调用

如果管理API命令的执行花费更多时间,则服务器可能决定异步执行这些命令。MailStore PowerShell API包装程序可以等待此类异步执行的API命令完成,也可以在后台将其作为PowerShell作业运行。

待异步API调用完成

可以中断脚本的执行,直到由API包装程序创建的PowerShell作业终止为止,如以下脚本所示(本教程包中的Example3.ps1):

  Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'
  $msapiclient = New-MSApiClient -Username "admin" -Password "admin" -Server "localhost" -Port 8463 -IgnoreInvalidSSLCerts
  $return = Invoke-MSApiCall $msapiclient "VerifyStore" @{id = "1"}
  $return | fl

通过使用Invoke-MSApiCall,API包装程序将等待MailStore Server异步执行的API命令完成,并仅返回其最终结果。

 

订阅由异步API调用触发的事件

由API包装程序创建的PowerShell作业可以在后台运行时对其做出反应,而不必中断脚本的执行。这些作业会通过脚本可以订阅的每个状态请求来触发PowerShell EngineEvent,以便在每次出现时执行更多代码。为了证明这一点,只需对以前的脚本进行一些改动(本教程包中的Example4.ps1):

  Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'
  $msapiclient = New-MSApiClient -Username "admin" -Password "admin" -Server "localhost" -Port 8463 -IgnoreInvalidSSLCerts
  $return = Start-MSApiCall $msapiclient "VerifyStore" @{id = "1"}
  if ($return.statusCode -eq "running") {
      $mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData}
  } else {
      $return | fl
  }

通过使用Start-MSApiCall,API包装程序将运行由MailStore Server在后台异步执行的API命令,并返回其第一个结果。该脚本使用返回对象的Token属性作为SourceIdentifier来订阅由后台作业通过Register-EngineEvent触发的事件。通过该属性,事件与触发PowerShell作业相关,因此与服务器进程相关。该动作脚本块本身作为与该事件的每个触发执行的PowerShell的工作创造。通过$ event 自动变量的MessageData属性 脚本块可以访问后台作业提供的返回对象。该对象包含服务器进程的状态:

 @{error=; token=e2b7c58ff37df64e2b62bb02bde9bbfd; statusVersion=77; statusCode=running; percentProgress=95; statusText=; result=; logOutput= 1400 messages verified...}

通过这些机制,脚本可以在后台监视服务器进程的同时执行其他任务。也可以通过这种方式执行和处理多个异步API命令。

取消异步API调用

要取消执行异步API命令,请将Stop-MSApiCall与令牌或返回对象一起使用。对于上面的示例,调用将是:

  Stop-MSApiCall $MSApiclient -AsyncReturnObject $return

固定TLS版本

API包装程序支持TLS1.2,TLS1.1和TLS1.0连接,并使用可用的最高版本。如果仅应使用特定的TLS版本,则可以使用SecurityProtocol参数。支持的值为Tls12,Tls11和Tls。

  Import-Module '..\API-Wrapper\MS.PS.Lib.psd1'
  $msapiclient = New-MSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -IgnoreInvalidSSLCerts -SecurityProtocol Tls12