Quelltext der Seite PowerShell API-Wrapper Tutorial

__NOTOC__
++ Under construction ++

Dieses Tutorial erläutert anhand einfacher Beispiele den Umgang mit der [[MailStore Server Administration API]] mittels Windows PowerShell Skripten. Grundlegende MailStore Server, Windows und PowerShell Kenntnisse werden dabei vorausgesetzt.

Der im Tutorial verwendete API Wrapper stellt eine Beispielimplementierung eines MailStore Server Administration API Clients dar. Da die Kommunikation mit der Administration API in Form von Web Requests mittels HTTPS erfolgt, können selbstverständlich auch eigene Implementierungen verwendet werden, welche mit entsprechenden PowerShell Cmdlets arbeiten. Diese Möglichkeit wird hier allerdings nicht weiter betrachtet.

<p class=msnote>'''Hinweis:''' Es wird empfohlen, für dieses Tutorial und grundsätzlich für die Skriptentwicklung eine eigene, nicht produktive Installation von MailStore Server in einer Testumgebung zu verwenden, um Probleme und Datenverluste in der Produktivumgebung zu vermeiden. Hierfür eignet sich z.B. die voll funktionsfähige, 30-Tage-Testversion von MailStore Server.</p>

= Installation der benötigten Komponenten =

Die gezeigten Beispiele nutzen den MailStore PowerShell API Wrapper und sind wie dieser auf Windows PowerShell ab Version 3.0 lauffähig. Abhängig von der verwendeten Windows Version muss eine kompatible PowerShell Version zunächst heruntergeladen und installiert werden. Die für das Tutorial benötigten Komponenten finden Sie hier:

* [ftp://ftp.mailstore.com/pub/Scripts/PowerShell/MSS.PS.Lib.zip MailStore PowerShell API Wrapper]
* [[Media:MailStorePSTutorialScripts.zip?|MailStore PowerShell Tutorial Beispielskripte]]
* [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (enthält die PowerShell 3.0)
* [http://www.microsoft.com/de-de/download/details.aspx?id=40855 Windows Management Framework 4.0] (alternativ, enthält die PowerShell 4.0)

Bitte beachten Sie auch die Systemvoraussetzungen und Hinweise zur jeweiligen Version des Windows Management Frameworks.

<p class=msnote><span class=mswarning>'''Wichtiger Hinweis:''' Die Installation eines Windows Management Frameworks wird auf Systemen, welche eine bestimmte PowerShell Version voraussetzen und erweitern, wie beispielsweise Microsoft Exchange Server, nicht unterstützt und kann die Funktion dieser Systeme massiv beeinträchtigen oder zum Erliegen bringen.</span></p>

Nach dem Herunterladen und ggf. der Installation der PowerShell entpacken Sie bitte den MailStore PowerShell API Wrapper und die Beispielskripte (standardmäßig nach ''C:\MailStore Scripting Tutorial\PowerShell\'').

Der MailStore PowerShell API Wrapper und die Beispielskripte sind nicht digital signiert. Daher muss zunächst die Ausführung solcher Skripte in einer administrativen PowerShell Session mittels

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Set-ExecutionPolicy -ExecutionPolicy Unrestricted
</source>

zugelassen werden.

= Einbinden des MailStore PowerShell API Wrappers =

Der MailStore PowerShell API Wrapper ist als PowerShell Script Module (''MSS.PS.Lib.psm1'') implementiert und wird daher über sein Manifest (''MSS.PS.Lib.psd1'') per ''Import-Module'' in eine PowerShell Session eingebunden.

Öffnen Sie eine PowerShell Session und binden Sie das API Wrapper Modul mit folgenden Befehl ein:

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Import-Module "C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1"
</source>

== Informationen zum MailStore PowerShell API Wrapper abrufen ==

Der MailStore PowerShell API Wrapper stellt einige Funktionen und Variablen zur Verfügung, um gemäß PowerShell Konventionen auf die MailStore Server Administration API zugreifen zu können. Geben Sie folgenden Befehl ein, um Informationen hierüber abzurufen:

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Get-Module MSS.PS.Lib | fl
</source>

Mittels der Eigenschaften des Moduls kann man noch detailliertere Informationen abrufen. Beispielsweise gibt

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  (Get-Module MSS.PS.Lib).ExportedVariables
</source>

die zur Verfügung gestellten Variablen des Moduls zurück.<br/>
Mittels 

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Get-Help *MSS*
</source>

stellt der MailStore PowerShell API Wrapper für seine Funktionen Inline-Hilfen (nur auf Englisch verfügbar) bereit.

= Verwendung der API Wrapper Funktionen =

Anhand des folgenden Beispielskripts soll die grundlegende Verwendung der MailStore PowerShell API Wrapper Funktionen veranschaulicht werden. Dieses Skript finden Sie im Beispielskriptpaket als ''Example1.ps1''.

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Import-Module 'C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1'
  $mssapiclient = New-MSSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -Code JSON -IgnoreInvalidSSLCerts
  $return = Invoke-MSSApiCall $mssapiclient "GetServerInfo"
  $return | fl
</source>

Die Funktion ''New-MSSApiClient'' erstellt ein neues API-Client-Objekt, welches dann für API Calls mittels ''Invoke-MSSApiCall'' verwendet werden. Die im Skript angegebenen Werte für die Parameter ''-Username, -Password, -MailStoreServer, -Port'' und ''-Code'' sind die Standardwerte der Funktion, nur der Schalter ''-IgnoreInvalidSSLCerts'' muss bei Verwendung von nicht-vertrauten Zertifikaten explizit angegeben werden, ansonsten kommt es zu einer Fehlermeldung.

''Invoke-MSSApiCall'' benötigt neben dem API-Client-Objekt einen [[MailStore_Server_Administration_API_Commands|API Befehl]] und ggf. dessen Parameter. Der Befehl ''[[MailStore_Server_Administration_API_Commands#GetServerInfo|GetServerInfo]]'' im Skript benötigt keine weiteren Parameter und liefert ein Objekt in folgender Form zurück:

  Type  : JSON
  Token : 
  Data  : @{version=8.1.2.9268; machineName=DEMO}

Die ''Type'' Eigenschaft des Objekts entspricht dabei entweder dem ''-Code'' Parameter des API-Client-Objekt ("JSON" oder "XML"), oder enthält für asynchron ausgeführte API-Befehle den Wert "JOB" (s.u.) und charakterisiert den Typ des in der ''Data'' Eigenschaft enthaltenen Objekts. Die ''Token'' Eigenschaft ist ebenfalls nur für asynchron ausgeführte API-Befehle relevant.

In der ''Data'' Eigenschaft befindet sich das vom MailStore Server zurückgelieferte Ergebnis, hier als JSON Objekt:

  PS C:\MailStore Scripting Tutorial\PowerShell\Scripts>$return.Data|fl
  version     : 8.1.2.9268
  machineName : DEMO

== API Wrapper Funktionen mit Parametern aufrufen ==

Viele MailStore Server Administration API Befehle erfordern die Angabe von Parametern. Selbstverständlich ist der MailStore PowerShell API Wrapper in der Lage, diese mittels ''Invoke-MSSApiCall'' zu übermitteln. Zur Erläuterung soll das folgende Skript dienen, das im Beispielskriptpaket als ''Example2.ps1'' enthalten ist.

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Import-Module 'C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1'
  $mssapiclient = New-MSSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -Code JSON -IgnoreInvalidSSLCerts
  $users = (Invoke-MSSApiCall $mssapiclient "GetUserList").Data
  foreach ($user in $users) {(Invoke-MSSApiCall $mssapiclient "GetUserInfo" @{userName = $user.userName}).Data | fl}
</source>

Das Skript liefert Details über die in MailStore Server angelegten Benutzer zurück und gibt sie als Liste aus. Es macht sich dabei zunutze, dass der MailStore PowerShell API Wrapper die Antworten der MailStore Server Management API direkt in Objekte konvertiert, deren Eigenschaften dann direkt weiterverwendet werden können.

Der im Skript aufgerufene API Befehl ''[[MailStore_Server_Administration_API_Commands#GetUserInfo|GetUserInfo]]'' erfordert einen Parameter ''userName''. Die Funktion ''Invoke-MSSApiCall'' erwartet Parameter als Hashtable, also z.B. in der Form ''@{Parametername1 = Wert1; Parametername2 = Wert2;...}''. Die Parameternamen sind dabei case sensitive.

Zunächst wird die Liste der MailStore Server Benutzer mittels des API Befehls ''[[MailStore_Server_Administration_API_Commands#GetUserList|GetUserList]]'' abgerufen. Dieser liefert ein Array mit Einträgen folgenden Aufbaus zurück:
  
  userName          : abby.hernandez
  fullName          : Abby Hernandez
  distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com

Über diese Einträge wird nun iteriert und dabei die ''userName'' Eigenschaft jedes Eintrags als Parameter des API Befehls ''[[MailStore_Server_Administration_API_Commands#GetUserInfo|GetUserInfo]]'' verwendet. Das Ergebnis für den o.g. Eintrag sieht wie folgt aus:

  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[]}}

An der ''privilegesOnFolders'' Eigenschaft ist gut erkennbar, dass die zurückgegebenen Objekte durchaus tiefer verschachtelt sein und ihrerseits weitere Objekte enthalten können.

= API Wrapper Funktionen für asynchron ausgeführte API Befehle aufrufen =

MailStore Server Administration API-Befehle, deren Ausführung typischerweise länger dauert, werden vom Server asynchron ausgeführt. Der MailStore PowerShell API Wrapper erkennt den Aufruf dieser [[MailStore_Server_Administration_API#Asynchron_ausgef.C3.BChrte_Befehle|asynchron ausgeführten API Befehle]] und führt diese als [http://technet.microsoft.com/en-us/library/hh847783%28v=wps.620%29.aspx PowerShell Job] im Hintergrund aus.

== API Wrapper PowerShell Jobs synchron verarbeiten ==

Die weitere Skriptausführung kann unterbrochen werden, bis ein vom API Wrapper erzeugter PowerShell Job abgeschlossen wurde. Das Skript ''Example3.ps1'' aus dem Beispielskriptpaket verdeutlicht diese Funktionalität:

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Import-Module 'C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1'
  $mssapiclient = New-MSSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -Code JSON -IgnoreInvalidSSLCerts
  $return = invoke-MSSApiCall $mssapiclient "VerifyStore" @{id = "1"}
  if ($return.Type -eq "JOB") {
      Wait-Job $return.Data
      Receive-Job $return.Data
  } else {
      $return.Data
  }
</source>

Der im Skript aufgerufene API Befehl ''[[MailStore_Server_Administration_API_Commands#VerifyStore|VerifyStore]]'' liefert ein Objekt mit der ''Type'' Eigenschaft "JOB" zurück.

  Type  : JOB
  Token : sa9e8d780329f1e0c59503a2e041f7c72b
  Data  : System.Management.Automation.PSRemotingJob

Im Unterschied zu den Rückgabeobjekten bei synchron ausgeführten API Befehlen ist hier die ''Token'' Eigenschaft gesetzt, sie enthält eine vom Server zurückgegebene, eindeutige ID des Serverprozesses und ist für die Ereignisbehandlung von Bedeutung (siehe unten). Die ''Data'' Eigenschaft enthält den PowerShell Job, der im Hintergrund die vom Server zurückgelieferten Statusobjekte verarbeitet.

Dieser PowerShell Job fragt den Status des zugehörigen Serverprozesses in regelmäßigen Intervallen ab (standardmäßig alle 500 ms) und wird beendet, wenn dieser abgeschlossen ist. Mittels des PowerShell cmdlets [http://technet.microsoft.com/en-us/library/hh849735.aspx Wait-Job] wartet das Skript auf die Fertigstellung des Jobs, anschließend wird das Ergebnis des Jobs mittels [http://technet.microsoft.com/en-us/library/hh849718.aspx Receive-Job] abgerufen:

  Type       : JSON
  Token      : 
  Data       : @{status=succeeded; progressPercentage=100; messages=System.Collections.ArrayList}
  RunspaceId : 2eca1237-4504-4b63-a153-d326adf8c744

<p class=msnote>'''Hinweis:''' Die ''RunspaceId'' wird von der PowerShell automatisch erzeugt und kann hier ignoriert werden.</p>

== API Wrapper PowerShell Jobs asynchron verarbeiten ==

Anstatt die Ausführung eines Skripts zu unterbrechen, kann auch auf die vom API Wrapper erzeugten PowerShell Jobs reagiert werden, während diese im Hintergrund ausgeführt werden. Diese Jobs triggern mit jedem abgefragten Status ein PowerShell EngineEvent, welches vom Skript abonniert werden kann, um bei dessen Eintritt weiteren Code auszuführen. Hierzu muss das vorherige Skript geringfügig angepasst werden (''Example4.ps1'' aus dem Beispielskriptpaket):

<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">
  Import-Module 'C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1'
  
  $mssapiclient = New-MSSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -Code JSON -IgnoreInvalidSSLCerts
  $return = invoke-MSSApiCall $mssapiclient "VerifyStore" @{id = "1"}
  $return|fl
  if ($return.Type -eq "JOB") {
      $mssevent = Register-EngineEvent -SourceIdentifier $return.Token -Action {write-host $event.MessageData.Data}
  } else {
      $return.Data
  }
</source>

Im Gegensatz zum dritten Beispielskript wird hier mittels [http://technet.microsoft.com/en-us/library/hh849967.aspx Register-EngineEvent] das vom Hintergrundjob getriggerte Event abonniert. Dieses verwendet als ''SourceIdentifier'' die in der ''Token'' Eigenschaft des Rückgabeobjekts enthaltene ID und ist darüber dem auslösenden PowerShell Job 
und somit dem Serverprozess eindeutig zuzuordnen. Der ''Action'' Skriptblock wird selbst wiederum als Job angelegt und bei jeder Auslösung des Events ausgeführt. Über die ''MessageData'' Eigenschaft der  [http://technet.microsoft.com/en-us/library/hh847768.aspx automatischen Variable] ''$event'' greift er hier auf das vom Hintergrundjob dort hinterlegte Rückgabeobjekt zu. Dessen ''Data'' Eigenschaft enthält das Statusobjekt des Serverprozesses:

  @{status=running; progressPercentage=0; messages=System.Collections.ArrayList}

Durch diese Mechanismen kann das Skript im Vordergrund weitere Aufgaben ausführen, während im Hintergrund der Serverprozess überwacht wird. Auch die Ausführung und Behandlung mehrerer asynchroner API Befehle ist so möglich.