Skip to content

Commit 2a82457

Browse files
pim-simonsstijnmoreels
pim-simons
and
stijnmoreels
authored
feat: added apim soft delete scripts (#278)
Co-authored-by: Stijn Moreels <9039753+stijnmoreels@users.noreply.github.com> Co-authored-by: Pim Simons <pim.simons@codit.eu>
1 parent f7402d9 commit 2a82457

13 files changed

Lines changed: 576 additions & 0 deletions

‎docs/preview/02-Features/powershell/azure-management.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
2+
---
3+
title: "Azure Management"
4+
layout: default
5+
---
6+
7+
# Azure Management
8+
9+
This module provides the following capabilities:
10+
- [Azure Management](#azure-management)
11+
- [Installation](#installation)
12+
- [Removing a soft deleted API Management instance](#removing-a-soft-deleted-api-management-instance)
13+
- [Restoring a soft deleted API Management instance](#restoring-a-soft-deleted-api-management-instance)
14+
15+
## Installation
16+
17+
To have access to the following features, you have to import the module:
18+
19+
```powershell
20+
PS> Install-Module -Name Arcus.Scripting.Management
21+
```
22+
23+
## Removing a soft deleted API Management instance
24+
25+
Removes a soft deleted API Management instance.
26+
For more information on API Management and soft deletion see [here](https://docs.microsoft.com/en-us/azure/api-management/soft-delete#soft-delete-behavior).
27+
28+
| Parameter | Mandatory | Description |
29+
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
30+
| `Name` | yes | The name of the API Management instance that has been soft deleted. |
31+
| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. |
32+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
33+
| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) |
34+
| `AccessToken` | no | The access token to be used to remove the Azure API Management instance. |
35+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
36+
| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) |
37+
38+
> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`.
39+
40+
**Example**
41+
```powershell
42+
PS> Remove-AzApiManagementSoftDeletedService -Name "my-apim"
43+
# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service
44+
# API Management instance has been found for name 'my-apim' as a soft deleted service
45+
# Removing the soft deleted API Management instance 'my-apim'
46+
# Successfully removed the soft deleted API Management instance 'my-apim'
47+
```
48+
49+
## Restoring a soft deleted API Management instance
50+
51+
Restores a soft deleted API Management instance.
52+
For more information on API Management and soft deletion see [here](https://docs.microsoft.com/en-us/azure/api-management/soft-delete#soft-delete-behavior).
53+
54+
| Parameter | Mandatory | Description |
55+
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
56+
| `Name` | yes | The name of the API Management instance that has been soft deleted. |
57+
| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. |
58+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
59+
| `EnvironmentName`| no | The name of the Azure environment where the Azure API Management instance resides. (default: `AzureCloud`) |
60+
| `AccessToken` | no | The access token to be used to restore the Azure API Management instance. |
61+
| | | When not provided, it will be retrieved from the current context (Get-AzContext). |
62+
| `ApiVersion ` | no | The version of the management API to be used. (default: `2021-08-01`) |
63+
64+
> :bulb: The `ApiVersion` has successfully been tested with version `2021-08-01`.
65+
66+
**Example**
67+
```powershell
68+
PS> Restore-AzApiManagementSoftDeletedService -Name "my-apim"
69+
# Checking if the API Management instance with name 'my-apim' is listed as a soft deleted service
70+
# API Management instance has been found for name 'my-apim' as a soft deleted service
71+
# Restoring the soft deleted API Management instance 'my-apim'
72+
# Successfully restored the soft deleted API Management instance 'my-apim'
73+
```

‎src/Arcus.Scripting.Management/Arcus.Scripting.Management.psd1‎

7.62 KB
Binary file not shown.

‎src/Arcus.Scripting.Management/Arcus.Scripting.Management.psm1‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
<#
2+
.Synopsis
3+
Remove a soft deleted API Management instance.
4+
5+
.Description
6+
Permanently remove a soft deleted API Management instance.
7+
8+
.Parameter Name
9+
The name of the Azure API Management instance which has been soft deleted and will be permanently removed.
10+
11+
.Parameter SubscriptionId
12+
[Optional] The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
13+
14+
.Parameter EnvironmentName
15+
[Optional] The Azure Cloud environment in which the Azure API Management instance resides.
16+
17+
.Parameter AccessToken
18+
[Optional] The access token to be used to restore the Azure API Management instance.
19+
20+
.Parameter ApiVersion
21+
[Optional] The version of the api to be used.
22+
#>
23+
function Remove-AzApiManagementSoftDeletedService {
24+
param(
25+
[Parameter(Mandatory = $true)][string] $Name = $(throw "Name of the API Management instance is required"),
26+
[Parameter(Mandatory = $false)][string] $SubscriptionId = "",
27+
[Parameter(Mandatory = $false)][string] $EnvironmentName = "AzureCloud",
28+
[Parameter(Mandatory = $false)][string] $AccessToken = "",
29+
[Parameter(Mandatory = $false)][string] $ApiVersion = "2021-08-01"
30+
)
31+
32+
. $PSScriptRoot\Scripts\Remove-AzApiManagementSoftDeletedService.ps1 -Name $Name -SubscriptionId $SubscriptionId -EnvironmentName $EnvironmentName -AccessToken $AccessToken -ApiVersion $ApiVersion
33+
}
34+
35+
Export-ModuleMember -Function Remove-AzApiManagementSoftDeletedService
36+
37+
<#
38+
.Synopsis
39+
Restore a soft deleted API Management instance.
40+
41+
.Description
42+
Restore a soft deleted API Management instance.
43+
44+
.Parameter Name
45+
The name of the Azure API Management instance which has been soft deleted and will be restored.
46+
47+
.Parameter SubscriptionId
48+
[Optional] The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
49+
50+
.Parameter EnvironmentName
51+
[Optional] The Azure Cloud environment in which the Azure API Management instance resides.
52+
53+
.Parameter AccessToken
54+
[Optional] The access token to be used to restore the Azure API Management instance.
55+
56+
.Parameter ApiVersion
57+
[Optional] The version of the api to be used.
58+
#>
59+
function Restore-AzApiManagementSoftDeletedService {
60+
param(
61+
[Parameter(Mandatory = $true)][string] $Name = $(throw "Name of the API Management instance is required"),
62+
[Parameter(Mandatory = $false)][string] $SubscriptionId = "",
63+
[Parameter(Mandatory = $false)][string] $EnvironmentName = "AzureCloud",
64+
[Parameter(Mandatory = $false)][string] $AccessToken = "",
65+
[Parameter(Mandatory = $false)][string] $ApiVersion = "2021-08-01"
66+
)
67+
68+
. $PSScriptRoot\Scripts\Restore-AzApiManagementSoftDeletedService.ps1 -Name $Name -SubscriptionId $SubscriptionId -EnvironmentName $EnvironmentName -AccessToken $AccessToken -ApiVersion $ApiVersion
69+
}
70+
71+
Export-ModuleMember -Function Restore-AzApiManagementSoftDeletedService

‎src/Arcus.Scripting.Management/Arcus.Scripting.Management.pssproj‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
2+
<PropertyGroup>
3+
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
4+
<SchemaVersion>2.0</SchemaVersion>
5+
<ProjectGuid>{a7b00f0f-4e7b-48d3-9a3e-6ae99602d2cd}</ProjectGuid>
6+
<OutputType>Exe</OutputType>
7+
<RootNamespace>Arcus.Scripting.Management</RootNamespace>
8+
<AssemblyName>Arcus.Scripting.Management</AssemblyName>
9+
<Name>Arcus.Scripting.Management</Name>
10+
<ProjectHome />
11+
</PropertyGroup>
12+
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
13+
<DebugSymbols>true</DebugSymbols>
14+
<DebugType>full</DebugType>
15+
<Optimize>false</Optimize>
16+
<OutputPath>bin\Debug\</OutputPath>
17+
<DefineConstants>DEBUG;TRACE</DefineConstants>
18+
<ErrorReport>prompt</ErrorReport>
19+
<WarningLevel>4</WarningLevel>
20+
</PropertyGroup>
21+
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
22+
<DebugType>pdbonly</DebugType>
23+
<Optimize>true</Optimize>
24+
<OutputPath>bin\Release\</OutputPath>
25+
<DefineConstants>TRACE</DefineConstants>
26+
<ErrorReport>prompt</ErrorReport>
27+
<WarningLevel>4</WarningLevel>
28+
</PropertyGroup>
29+
<ItemGroup>
30+
<Folder Include="Scripts\" />
31+
</ItemGroup>
32+
<ItemGroup>
33+
<Compile Include="Arcus.Scripting.Management.psd1" />
34+
<Compile Include="Arcus.Scripting.Management.psm1" />
35+
<Compile Include="Scripts\Get-AzApiManagementSoftDeletedResources.ps1" />
36+
<Compile Include="Scripts\Get-AzApiManagementResourceManagementUrl.ps1" />
37+
<Compile Include="Scripts\Remove-AzApiManagementSoftDeletedService.ps1" />
38+
<Compile Include="Scripts\Restore-AzApiManagementSoftDeletedService.ps1" />
39+
</ItemGroup>
40+
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
41+
<Target Name="Build" />
42+
<Import Project="$(MSBuildExtensionsPath)\PowerShell Tools for Visual Studio\PowerShellTools.targets" Condition="Exists('$(MSBuildExtensionsPath)\PowerShell Tools for Visual Studio\PowerShellTools.targets')" />
43+
</Project>

‎src/Arcus.Scripting.Management/Scripts/Get-AzApiManagementResourceManagementUrl.ps1‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
param(
2+
[Parameter(Mandatory = $true)][string] $EnvironmentName
3+
)
4+
5+
try {
6+
$resourceManagerUrl = ""
7+
8+
$environments = (Get-AzEnvironment).Name
9+
if ($EnvironmentName -notin $environments) {
10+
$supportedEnvironments = ""
11+
12+
foreach ($env in $environments) {
13+
if ($supportedEnvironments.Length -eq 0) {
14+
$supportedEnvironments += $env
15+
}
16+
else {
17+
$supportedEnvironments += ", " + $env
18+
}
19+
}
20+
21+
Write-Error "Unrecognized environment specified. Supported values are: $supportedEnvironments"
22+
}
23+
24+
$resourceManagerUrl = (Get-AzEnvironment -Name $EnvironmentName).ResourceManagerUrl
25+
26+
return $resourceManagerUrl
27+
}
28+
catch {
29+
Write-Warning "Failed to retrieve the resource management endpoint"
30+
$ErrorMessage = $_.Exception.Message
31+
Write-Warning "Error: $ErrorMessage"
32+
}

‎src/Arcus.Scripting.Management/Scripts/Get-AzApiManagementSoftDeletedResources.ps1‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
param(
2+
[Parameter(Mandatory = $true)][string] $Name,
3+
[Parameter(Mandatory = $true)][string] $SubscriptionId,
4+
[Parameter(Mandatory = $true)][string] $ResourceManagerUrl,
5+
[Parameter(Mandatory = $true)][object] $AuthHeader,
6+
[Parameter(Mandatory = $true)][string] $ApiVersion
7+
)
8+
9+
Write-Verbose "Checking if the API Management instance with name '$Name' is listed as a soft deleted service"
10+
$getUri = "$ResourceManagerUrl" + "subscriptions/$SubscriptionId/providers/Microsoft.ApiManagement/deletedservices" + "?api-version=$ApiVersion"
11+
12+
$deletedServices = (Invoke-RestMethod -Method GET -Uri $getUri -Headers $AuthHeader)
13+
14+
if ($deletedServices.value.count -eq 0 -or ($deletedServices.value | Where-Object name -eq $Name).count -eq 0) {
15+
throw "API Management instance with name '$Name' is not listed as a soft deleted service and therefore it cannot be removed or restored"
16+
}
17+
18+
Write-Host "API Management instance has been found for name '$Name' as a soft deleted service"
19+
20+
return $deletedServices

‎src/Arcus.Scripting.Management/Scripts/Remove-AzApiManagementSoftDeletedService.ps1‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
param(
2+
[Parameter(Mandatory = $true)][string] $Name = $(throw "Name of the API Management instance is required"),
3+
[Parameter(Mandatory = $false)][string] $SubscriptionId = "",
4+
[Parameter(Mandatory = $false)][string] $EnvironmentName = "AzureCloud",
5+
[Parameter(Mandatory = $false)][string] $AccessToken = "",
6+
[Parameter(Mandatory = $false)][string] $ApiVersion = "2021-08-01"
7+
)
8+
9+
if ($SubscriptionId -eq "" -or $AccessToken -eq "") {
10+
# Request accessToken in case the script contains no records
11+
$token = Get-AzCachedAccessToken
12+
13+
$AccessToken = $token.AccessToken
14+
$SubscriptionId = $token.SubscriptionId
15+
}
16+
17+
$authHeader = @{
18+
'Authorization'='Bearer ' + $AccessToken
19+
}
20+
21+
$resourceManagerUrl = . $PSScriptRoot\Get-AzApiManagementResourceManagementUrl.ps1 -EnvironmentName $EnvironmentName
22+
23+
$deletedServices = . $PSScriptRoot\Get-AzApiManagementSoftDeletedResources.ps1 -Name $Name -SubscriptionId $SubscriptionId -ResourceManagerUrl $resourceManagerUrl -AuthHeader $authHeader -ApiVersion $ApiVersion
24+
25+
Write-Host "Removing the soft deleted API Management instance '$Name'"
26+
try {
27+
$serviceId = ($deletedServices.value | Where-Object name -eq $Name).id
28+
$deleteUri = "$resourceManagerUrl" + "$serviceId" + "?api-version=$ApiVersion"
29+
$removeService = Invoke-RestMethod -Method DELETE -Uri $deleteUri -Headers $authHeader
30+
} catch {
31+
throw "The soft deleted API Management instance '$Name' could not be removed. Details: $($_.Exception.Message)"
32+
}
33+
34+
Write-Host "Successfully removed the soft deleted API Management instance '$Name'"

‎src/Arcus.Scripting.Management/Scripts/Restore-AzApiManagementSoftDeletedService.ps1‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
param(
2+
[Parameter(Mandatory = $true)][string] $Name = $(throw "Name of the API Management instance is required"),
3+
[Parameter(Mandatory = $false)][string] $SubscriptionId = "",
4+
[Parameter(Mandatory = $false)][string] $EnvironmentName = "AzureCloud",
5+
[Parameter(Mandatory = $false)][string] $AccessToken = "",
6+
[Parameter(Mandatory = $false)][string] $ApiVersion = "2021-08-01"
7+
)
8+
9+
if ($SubscriptionId -eq "" -or $AccessToken -eq "") {
10+
# Request accessToken in case the script contains no records
11+
$token = Get-AzCachedAccessToken
12+
13+
$AccessToken = $token.AccessToken
14+
$SubscriptionId = $token.SubscriptionId
15+
}
16+
17+
$authHeader = @{
18+
'Authorization'='Bearer ' + $AccessToken
19+
}
20+
21+
$resourceManagerUrl = . $PSScriptRoot\Get-AzApiManagementResourceManagementUrl.ps1 -EnvironmentName $EnvironmentName
22+
23+
$deletedServices = . $PSScriptRoot\Get-AzApiManagementSoftDeletedResources.ps1 -Name $Name -SubscriptionId $SubscriptionId -ResourceManagerUrl $resourceManagerUrl -AuthHeader $authHeader -ApiVersion $ApiVersion
24+
25+
Write-Host "Restoring the soft deleted API Management instance '$Name'"
26+
try {
27+
$location = ($deletedServices.value | Where-Object name -eq $Name).location
28+
$serviceId = ($deletedServices.value | Where-Object name -eq $Name).properties.serviceId
29+
$data = @{
30+
location = $location
31+
properties = @{
32+
restore = $true
33+
};
34+
};
35+
$body = $data | ConvertTo-Json;
36+
$putUri = "$resourceManagerUrl" + "$serviceId" + "?api-version=$ApiVersion"
37+
$restoreService = Invoke-RestMethod -Method PUT -Uri $putUri -ContentType 'application/json' -Headers $authHeader -Body $body
38+
} catch {
39+
throw "The soft deleted API Management instance '$Name' could not be restored. Details: $($_.Exception.Message)"
40+
}
41+
42+
Write-Host "Successfully restored the soft deleted API Management instance '$Name'"

‎src/Arcus.Scripting.Tests.Integration/Arcus.Scripting.Management.tests.ps1‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Import-Module -Name $PSScriptRoot\..\Arcus.Scripting.Management -ErrorAction Stop
2+
Import-Module -Name $PSScriptRoot\..\Arcus.Scripting.Security -ErrorAction Stop
3+
4+
InModuleScope Arcus.Scripting.Management {
5+
Describe "Arcus Azure Management integration tests" {
6+
BeforeEach {
7+
$config = & $PSScriptRoot\Load-JsonAppsettings.ps1 -fileName "appsettings.json"
8+
& $PSScriptRoot\Connect-AzAccountFromConfig.ps1 -config $config
9+
}
10+
Context "Remove soft deleted Azure API Management service" {
11+
It "Providing an API Management name that does not exist as a soft deleted service should fail" {
12+
# Arrange
13+
$Name = 'unexisting-apim-instance'
14+
15+
# Act
16+
{
17+
Remove-AzApiManagementSoftDeletedService -Name $Name
18+
} | Should -Throw -ExpectedMessage "API Management instance with name '$Name' is not listed as a soft deleted service and therefore it cannot be removed or restored"
19+
}
20+
}
21+
Context "Restore soft deleted Azure API Management service" {
22+
It "Providing an API Management name that does not exist as a soft deleted service should fail" {
23+
# Arrange
24+
$Name = 'unexisting-apim-instance'
25+
26+
# Act
27+
{
28+
Restore-AzApiManagementSoftDeletedService -Name $Name
29+
} | Should -Throw -ExpectedMessage "API Management instance with name '$Name' is not listed as a soft deleted service and therefore it cannot be removed or restored"
30+
}
31+
}
32+
}
33+
}

‎src/Arcus.Scripting.Tests.Integration/Arcus.Scripting.Tests.Integration.pssproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
<WarningLevel>4</WarningLevel>
2727
</PropertyGroup>
2828
<ItemGroup>
29+
<Compile Include="Arcus.Scripting.Management.tests.ps1" />
2930
<Compile Include="Arcus.Scripting.ARM.tests.ps1" />
3031
<Compile Include="Arcus.Scripting.DevOps.tests.ps1" />
3132
<Compile Include="Arcus.Scripting.AppService.tests.ps1" />

0 commit comments

Comments
 (0)