Invoking RESTful APIs from PowerShell Scripts

Zerto provides an extensive set of RESTful APIs to enable clients to manage Zerto Virtual Replication without using the Zerto User Interface.

This describes how to invoke Zerto APIs using Windows PowerShell. It shows how to authenticate with the service and shows the different ways to send data to, and receive data from, the Zerto APIs.

Zerto RESTful APIs are divided into the following types:

•

Authentication

•

HTTP requests

If you intend to invoke Zerto APIs from PowerShell, you must install PowerShell version 4.0 or higher.

All references to Zerto RESTful APIs assume the following base URL:

https://zvm-ip:zvm-port/v1

Where:

zvm-ip	The IP address of the Zerto Virtual Manager where the API is run.
zvm-port	The port to access the Zerto Virtual Manager. The default port is 9669.

See the following sections:

•

Authentication

•

Using the x-zerto-session Variable

•

Basic Invocation

•

Input Format

•

Output Format

•

Examples

Authentication

To authenticate, invoke the following API:

https://zvm-ip:zvm-port/v1/session/add

The response to this request contains a variable called x-zerto-session that contains a unique session ID that is used in subsequent requests to APIs.

Authentication Sample

The following code snippet shows an example of authentication.

	$baseURL = "https://" + $strZVMIP + ":"+$strZVMPort
5	$xZertoSessionURL = $baseURL +"/v1/session/add"
1	$authInfo = ("{0}:{1}" -f $userName,$password)
2	$authInfo = [System.Text.Encoding]::UTF8.GetBytes($authInfo)
3	$authInfo = [System.Convert]::ToBase64String($authInfo)
4	$headers = @{Authorization=("Basic {0}" -f $authInfo)}
	$contentType = "application/json"
7	$xZertoSessionResponse = Invoke-WebRequest -Uri $xZertoSessionURL -Headers $headers                                            -Method POST -Body $body -ContentType $contentType
8	return $xZertoSessionResponse.headers.get_item("x-zerto-session")

The following list explains the authentication sample.

1.

Create an authentication object array from the username and password.

2.

Convert the authentication object to UTF8.

3.

Convert the information to base64 format.

4.

Build the basic authentication format into a header variable.

5.

Build the session request URL.

6.

Authenticate the user's credentials. The field contentType authenticates a user's credentials.

7.

Invoke the HTTP request to the specified URL, given the authentication header. The response will contain a header with the x-zerto-session variable.

8.

Extract the x-zerto-session value from the response headers.

Using the x-zerto-session Variable

Once you have obtained the x-zerto-session unique session identifier, build a header for subsequent HTTP requests containing the session identifier:

$zertSessionHeader = @{"x-zerto-session"=$xZertoSession}

where $xZertoSession holds the unique session identifier.

Basic Invocation

Running Zerto APIs from PowerShell is based on the Invoke-RestMethod command.

A basic invocation is similar to the following:

$vpgListApiUrl = "https://" + $strZVMIP + ":"+$strZVMPort+"/v1/vpgs"
                               Invoke-RestMethod -Uri $vpgListApiUrl -Headers $zertSessionHeader

Input Format

If the request requires parameters that do not reside in the URL, such as POST requests, specify the input format type using the –ContentType argument and switch between XML and JSON.

Output Format

The output formats of the API requests can be parsed as XML or JSON. PowerShell offers additional formats to which the data can be converted. You also have the ability to save the response to a file.

Specify the output format type using the –accept header.

For example, running the baseURL/v1/VPGs request returns a list of VPGs configured for a specific site.

Examples

Following are script examples.

Example 1: Get Information

The following code sample gets a list of VPGs from a specific Zerto Virtual Manager, and gets a VPG identifier based on a VPG name.

$strZVMIP = "{ZVM IP}"
$strZVMPort = "{ZVM HTTPS port}"
$strZVMUser = "{ZVM user}"
$strZVMPwd = "{ZVM user password}"
## Perform authentication so that Zerto APIs can run. Return a session identifier that needs to be inserted in the header for subsequent requests.
## For more details, see Zerto Virtual Replication RESTful API Reference Guide.
function getxZertoSession ($userName, $password){
  $baseURL = "https://" + $strZVMIP + ":"+$strZVMPort
  $xZertoSessionURI = $baseURL +"/v1/session/add"
  $authInfo = ("{0}:{1}" -f $userName,$password)
  $authInfo = [System.Text.Encoding]::UTF8.GetBytes($authInfo)
  $authInfo = [System.Convert]::ToBase64String($authInfo)
  $headers = @{Authorization=("Basic {0}" -f $authInfo)}
  $contentType = "application/json"
  $xZertoSessionResponse = Invoke-WebRequest -Uri $xZertoSessionURI
                   -Headers $headers -Method POST -Body $body -ContentType $contentType
 
    #$xZertoSessionResponse = Invoke-WebRequest -Uri $xZertoSessionURI
                                            -Headers $headers -Body $body -Method POST
    return $xZertoSessionResponse.headers.get_item("x-zerto-session")
}
#Extract x-zerto-session from the response, and add it to the actual API:
$xZertoSession = getxZertoSession $strZVMUser $strZVMPwd
$zertoSessionHeader = @{"x-zerto-session"=$xZertoSession}
 
#Invoke the Zerto API:
$vpgListApiUrl = "https://" + $strZVMIP + ":"+$strZVMPort+"/v1/vpgs"
$VPGNAME = "MyApp"
#Iterate with XML:
$vpgListXML= Invoke-RestMethod -Uri $vpgListApiUrl -Headers $zertoSessionHeader
                                                    -ContentType "application/xml"
foreach ($vpg in $vpgListXML.ArrayOfVpgApi.VpgApi){
  if ($vpg.VpgName -eq $VPGNAME){
    $tmpVpgIdentifier = $vpg.VpgIdentifier
    break
  }
}
#Iterate with JSON:
$vpgListJSON = Invoke-RestMethod -Uri $vpgListApiUrl -Headers $zertoSessionHeader
                                                     -ContentType "application/json"
foreach ($vpg in $vpgListJSON){
  if ($vpg.VpgName -eq $VPGNAME){
    $tmpVpgIdentifier = $vpg.VpgIdentifier
    break
  }
}
write-host $tmpVpgIdentifier
##End of script

Example 2: Perform an Action

The following code sample creates a VPG with a list of VMs specified in a file.

Both pre-recovery and post-recovery scripts are run by the ZVM service on the ZVM machine. The account running the ZVM service is the account that will run the scripts when they are executed

#Parameters Section
$strZVMIP = "{Zerto Virtual Manager IP}"
$strZVMPort = "{Zerto Virtual Manager HTTPS port}"
$strZVMUser = "{Zerto Virtual Manager user}"
$strZVMPw = "{Zerto Virtual Manager user password}"
$sourceSiteName = "{protected site name}"
$targetSiteName = "{recovery site name}"
$targetDataStoreName = "{recovery storage name in the recovery site for the VPG}"
$vpgName = "{name of the VPG you want to create}"
$unProtectedVMsCSVFile = "name of the file that has the names of the VMs to add to the VPG. The file must not have headers, and the VM names must be separated with commas, without spaces between the names. For example, the first row in the file would look like this: vm1,vm2,vm3}"
$BASEURL = "https://" + $strZVMIP + ":"+$strZVMPort+"/v1/" #base URL for all APIs
$zertoSessionHeader_xml = @{"Accept"="application/xml"
"x-zerto-session"=$xZertoSession}
##Function Definitions
#Get a site identifier by invoking Zerto APIs, given a Zerto API session and a site name:
function getSiteIdentifierByName ($sessionHeader, $siteName){
  $url = $BASEURL + "virtualizationsites"
  $response = Invoke-RestMethod -Uri $url -Headers $zertoSessionHeader_xml
  ForEach ($site in $response.ArrayOfVirtualizationSiteApi.VirtualizationSiteApi) {
    if ($site.VirtualizationSiteName -eq $siteName){
      return $site.SiteIdentifier
    }
  }
}
#Get a storage identifier by invoking Zerto APIs, given a Zerto API session and a storage name:
function getDatastoreIdentifierByName ($sessionHeader, $siteIdentfier, $datastoreName){
  $url = $BASEURL + "virtualizationsites/"+$siteIdentfier + "/datastores"
  $response = Invoke-RestMethod -Uri $url -Headers $zertoSessionHeader_xml
  ForEach ($datastore in $response.ArrayOfDatastoreNativeApi.DatastoreNativeApi) {
    if ($datastore.DatastoreName -eq $datastoreName){
      return $datastore.DatastoreIdentifier
    }
  }
}
#Get unprotected VM identifiers by invoking Zerto APIs, given a Zerto API session, a site identifier, and a list of VMs to add to the VPG:
function getUnprotectedVMsIdentifiers($sessionHeader, $siteIdentfier, $VMNames){
  $url = $BASEURL + "virtualizationsites/"+$siteIdentfier + "/vms"
  $unprotectedVMsIdentifiers = @()
  $response= Invoke-RestMethod -Uri $url -Headers $zertoSessionHeader_xml
  ForEach ($vm in $response.ArrayOfVmNativeApi.VmNativeApi) {
    if ($VMNames.IndexOf($vm.VmName) -gt -1){
      $unprotectedVMsIdentifiers+=($vm.VmIdentifier)
    }
  }
  return $unprotectedVMsIdentifiers
}
#Authenticate with Zerto APIs: create a Zerto API session and return it, to be used in other APIs
function getZertoXSession (){
  #Authenticate with Zerto APIs:
  $xZertoSessionURL = "https://" + $strZVMIP + ":"+$strZVMPort+"/v1/session/add"
  $authInfo = ("{0}:{1}" -f $strZVMUser,$strZVMPw)
  $authInfo = [System.Text.Encoding]::UTF8.GetBytes($authInfo)
  $authInfo = [System.Convert]::ToBase64String($authInfo)
  $headers = @{Authorization=("Basic {0}" -f $authInfo)}
  $xZertoSessionResponse = Invoke-WebRequest -Uri $xZertoSessionURL -Headers $headers -Method POST
  #Extract x-zerto-session from the response and add it to the actual API:
  $xZertoSession = $xZertoSessionResponse.headers.get_item("x-zerto-session")
  return $xZertoSession
}
#Build VM elements to be added to the VPGs API, based on a list of VM identifiers
function buildVMsElement ($VMs) {
$response = "<VmsIdentifiers>"
 
  ForEach ($vm in $VMs) {
    $response+="<string xmlns="+'"http://schemas.microsoft.com/2003/10/Serialization/Arrays"'+">"+$vm+"</string>"
  }
  $response += "</VmsIdentifiers>"
  return $response
}
#Script starts here:
$xZertoSession = getZertoXSession
 
$zertoSessionHeader = @{"x-zerto-session"=$xZertoSession}
 
$sourceSiteIdentifier = getSiteIdentifierByName $zertoSessionHeader $sourceSiteName
 
$targetSiteIdentifier = getSiteIdentifierByName $zertoSessionHeader $targetSiteName
 
$dataStoreIdentifier = getDatastoreIdentifierByName $zertoSessionHeader $targetSiteIdentifier$targetDataStoreName
 
$unprotectedVMNames = Get-Content $unProtectedVMsCSVFile | %{$_.Split(",")}
 
$vmsIdentifiers = getUnprotectedVMsIdentifiers $zertoSessionHeader $sourceSiteIdentifier$unprotectedVMNames
 
$vmsIdentifiersElement = buildVMsElement $vmsIdentifiers
#Create the URL and body of the VPGs request:
$createVPGUrl = $BASEURL+"vpgs"
$vpgsRequestBody = "<VpgCreateDataApi xmlns="+'"http://schemas.zerto.com/zvm/api"'+">"
            +"<DatastoreIdentifier>"+$dataStoreIdentifier +"</DatastoreIdentifier>
            <SourceSiteIdentifier>"+$sourceSiteIdentifier+"</SourceSiteIdentifier>
            <TargetSiteIdentifier>"+$targetSiteIdentifier+"</TargetSiteIdentifier>"
            +$vmsIdentifiersElement+"<VpgName>"+$vpgName+"</VpgName> </VpgCreateDataApi>"
#Invoke the Zerto API:
Invoke-RestMethod -Uri $createVPGUrl -Headers $zertoSessionHeader
                    -Body $vpgsRequestBody -ContentType "application/xml" -method POST
##End of script