From 5e2e4a0c1b16b54a6aa3809de9a16a185062b26c Mon Sep 17 00:00:00 2001 From: Wes Carroll Date: Fri, 22 Feb 2019 22:17:47 -0500 Subject: [PATCH] Start commenting code and help messages --- .../Private/Get-ZertoApiFilter.ps1 | 10 ++- .../Private/Invoke-ZertoRestRequest.ps1 | 10 +++ .../Public/Connect-ZertoServer.ps1 | 49 ++++++++---- .../Public/Disconnect-ZertoServer.ps1 | 4 + ZertoApiWrapper/Public/Get-ZertoAlert.ps1 | 76 +++++++++++++++---- ZertoApiWrapper/Public/Get-ZertoDatastore.ps1 | 7 +- 6 files changed, 124 insertions(+), 32 deletions(-) diff --git a/ZertoApiWrapper/Private/Get-ZertoApiFilter.ps1 b/ZertoApiWrapper/Private/Get-ZertoApiFilter.ps1 index 9af34e8..a6400ca 100644 --- a/ZertoApiWrapper/Private/Get-ZertoApiFilter.ps1 +++ b/ZertoApiWrapper/Private/Get-ZertoApiFilter.ps1 @@ -1,18 +1,24 @@ function Get-ZertoApiFilter { [cmdletbinding()] param( - [Parameter( Mandatory = $true )] + [Parameter( Mandatory = $true, + HelpMessage = "Hashtable that contains filter keys and values" + )] [hashtable]$filterTable ) + # Define the start of the return string [string]$returnString = "?" + #Foreach item in the table, process each item foreach ( $key in $filterTable.Keys ) { + #If this is not the first item added to the string, add the ampersand and filter if ($returnString.Length -gt 1) { $returnString = "{0}&{1}={2}" -f $returnString, $key, $filterTable[$key] } else { + #If it is the first item, just add the first item $returnString = "{0}{1}={2}" -f $returnString, $key, $filterTable[$key] } } - + # Return the built query String return $returnString } diff --git a/ZertoApiWrapper/Private/Invoke-ZertoRestRequest.ps1 b/ZertoApiWrapper/Private/Invoke-ZertoRestRequest.ps1 index a59931a..a52f9a8 100644 --- a/ZertoApiWrapper/Private/Invoke-ZertoRestRequest.ps1 +++ b/ZertoApiWrapper/Private/Invoke-ZertoRestRequest.ps1 @@ -11,24 +11,34 @@ function Invoke-ZertoRestRequest { [switch]$returnHeaders ) $callerErrorActionPreference = $ErrorActionPreference + # If the ZVM server and Port not defined, Stop Call if ( -not ((Test-Path variable:script:zvmServer) -and (Test-Path variable:script:zvmPort)) ) { Write-Error -Message "Zerto Connection does not Exist. Please run Connect-ZertoServer first to establish a connection" break } + + # If the Headers exist and the Last action was more than 30 minutes ago, Session is Expired if ( (Test-Path variable:script:zvmHeaders) -and $([datetime]$script:zvmLastAction).addMinutes(30) -lt $(get-date) ) { Write-Error -Message "Authorization Token has Expired. Please re-authorize to the Zerto Virtual Manager" break } else { + + # Build the URI to be submitted $submittedURI = "https://{0}:{1}/{2}/{3}" -f $script:zvmServer, $script:zvmPort, $apiVersion, $uri try { + # Set the zvmLastAction time and try to submit the REST Request $script:zvmLastAction = (get-date).Ticks $apiRequestResults = Invoke-RestMethod -Uri $submittedURI -Headers $script:zvmHeaders -Method $method -Body $body -ContentType $contentType -Credential $credential -SkipCertificateCheck -ResponseHeadersVariable responseHeaders -TimeoutSec 100 } catch { + # If an error is encountered, Catch Write-Error -ErrorRecord $_ -ErrorAction $callerErrorActionPreference } + + # If the calling function does not need the headers (Default Action) return the results of the API Call if (-not $returnHeaders) { return $apiRequestResults } else { + #If Headers are required, build a PS Custom Object with the Results and the Headers $apiRequestAndHeaderResults = New-Object -TypeName psobject $apiRequestAndHeaderResults | Add-Member -MemberType NoteProperty -Name "apiRequestResults" -Value $apiRequestResults $apiRequestAndHeaderResults | Add-Member -MemberType NoteProperty -Name "Headers" -Value $responseHeaders diff --git a/ZertoApiWrapper/Public/Connect-ZertoServer.ps1 b/ZertoApiWrapper/Public/Connect-ZertoServer.ps1 index 375529c..431cddb 100644 --- a/ZertoApiWrapper/Public/Connect-ZertoServer.ps1 +++ b/ZertoApiWrapper/Public/Connect-ZertoServer.ps1 @@ -1,7 +1,5 @@ function Connect-ZertoServer { - [cmdletbinding( - SupportsShouldProcess = $false - )] + [cmdletbinding()] param( [Parameter( Mandatory = $true, @@ -9,7 +7,9 @@ function Connect-ZertoServer { )] [ValidateNotNullOrEmpty()] [string]$zertoServer, - [Parameter( HelpMessage = "Zerto Virtual Manager management port. Default value is 9669." )] + [Parameter( + HelpMessage = "Zerto Virtual Manager management port. Default value is 9669." + )] [string]$zertoPort = "9669", [Parameter( Mandatory = $true, @@ -19,17 +19,34 @@ function Connect-ZertoServer { $credential, [switch]$returnHeaders ) - Set-Variable -Name zvmServer -Scope Script -Value $zertoServer - Set-Variable -Name zvmPort -Scope Script -Value $zertoPort - Set-Variable -Name zvmLastAction -Scope Script -Value $(get-date).Ticks - Set-Variable -Name zvmHeaders -Scope Script -Value $null - $body = '{"AuthenticationMethod": "1"}' - $uri = "session/add" - $results = Invoke-ZertoRestRequest -uri $uri -credential $credential -returnHeaders -body $body -method POST - $zertoAuthorizationHeaders = @{"x-zerto-session" = $results.Headers['x-zerto-session'][0].ToString(); "Accept" = "application/json"} - Set-Variable -Name zvmHeaders -Scope Script -Value $zertoAuthorizationHeaders - Set-Variable -Name zvmLocalInfo -Scope Script -Value (Get-ZertoLocalSite) - if ($returnHeaders) { - return $zertoAuthorizationHeaders + + begin { + $body = '{"AuthenticationMethod": "1"}' + $uri = "session/add" + # Set Script Scope Variables for Use in all functions in the module; Server and Port Information + Set-Variable -Name zvmServer -Scope Script -Value $zertoServer + Set-Variable -Name zvmPort -Scope Script -Value $zertoPort + # Set zvmLastAction Variable to keep track when the API token expires + Set-Variable -Name zvmLastAction -Scope Script -Value $(get-date).Ticks + # Set / Clear the zvmHeaders to clear any existing token + Set-Variable -Name zvmHeaders -Scope Script -Value $null + } + + process { + # Send authorization request to the function and send back the results including headers + $results = Invoke-ZertoRestRequest -uri $uri -credential $credential -returnHeaders -body $body -method POST + } + + end { + # Build Headers Hashtable with Authorization Token + $zertoAuthorizationHeaders = @{"x-zerto-session" = $results.Headers['x-zerto-session'][0].ToString(); "Accept" = "application/json"} + # Set common Script Scope Variables to be used other functions (Headers and Local Site Info) + Set-Variable -Name zvmHeaders -Scope Script -Value $zertoAuthorizationHeaders + Set-Variable -Name zvmLocalInfo -Scope Script -Value (Get-ZertoLocalSite) + + # Have the option to return the headers to a variable + if ($returnHeaders) { + return $zertoAuthorizationHeaders + } } } diff --git a/ZertoApiWrapper/Public/Disconnect-ZertoServer.ps1 b/ZertoApiWrapper/Public/Disconnect-ZertoServer.ps1 index f0d6ee0..9233a37 100644 --- a/ZertoApiWrapper/Public/Disconnect-ZertoServer.ps1 +++ b/ZertoApiWrapper/Public/Disconnect-ZertoServer.ps1 @@ -1,7 +1,11 @@ function Disconnect-ZertoServer { [cmdletbinding()] $uri = "session" + + # Delete API Authorization Invoke-ZertoRestRequest -uri $uri -method DELETE + + # Remove all variables used Remove-Variable -Name zvmServer -Scope Script Remove-Variable -Name zvmPort -Scope Script Remove-Variable -Name zvmLastAction -Scope Script diff --git a/ZertoApiWrapper/Public/Get-ZertoAlert.ps1 b/ZertoApiWrapper/Public/Get-ZertoAlert.ps1 index d51c8f8..0aa448c 100644 --- a/ZertoApiWrapper/Public/Get-ZertoAlert.ps1 +++ b/ZertoApiWrapper/Public/Get-ZertoAlert.ps1 @@ -1,31 +1,76 @@ function Get-ZertoAlert { [cmdletbinding( defaultParameterSetName = "main" )] param( - [Parameter( ParameterSetName = "alertId", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true )] + [Parameter( + ParameterSetName = "alertId", + Mandatory = $true, + ValueFromPipeline = $true, + ValueFromPipelineByPropertyName = $true , + HelpMessage = "AlertId or array of AlertIds to be queried" + )] [string[]]$alertId, - [Parameter( ParameterSetName = "entities", Mandatory = $true )] + [Parameter( + ParameterSetName = "entities", + Mandatory = $true, + HelpMessage = "Switch to return the entities information from the API" + )] [switch]$entities, - [Parameter( ParameterSetName = "helpIdentifiers", Mandatory = $true )] + [Parameter( + ParameterSetName = "helpIdentifiers", + Mandatory = $true, + HelpMessage = "Switch to get the Help Identifiers information from the API" + )] [switch]$helpIdentifiers, - [Parameter( ParameterSetName = "levels", Mandatory = $true )] + [Parameter( + ParameterSetName = "levels", + Mandatory = $true, + HelpMessage = "Switch to return Alert Levels information from the API" + )] [switch]$levels, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns Alerts after the Start Date. Provide the string in the format of 'yyyy-MM-ddTHH:mm:ss.fff'" + )] [string]$startDate, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns Alerts before the End Date. Provide the string in the format of 'yyyy-MM-ddTHH:mm:ss.fff'" + )] [string]$endDate, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage "Returns alerts for the specified vraIdentifier" + )] [string]$vpgIdentifier, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts for the specified siteIdentifier" + )] [string]$siteIdentifier, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts for the specified zorgIdentifier" + )] [string]$zorgIdentifier, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts for the specified level" + )] [string]$level, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts for the specified helpIdentifier" + )] [string]$helpIdentifier, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts for the specified entity" + )] [string]$entity, - [Parameter( ParameterSetName = "filter" )] + [Parameter( + ParameterSetName = "filter", + HelpMessage = "Returns alerts that are dismissed" + )] [switch]$isDismissed ) @@ -35,12 +80,15 @@ function Get-ZertoAlert { } process { + # Select the operation based on the ParameterSetName switch ( $PSCmdlet.ParameterSetName ) { + # If called without any parameters, return all alerts "main" { $uri = "{0}" -f $baseUri $returnObject = Invoke-ZertoRestRequest -uri $uri } + # If called with the alertId ParameterSetName, build an object that contains all alerts for alertIds specified "alertId" { $returnObject = foreach ( $id in $alertId ) { $uri = "{0}/{1}" -f $baseUri, $alertId @@ -48,12 +96,14 @@ function Get-ZertoAlert { } } + # If called with the filter ParameterSetName, get a filter string and get results from API. "filter" { $filter = Get-ZertoApiFilter -filterTable $PSBoundParameters $uri = "{0}{1}" -f $baseUri, $filter $returnObject = Invoke-ZertoRestRequest -uri $uri } + # If any other ParameterSetName is called, build URI based on ParameterSetName and submit default { $uri = "{0}/{1}" -f $baseUri, $PSCmdlet.ParameterSetName.ToLower() $returnObject = Invoke-ZertoRestRequest -uri $uri diff --git a/ZertoApiWrapper/Public/Get-ZertoDatastore.ps1 b/ZertoApiWrapper/Public/Get-ZertoDatastore.ps1 index 1e8bebf..52d0795 100644 --- a/ZertoApiWrapper/Public/Get-ZertoDatastore.ps1 +++ b/ZertoApiWrapper/Public/Get-ZertoDatastore.ps1 @@ -1,7 +1,10 @@ function Get-ZertoDatastore { [cmdletbinding( DefaultParameterSetName = "main" )] param( - [Parameter( ParameterSetName = "datastoreIdentifier" )] + [Parameter( + ParameterSetName = "datastoreIdentifier", + HelpMessage = "datastoreIdentifier or array of datastoreIdentifiers to be queried" + )] [string[]]$datastoreIdentifier ) @@ -11,10 +14,12 @@ function Get-ZertoDatastore { } process { + # If command is called without parameters, return all datastores if ( $PSCmdlet.ParameterSetName -eq "main" ) { $uri = "{0}" -f $baseUri $returnObject = Invoke-ZertoRestRequest -uri $uri } else { + # Return information for datastoreIdentifiers requested $returnObject = foreach ( $id in $datastoreIdentifier ) { $uri = "{0}/{1}" -f $baseUri, $id Invoke-ZertoRestRequest -uri $uri