diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 new file mode 100644 index 0000000000..ed091924be --- /dev/null +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -0,0 +1,118 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +function Get-EntraDeletedDevice { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all deleted devices.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for devices.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Device Object ID to retrieve.")] + [System.String] $DeviceObjectId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DeviceObjectId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DeviceObjectId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgDirectoryDeletedItemAsDevice @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgDirectoryDeletedItemAsDevice @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the deleted devices: $_" + } + } +} \ No newline at end of file diff --git a/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 new file mode 100644 index 0000000000..5c57b40dbf --- /dev/null +++ b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 @@ -0,0 +1,118 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +function Get-EntraBetaDeletedDevice { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all deleted devices.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for devices.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Device Object ID to retrieve.")] + [System.String] $DeviceObjectId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraBetaCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DeviceObjectId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DeviceObjectId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the deleted devices: $_" + } + } +} \ No newline at end of file diff --git a/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md new file mode 100644 index 0000000000..63323911c0 --- /dev/null +++ b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md @@ -0,0 +1,277 @@ +--- +title: Get-EntraBetaDeletedDevice +description: This article provides details on the Get-EntraBetaDeletedDevice command. + + +ms.topic: reference +ms.date: 11/14/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra.Beta-Help.xml +Module Name: Microsoft.Graph.Entra.Beta +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice + +schema: 2.0.0 +--- + +# Get-EntraBetaDeletedDevice + +## Synopsis + +Retrieves the list of previously deleted devices. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraBetaDeletedDevice + [-Filter ] + [-All] + [-Top ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraBetaDeletedDevice + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraBetaDeletedDevice + -DeviceObjectId + [-All] + [-Property ] + [] +``` + +## Description + +The `Get-EntraBetaDeletedDevice` cmdlet Retrieves the list of previously deleted devices. + +## Examples + +### Example 1: Get list of deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices. + +### Example 2: Get list of deleted devices using All parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -All +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices using All parameter. + +### Example 3: Get top two deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -Top 2 +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 +``` + +This cmdlet retrieves top two deleted devices. + +### Example 4: Get deleted devices using SearchString parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -SearchString 'Woodgrove Desktop' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices using SearchString parameter. + +### Example 5: Get deleted devices filter by display name + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -Filter "DisplayName eq 'Woodgrove Desktop'" +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices having specified display name. + +### Example 6: Get deleted device by DeviceObjectId + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -DeviceObjectId 'cccccccc-2222-3333-4444-dddddddddddd' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves the deleted device specified by DeviceObjectId. + +- `-DeviceObjectId` parameter specifies the deleted device Id. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Filter + +Retrieve only those deleted devices that satisfy the filter. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Retrieve only those devices that satisfy the -SearchString value. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +The maximum number of devices. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DeviceObjectId + +The unique ID of the deleted device to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +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](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraBetaDevice](Get-EntraBetaDevice.md) diff --git a/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md new file mode 100644 index 0000000000..9e46ff6b5a --- /dev/null +++ b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md @@ -0,0 +1,277 @@ +--- +title: Get-EntraDeletedDevice +description: This article provides details on the Get-EntraDeletedDevice command. + + +ms.topic: reference +ms.date: 11/14/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra-Help.xml +Module Name: Microsoft.Graph.Entra +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra/Get-EntraDeletedDevice + +schema: 2.0.0 +--- + +# Get-EntraDeletedDevice + +## Synopsis + +Retrieves the list of previously deleted devices. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraDeletedDevice + [-Filter ] + [-All] + [-Top ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraDeletedDevice + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraDeletedDevice + -DeviceObjectId + [-All] + [-Property ] + [] +``` + +## Description + +The `Get-EntraDeletedDevice` cmdlet Retrieves the list of previously deleted devices. + +## Examples + +### Example 1: Get list of deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices. + +### Example 2: Get list of deleted devices using All parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -All +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices using All parameter. + +### Example 3: Get top two deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -Top 2 +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 +``` + +This cmdlet retrieves top two deleted devices. + +### Example 4: Get deleted devices using SearchString parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -SearchString 'Woodgrove Desktop' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices using SearchString parameter. + +### Example 5: Get deleted devices filter by display name + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -Filter "DisplayName eq 'Woodgrove Desktop'" +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices having specified display name. + +### Example 6: Get deleted device by DeviceObjectId + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -DeviceObjectId 'cccccccc-2222-3333-4444-dddddddddddd' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves the deleted device specified by DeviceObjectId. + +- `-DeviceObjectId` parameter specifies the deleted device Id. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Filter + +Retrieve only those deleted devices that satisfy the filter. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Retrieve only those devices that satisfy the -SearchString value. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +The maximum number of devices. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DeviceObjectId + +The unique ID of the deleted device to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +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](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraDevice](Get-EntraDevice.md) diff --git a/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 b/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 new file mode 100644 index 0000000000..57e6e8583e --- /dev/null +++ b/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 @@ -0,0 +1,93 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Graph.Entra) -eq $null) { + Import-Module Microsoft.Graph.Entra + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "iPhone 12 Pro" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeviceCategory" = "Test" + "AccountEnabled" = "True" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "DeviceId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgDirectoryDeletedItemAsDevice -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra +} + +Describe "Get-EntraDeletedDevice" { + Context "Test for Get-EntraDeletedDevice" { + It "Should return all devices" { + $result = Get-EntraDeletedDevice + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return specific device by searchstring" { + $result = Get-EntraDeletedDevice -SearchString 'iPhone 12 Pro' + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return specific device by filter" { + $result = Get-EntraDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return top device" { + $result = Get-EntraDeletedDevice -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraDeletedDevice -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "iPhone 12 Pro" + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraDeletedDevice -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedDevice" + $result = Get-EntraDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedDevice" + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraDeletedDevice -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file diff --git a/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 b/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 new file mode 100644 index 0000000000..e9eb15279b --- /dev/null +++ b/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 @@ -0,0 +1,93 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Graph.Entra.Beta) -eq $null) { + Import-Module Microsoft.Graph.Entra.Beta + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "iPhone 12 Pro" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeviceCategory" = "Test" + "AccountEnabled" = "True" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "DeviceId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra.Beta +} + +Describe "Get-EntraBetaDeletedDevice" { + Context "Test for Get-EntraBetaDeletedDevice" { + It "Should return all devices" { + $result = Get-EntraBetaDeletedDevice + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return specific device by searchstring" { + $result = Get-EntraBetaDeletedDevice -SearchString 'iPhone 12 Pro' + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return specific device by filter" { + $result = Get-EntraBetaDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return top device" { + $result = Get-EntraBetaDeletedDevice -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraBetaDeletedDevice -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "iPhone 12 Pro" + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraBetaDeletedDevice -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedDevice" + $result = Get-EntraBetaDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedDevice" + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraBetaDeletedDevice -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file