|
|
| Zeile 1: |
Zeile 1: |
| − | ++ 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.
| |
| − |
| |
| − | <p class=msnote>'''Hinweis:''' Es wird empfohlen, für dieses Tutorial und grundsätzlich für die Skriptentwicklung eine eigene, nicht produktive Instanz 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:
| |
| − |
| |
| − | [[Media:MailStorePSAPIWrapper.zip?|MailStore PowerShell API Wrapper]]<br/>
| |
| − | [[Media:MailStorePSTutorialScripts.zip?|MailStore PowerShell Tutorial Beispielskripte]]<br/>
| |
| − | [https://my.mailstore.com/TrialLicense/RequestForm?lang=de 30-Tage-Testversion von MailStore Server]<br/>
| |
| − | [http://www.microsoft.com/en-us/download/details.aspx?id=34595 Windows Management Framework 3.0] (enthält die PowerShell 3.0)<br/>
| |
| − | [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 style="color:red">'''Wichtiger Hinweis:'''</span> 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.</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\'').
| |
| − |
| |
| − | = 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:
| |
| − | <pre>Import-Module "C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1"</pre>
| |
| − |
| |
| − | <div style="border:1px solid gray; padding:6px 10px 6px 10px; margin:0px 0px 12px 0px">'''Hinweis:''' 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
| |
| − | <pre>Set-ExecutionPolicy -ExecutionPolicy Unrestricted</pre>
| |
| − | zugelassen werden.</div>
| |
| − |
| |
| − | == 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:
| |
| − | <pre>Get-Module MSS.PS.Lib|fl</pre>
| |
| − | Mittels der Eigenschaften des Moduls kann man noch detailliertere Informationen abrufen. Beispielsweise gibt
| |
| − | <pre>(Get-Module MSS.PS.Lib).ExportedVariables</pre>
| |
| − | die zur Verfügung gestellten Variablen des Moduls zurück.<br/>
| |
| − | Mittels
| |
| − | <pre>Get-Help</pre>
| |
| − | 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''.
| |
| − | <pre>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</pre>
| |
| − | 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.<br/>
| |
| − | ''Invoke-MSSApiCall'' benötigt neben dem API-Client-Objekt einen [[MailStore_Server_Administration_API_Commands|API Befehl]] und ggf. dessen Parameter. Der Befehl ''GetServerInfo'' im Skript benötigt keine weiteren Parameter und liefert ein Objekt in folgender Form zurück:
| |
| − |
| |
| − | <pre>Type : JSON
| |
| − | Token :
| |
| − | Data : @{version=8.1.2.9268; machineName=DEMO}</pre>
| |
| − |
| |
| − | 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.<br/>
| |
| − | In der ''Data'' Eigenschaft befindet sich das vom MailStore Server zurückgelieferte Ergebnis, hier als JSON Objekt:
| |
| − |
| |
| − | <pre>PS C:\MailStore Scripting Tutorial\PowerShell\Scripts>$return.Data|fl
| |
| − | version : 8.1.2.9268
| |
| − | machineName : DEMO</pre>
| |
| − |
| |
| | == API Wrapper Funktionen mit Parametern aufrufen == | | == API Wrapper Funktionen mit Parametern aufrufen == |
| | | | |
| Zeile 69: |
Zeile 4: |
| | <pre>Import-Module 'C:\MailStore Scripting Tutorial\PowerShell\API-Wrapper\MSS.PS.Lib.psd1' | | <pre>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 | | $mssapiclient = New-MSSApiClient -Username admin -Password admin -MailStoreServer localhost -Port 8463 -Code JSON -IgnoreInvalidSSLCerts |
| − | $users = Invoke-MSSApiCall $mssapiclient "GetUserList" | + | $users = (Invoke-MSSApiCall $mssapiclient "GetUserList").Data |
| − | foreach ($user in $users.Data) {(Invoke-MSSApiCall $mssapiclient "GetUserInfo" @{userName = $user.userName}).Data|fl}</pre> | + | foreach ($user in $users) {(Invoke-MSSApiCall $mssapiclient "GetUserInfo" @{userName = $user.userName}).Data|fl}</pre> |
| | + | 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: |
| | + | <pre>userName : abby.hernandez |
| | + | fullName : Abby Hernandez |
| | + | distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com</pre> |
| | + | Ü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 könnte wie folgt aussehen: |
| | + | <pre>userName : abby.hernandez |
| | + | fullName : Abby Hernandez |
| | + | distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com |
| | + | authentication : directoryServices |
| | + | |
| | + | pop3UserNames : {} |
| | + | privileges : {login} |
| | + | privilegesOnFolders : {@{folder=abby.hernandez; privileges=System.Object[]}}</pre> |
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 Beispielskript dienen, das im Beispielskriptpaket als Example2.ps1 enthalten ist.
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}
Zunächst wird die Liste der MailStore Server Benutzer mittels des API Befehls 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 GetUserInfo verwendet. Das Ergebnis für den o.g. Eintrag könnte wie folgt aussehen:
userName : abby.hernandez
fullName : Abby Hernandez
distinguishedName : CN=Abby Hernandez,OU=tutorial,DC=example,DC=com
authentication : directoryServices
emailAddresses : {[email protected]}
pop3UserNames : {}
privileges : {login}
privilegesOnFolders : {@{folder=abby.hernandez; privileges=System.Object[]}}
