PowerShell API包装程序教程

重要提示：本网站上提供的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。您可以在这里找到本教程所需的组件：

MailStore PowerShell API包装程序和教程示例脚本
适用于您的操作系统的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

分享到：微信 QQ空间 QQ好友新浪微博百度贴吧