[IoT Hub] Invoke a query in an IoT hub. (#11567)

* Invoke a query in an IoT hub.

Author: anusapan

src/IotHub/IotHub.Test/ScenarioTests/IotHubDPDeviceTests.ps1

@@ -63,6 +63,10 @@ function Test-AzureRmIotHubDeviceLifecycle
 	Assert-True { $newDevice3.Authentication.Type -eq 'CertificateAuthority' }
 	Assert-False { $newDevice3.Capabilities.IotEdge }
 
+	# Count devices
+	$totalDevices = Invoke-AzIotHubQuery -ResourceGroupName $ResourceGroupName -IotHubName $IotHubName -Query "select * from devices"
+	Assert-True { $totalDevices.Count -eq 3}
+
 	# Get device twin
 	$device1twin = Get-AzIotHubDeviceTwin -ResourceGroupName $ResourceGroupName -IotHubName $IotHubName -DeviceId $device1
 	Assert-True { $device1twin.DeviceId -eq $device1}

src/IotHub/IotHub.Test/ScenarioTests/IotHubDPModuleTests.ps1

@@ -61,6 +61,10 @@ function Test-AzureRmIotHubModuleLifecycle
 	Assert-True { $newModule2.DeviceId -eq $device1 }
 	Assert-True { $newModule2.Authentication.Type -eq 'SelfSigned' }
 
+	# Count device modules
+	$totalModules = Invoke-AzIotHubQuery -ResourceGroupName $ResourceGroupName -IotHubName $IotHubName -Query "select * from devices.modules where devices.Id='$device1'"
+	Assert-True { $totalModules.Count -eq 2}
+
 	# Get module twin
 	$module1twin = Get-AzIotHubModuleTwin -ResourceGroupName $ResourceGroupName -IotHubName $IotHubName -DeviceId $device1 -ModuleId $module1
 	Assert-True { $module1twin.DeviceId -eq $device1}

src/IotHub/IotHub.Test/SessionRecords/Microsoft.Azure.Commands.IotHub.Test.ScenarioTests.IotHubDPDeviceTests/TestAzureIotHubDeviceLifecycle.json

@@ -105,7 +105,7 @@ CmdletsToExport = 'Add-AzIotHubKey', 'Get-AzIotHubEventHubConsumerGroup',
                'Get-AzIotHubModuleTwin', 'Update-AzIotHubModuleTwin',
                'Add-AzIotHubConfiguration', 'Get-AzIotHubConfiguration',
                'Remove-AzIotHubConfiguration', 'Set-AzIotHubConfiguration',
-               'Invoke-AzIotHubModuleMethod'
+               'Invoke-AzIotHubModuleMethod', 'Invoke-AzIotHubQuery'
 # Variables to export from this module
 # VariablesToExport = @()
 

src/IotHub/IotHub.Test/SessionRecords/Microsoft.Azure.Commands.IotHub.Test.ScenarioTests.IotHubDPModuleTests/TestAzureIotHubModuleLifecycle.json

@@ -31,6 +31,7 @@
     - `Remove-AzIotHubConfiguration`
     - `Set-AzIotHubConfiguration`
 * Added cmdlet to invoke an edge module method in an Iot Hub.
+* Added cmdlet to invoke a query in an IoT hub to retrieve information using a SQL-like language.
 
 ## Version 2.3.0
 * Added support to manage distributed settings per-device. New Cmdlets are:

src/IotHub/IotHub/Az.IotHub.psd1

@@ -0,0 +1,103 @@
+// ----------------------------------------------------------------------------------
+//
+// Copyright Microsoft Corporation
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------------
+
+namespace Microsoft.Azure.Commands.Management.IotHub
+{
+    using System.Collections.Generic;
+    using System.Management.Automation;
+    using Microsoft.Azure.Commands.Management.IotHub.Common;
+    using Microsoft.Azure.Commands.Management.IotHub.Models;
+    using Microsoft.Azure.Devices;
+    using Microsoft.Azure.Management.IotHub;
+    using Microsoft.Azure.Management.IotHub.Models;
+    using Microsoft.WindowsAzure.Commands.Utilities.Common;
+    using ResourceManager.Common.ArgumentCompleters;
+
+    [Cmdlet("Invoke", ResourceManager.Common.AzureRMConstants.AzureRMPrefix + "IotHubQuery", DefaultParameterSetName = ResourceParameterSet, SupportsShouldProcess = true)]
+    [OutputType(typeof(string))]
+    public class InvokeAzIotHubQuery : IotHubBaseCmdlet
+    {
+        private const string ResourceIdParameterSet = "ResourceIdSet";
+        private const string ResourceParameterSet = "ResourceSet";
+        private const string InputObjectParameterSet = "InputObjectSet";
+
+        [Parameter(Position = 0, Mandatory = true, ParameterSetName = InputObjectParameterSet, ValueFromPipeline = true, HelpMessage = "IotHub object")]
+        [ValidateNotNullOrEmpty]
+        public PSIotHub InputObject { get; set; }
+
+        [Parameter(Position = 0, Mandatory = true, ParameterSetName = ResourceParameterSet, HelpMessage = "Name of the Resource Group")]
+        [ValidateNotNullOrEmpty]
+        [ResourceGroupCompleter]
+        public string ResourceGroupName { get; set; }
+
+        [Parameter(Position = 0, Mandatory = true, ParameterSetName = ResourceIdParameterSet, ValueFromPipelineByPropertyName = true, HelpMessage = "IotHub Resource Id")]
+        [ValidateNotNullOrEmpty]
+        [ResourceIdCompleter("Microsoft.Devices/IotHubs")]
+        public string ResourceId { get; set; }
+
+        [Parameter(Position = 1, Mandatory = true, ParameterSetName = ResourceParameterSet, HelpMessage = "Name of the Iot Hub")]
+        [ValidateNotNullOrEmpty]
+        public string IotHubName { get; set; }
+
+        [Parameter(Position = 1, Mandatory = true, ParameterSetName = InputObjectParameterSet, HelpMessage = "User query to be executed.")]
+        [Parameter(Position = 1, Mandatory = true, ParameterSetName = ResourceIdParameterSet, HelpMessage = "User query to be executed.")]
+        [Parameter(Position = 2, Mandatory = true, ParameterSetName = ResourceParameterSet, HelpMessage = "User query to be executed.")]
+        [ValidateNotNullOrEmpty]
+        public string Query { get; set; }
+
+        [Parameter(Mandatory = false, HelpMessage = "Maximum number of elements to return. By default query has no cap.")]
+        public int Top { get; set; }
+
+        public override void ExecuteCmdlet()
+        {
+            if (ShouldProcess(this.IotHubName, Properties.Resources.InvokeIotHubQuery))
+            {
+                IotHubDescription iotHubDescription;
+                if (ParameterSetName.Equals(InputObjectParameterSet))
+                {
+                    this.ResourceGroupName = this.InputObject.Resourcegroup;
+                    this.IotHubName = this.InputObject.Name;
+                    iotHubDescription = IotHubUtils.ConvertObject<PSIotHub, IotHubDescription>(this.InputObject);
+                }
+                else
+                {
+                    if (ParameterSetName.Equals(ResourceIdParameterSet))
+                    {
+                        this.ResourceGroupName = IotHubUtils.GetResourceGroupName(this.ResourceId);
+                        this.IotHubName = IotHubUtils.GetIotHubName(this.ResourceId);
+                    }
+
+                    iotHubDescription = this.IotHubClient.IotHubResource.Get(this.ResourceGroupName, this.IotHubName);
+                }
+
+                IEnumerable<SharedAccessSignatureAuthorizationRule> authPolicies = this.IotHubClient.IotHubResource.ListKeys(this.ResourceGroupName, this.IotHubName);
+                SharedAccessSignatureAuthorizationRule policy = IotHubUtils.GetPolicy(authPolicies, PSAccessRights.RegistryRead);
+                PSIotHubConnectionString psIotHubConnectionString = IotHubUtils.ToPSIotHubConnectionString(policy, iotHubDescription.Properties.HostName);
+                RegistryManager registryManager = RegistryManager.CreateFromConnectionString(psIotHubConnectionString.PrimaryConnectionString);
+
+                IQuery query;
+                if (this.IsParameterBound(c => c.Top))
+                {
+                    query = registryManager.CreateQuery(this.Query, this.Top);
+                }
+                else
+                {
+                    query = registryManager.CreateQuery(this.Query);
+                }
+
+                this.WriteObject(query.GetNextAsJsonAsync().GetAwaiter().GetResult(), true);
+            }
+        }
+    }
+}

src/IotHub/IotHub/ChangeLog.md

@@ -237,4 +237,7 @@
   <data name="SetIotHubConfiguration" xml:space="preserve">
     <value>Set Configuration</value>
   </data>
+  <data name="InvokeIotHubQuery" xml:space="preserve">
+    <value>Query an Iot Hub</value>
+  </data>
 </root>

src/IotHub/IotHub/IotHub/DataPlane/InvokeAzIotHubQuery.cs

@@ -116,6 +116,12 @@ Invoke a direct method on a device.
 ### [Invoke-AzIotHubManualFailover](Invoke-AzIotHubManualFailover.md)
 Invoke failover process for the IoT Hub to the geo-paired disaster recovery region.
 
+### [Invoke-AzIotHubModuleMethod](Invoke-AzIotHubModuleMethod.md)
+Invoke an Edge module method.
+
+### [Invoke-AzIotHubQuery](Invoke-AzIotHubQuery.md)
+Query an IoT Hub using a powerful SQL-like language.
+
 ### [New-AzIotHub](New-AzIotHub.md)
 Creates a new IotHub.
 

src/IotHub/IotHub/Properties/Resources.Designer.cs

@@ -1,4 +1,4 @@
----
+---
 external help file: Microsoft.Azure.PowerShell.Cmdlets.IotHub.dll-Help.xml
 Module Name: Az.IotHub
 online version: https://docs.microsoft.com/en-us/powershell/module/az.iothub/invoke-aziothubmodulemethod
@@ -53,7 +53,7 @@ Number of seconds to wait until a connection is successfully made.
 Default is 10.
 
 ```yaml
-Type: Int32
+Type: System.Int32
 Parameter Sets: (All)
 Aliases:
 
@@ -68,7 +68,7 @@ Accept wildcard characters: False
 The credentials, account, tenant, and subscription used for communication with Azure.
 
 ```yaml
-Type: IAzureContextContainer
+Type: Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer
 Parameter Sets: (All)
 Aliases: AzContext, AzureRmContext, AzureCredential
 
@@ -83,7 +83,7 @@ Accept wildcard characters: False
 Target Device Id.
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: (All)
 Aliases:
 
@@ -98,7 +98,7 @@ Accept wildcard characters: False
 IotHub object
 
 ```yaml
-Type: PSIotHub
+Type: Microsoft.Azure.Commands.Management.IotHub.Models.PSIotHub
 Parameter Sets: InputObjectSet
 Aliases:
 
@@ -113,7 +113,7 @@ Accept wildcard characters: False
 Name of the Iot Hub
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: ResourceSet
 Aliases:
 
@@ -128,7 +128,7 @@ Accept wildcard characters: False
 Target device's module id.
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: (All)
 Aliases:
 
@@ -143,7 +143,7 @@ Accept wildcard characters: False
 The name of the method to invoke on this device module.
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: (All)
 Aliases:
 
@@ -158,7 +158,7 @@ Accept wildcard characters: False
 The payload for the method to invoke on this device module.
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: (All)
 Aliases:
 
@@ -173,7 +173,7 @@ Accept wildcard characters: False
 Name of the Resource Group
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: ResourceSet
 Aliases:
 
@@ -188,7 +188,7 @@ Accept wildcard characters: False
 IotHub Resource Id
 
 ```yaml
-Type: String
+Type: System.String
 Parameter Sets: ResourceIdSet
 Aliases:
 
@@ -204,7 +204,7 @@ Number of seconds to wait until a result is received from the direct method.
 Default is 10.
 
 ```yaml
-Type: Int32
+Type: System.Int32
 Parameter Sets: (All)
 Aliases:
 
@@ -219,7 +219,7 @@ Accept wildcard characters: False
 Prompts you for confirmation before running the cmdlet.
 
 ```yaml
-Type: SwitchParameter
+Type: System.Management.Automation.SwitchParameter
 Parameter Sets: (All)
 Aliases: cf
 
@@ -235,7 +235,7 @@ Shows what would happen if the cmdlet runs.
 The cmdlet is not run.
 
 ```yaml
-Type: SwitchParameter
+Type: System.Management.Automation.SwitchParameter
 Parameter Sets: (All)
 Aliases: wi
 
@@ -247,8 +247,7 @@ Accept wildcard characters: False
 ```
 
 ### CommonParameters
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.
-For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS