PowerShell support for on-premises data gateway clusters

Note

We recently revised the on-premises data gateway docs. We split them into content that's specific to Power BI and general content that applies to all services that the gateway supports. You're currently in the general content. To provide feedback on this article, or the overall gateway docs experience, scroll to the bottom of the article.

PowerShell scripts are available in the the PowerShell gallery. You must be using PowerShell version 5 or newer for these scripts to work correctly. You can use the PowerShell scripts to perform the following operations:

  • Retrieve the list of gateway clusters available for a user.
  • Retrieve the list of gateway instances registered in a cluster and their online or offline status.
  • Modify the enable or disable status for a gateway instance within a cluster and other gateway properties.
  • Delete a gateway.

Run the PowerShell commands

To install these cmdlets, run the following command in an elevated PowerShell session:

Install-Module -Name OnPremisesDataGatewayHAMgmt

The entire list of cmdlets can be found using the following command:

Get-Command -Module OnPremisesDataGateway*

Examples and descriptions are included in the cmdlets and you can access them using the following command:

get-help <cmdlet-name>

Now you can use the commands in the following table to manage your gateway clusters.

Command Description Parameters
Login-OnPremisesDataGateway Use this command to sign in to manage your on-premises data gateway clusters. You must run this command and sign in before other high-availability commands can work properly. Note: The Azure Active Directory auth token acquired as part of a Login call is valid for only 1 hour, after which it expires. You can rerun the Login command to acquire a new token. Azure Active Directory username and password (provided as part of the command execution, not initial invocation).
Get-OnPremisesDataGatewayClusters Retrieves the list of gateway clusters for the signed-in user. Optionally, you can pass formatting parameters to this command for better readability, such as Format-Table -AutoSize -Wrap.
Get-OnPremisesDataClusterGateways Retrieves the list of gateways within the specified cluster and additional information for each gateway like online or offline status and machine name. -ClusterObjectID xyz (where xyz is replaced with an actual cluster object ID value, which can be retrieved by using the Get-OnPremisesDataGatewayClusters command).
Set-OnPremisesDataGateway Use this command to set property values for a given gateway within a cluster, which includes the ability to enable or disable a specific gateway instance. -ClusterObjectID xyz (where xyz is replaced with an actual cluster object ID value, which can be retrieved by using the Get-OnPremisesDataGatewayClusters command). -GatewayObjectID abc (where abc is replaced with an actual gateway object ID value, which can be retrieved by using the Get-OnPremisesDataClusterGateways command, given a cluster object ID).
Get-OnPremisesDataGatewayStatus Use this command to retrieve the status for a given gateway instance within a cluster. -ClusterObjectID xyz (where xyz is replaced with an actual cluster object ID value, which can be retrieved by using the Get-OnPremisesDataGatewayClusters command). -GatewayObjectID abc (where abc is replaced with an actual gateway object ID value, which can be retrieved by using the Get-OnPremisesDataClusterGateways command, given a cluster object ID).
Remove-OnPremisesDataGateway Use this command to remove a gateway instance from a cluster. Note: The primary gateway in the cluster can't be removed until all other gateways in the cluster are removed. -ClusterObjectID xyz (where xyz is replaced with an actual cluster object ID value, which can be retrieved by using the Get-OnPremisesDataGatewayClusters command). -GatewayObjectID abc (where abc is replaced with an actual gateway object ID value, which can be retrieved by using the Get-OnPremisesDataClusterGateways command, given a cluster object ID).

Next steps