Feature - create new API operation on API Management service script (#50

) * Feature - create new API operation on API Management service script * pr-sug: add '-DisableNameChecking' during importing module * pr-sug: fix typo in api management * pr-fix: use concrete type as return type * Update Arcus.Scripting.ApiManagement.tests.ps1 * Update Arcus.Scripting.ApiManagement.tests.ps1 * Update Arcus.Scripting.ApiManagement.tests.ps1 * Update docs/preview/features/powershell/azure-api-management.md Co-authored-by: Maxim Braekman <[email protected]> * Update src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 Co-authored-by: Maxim Braekman <[email protected]> * Update docs/preview/features/powershell/azure-api-management.md Co-authored-by: Maxim Braekman <[email protected]> * Update src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 Co-authored-by: Maxim Braekman <[email protected]> * pr-sug: add with using module * pr-sug: update with context assertion Co-authored-by: Maxim Braekman <[email protected]>
arcus-azure · Jun 22, 2020 · 0c8fb0c · 0c8fb0c
1 parent 7653312
commit 0c8fb0c
Show file tree

Hide file tree

Showing 8 changed files with 206 additions and 4 deletions.
diff --git a/docs/preview/features/powershell/azure-api-management.md b/docs/preview/features/powershell/azure-api-management.md
@@ -0,0 +1,46 @@
+---
+title: "Scripts related to interacting with Azure API Management"
+layout: default
+---
+
+# Azure API Management
+
+## Installation
+
+To have access to the following features, you have to import the module:
+
+```powershell
+PS> Import-Module -Name Arcus.Scripting.ApiManagement
+```
+
+## Create a new API operation on the API Management service
+
+Create an operation on an existing API in Azure API Management.
+
+| Parameter           | Mandatory | Description                                                                                              |
+| ------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
+| `ResourceGroupName` | yes       | The resource group containing the API Management service                                                 |
+| `ServiceName`       | yes       | The name of the API Management service located in Azure                                                  |
+| `ApiId`             | yes       | The ID to identify the API running in API Management                                                     |
+| `OperationId`       | yes       | The ID to identify the to-be-created operation on the API                                                |
+| `Method`            | yes	      | The method of the to-be-created operation on the API                                                     |
+| `UrlTemplate`       | yes       | The URL-template, or endpoint-URL, of the to-be-created operation on the API                                        |
+| `OperationName`     | no        | The optional descriptive name to give to the to-be-created operation on the API (default: `OperationId`) |
+| `Description`       | no        | The optional explanation to describe the to-be-created operation on the API                             |
+| `PolicyFilePath`    | no        | The path to the file containing the optional policy of the to-be-created operation on the API            |
+
+**Example**
+
+Creates a new API operation on the API Management service with using the default base operation policy.
+
+```powershell
+PS> Create-AzApiManagementApiOperation -ResourceGroup $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -Method $Method -UrlTemplate $UrlTemplate
+# New API operation '$OperationName' on API Management service was added.
+```
+
+Creates a new API operation on the API Management service with using a specific operation policy.
+
+```powershell
+PS> Create-AzApiManagementApiOperation -ResourceGroup $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -Method $Method -UrlTemplate $UrlTemplate -OperationName $OperationName -Description $Description -PolicyFilePath $PolicyFilePath
+# New API operation '$OperationName' on API Management service was added.
+```	
diff --git a/docs/preview/index.md b/docs/preview/index.md
@@ -20,6 +20,7 @@ For more granular packages we recommend reading the documentation.
 
 * Automate Azure Data Factory tasks ([powershell](featues/powershell/azure-data-factory))
 * Automate Azure Key Vault tasks ([powershell](features/powershell/azure-key-vault))
+* Automate Azure API Management tasks ([powershell](features/powershell/azure-api-management))
 
 # License
 This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.

diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psd1 b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psd1
diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1
@@ -1,6 +1,50 @@
 <#
-	My Function
+ .Synopsis
+  Create an operation on an API in Azure API Management.
+
+ .Description
+  Create an operation on an existing API in Azure API Management.
+
+ .Parameter ServiceName
+  The name of the API Management service located in Azure.
+
+ .Parameter ResourceGroupName
+  The resource group containing the API Management service.
+
+ .Parameter ApiId
+  The ID to identify the API running in API Management.
+
+ .Parameter OperationId
+  The ID to identify the to-be-created operation on the API.
+
+ .Parameter Method
+  The method of the to-be-created operation on the API.
+
+ .Parameter UrlTemplate
+  The URL-template, or endpoint-URL, of the to-be-created operation on the API.
+
+ .Parameter OperationName
+  The optional descriptive name to give to the to-be-created operation on the API.
+
+ .Parameter Description
+  The optional explanation to describe the to-be-created operation on the API.
+
+ .Parameter PolicyFilePath
+  The path to the file containing the optional policy of the to-be-created operation on the API.
 #>
-function Get-Function {
+function Create-AzApiManagementApiOperation {
+	param(
+        [string][Parameter(Mandatory = $true)] $ResourceGroup = $(throw "Resource group is required"),
+        [string][Parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"),
+        [string][Parameter(Mandatory = $true)] $ApiId = $(throw "API ID is required"),
+        [string][Parameter(Mandatory = $true)] $OperationId = $(throw "Operation ID is required"),
+        [string][Parameter(Mandatory = $true)] $Method = $(throw "Method is required"),
+        [string][Parameter(Mandatory = $true)] $UrlTemplate = $(throw "URL template is required"),
+        [string][Parameter(Mandatory = $false)] $OperationName = $OperationId,
+        [string][Parameter(Mandatory = $false)] $Description = "",
+        [string][Parameter(Mandatory = $false)] $PolicyFilePath = ""
+	)
+	. $PSScriptRoot\Scripts\Create-AzApiManagementApiOperation.ps1 -ResourceGroup $ResourceGroup -ServiceName $ServiceName -ApiId $ApiId -OperationId $OperationId -Method $Method -UrlTemplate $UrlTemplate -OperationName $OperationName -Description $Description -PolicyFilePath $PolicyFilePath
+}
 
-}
+Export-ModuleMember -Function Create-AzApiManagementApiOperation
diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj
@@ -25,10 +25,13 @@
     <ErrorReport>prompt</ErrorReport>
     <WarningLevel>4</WarningLevel>
   </PropertyGroup>
-  <ItemGroup />
+  <ItemGroup>
+    <Folder Include="Scripts\" />
+  </ItemGroup>
   <ItemGroup>
     <Compile Include="Arcus.Scripting.ApiManagement.psd1" />
     <Compile Include="Arcus.Scripting.ApiManagement.psm1" />
+    <Compile Include="Scripts\Create-AzApiManagementApiOperation.ps1" />
   </ItemGroup>
   <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
   <Target Name="Build" />

diff --git a/src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementApiOperation.ps1 b/src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementApiOperation.ps1
@@ -0,0 +1,29 @@
+param(
+   [string][Parameter(Mandatory = $true)] $ResourceGroup = $(throw "Resource group is required"),
+   [string][Parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"),
+   [string][Parameter(Mandatory = $true)] $ApiId = $(throw "API ID is required"),
+   [string][Parameter(Mandatory = $true)] $OperationId = $(throw "Operation ID is required"),
+   [string][Parameter(Mandatory = $true)] $Method = $(throw "Method is required"),
+   [string][Parameter(Mandatory = $true)] $UrlTemplate = $(throw "URL template is required"),
+   [string][Parameter(Mandatory = $false)] $OperationName = $OperationId,
+   [string][Parameter(Mandatory = $false)] $Description = "",
+   [string][Parameter(Mandatory = $false)] $PolicyFilePath = ""
+)
+
+# Retrieve the context of APIM
+$apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroup -ServiceName $ServiceName
+
+# Create a new operation on the previously created API
+New-AzApiManagementOperation -Context $apimContext -ApiId $ApiId -OperationId $OperationId -Name $OperationName -Method $Method -UrlTemplate $UrlTemplate -Description $Description
+Write-Host "New API operation '$OperationName' on API Management service was added."
+
+# Check if a policy-file has been specified, if not - the base policy is assigned by default
+if($OperationId -eq "" -or $PolicyFilePath -eq "")
+{
+    Write-Host "No policy has been defined."
+}
+else
+{
+    Write-Host "Updating policy of the operation '$OperationId' in API '$ApiId'"
+    Set-AzApiManagementPolicy -Context $apimContext -ApiId $ApiId -OperationId $OperationId -PolicyFilePath $PolicyFilePath
+}
diff --git a/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1 b/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1
@@ -0,0 +1,78 @@
+using module Az
+Import-Module -Name $PSScriptRoot\..\Arcus.Scripting.ApiManagement -DisableNameChecking
+
+Describe "Arcus" {
+	Context "ApiManagement" {
+		InModuleScope Arcus.Scripting.ApiManagement {
+			It "Calls new operation on API Management operation w/o policy" {
+				# Arrange
+				$resourceGroup = "shopping"
+				$serviceName = "shopping-API-management"
+				$apiId = "shopping-API"
+				$operationId = "orders"
+				$method = "POST"
+				$urlTemplate = "https://{host}.com/{path}{query}"
+				$context = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.ServiceManagement.Models.PsApiManagementContext
+
+				Mock New-AzApiManagementContext {
+					$ResourceGroup | Should -Be $resourceGroup
+					$ServiceName | Should -Be $serviceName
+					return $context } -Verifiable
+				Mock New-AzApiManagementOperation {
+					$Context | Should -Be $context
+					$ApiId | Should -Be $apiId
+					$OperationId | Should -Be $operationId
+					$Method | Should -Be $method
+					$UrlTemplate | Should -Be $urlTemplate } -Verifiable
+				Mock Set-AzApiManagementPolicy { }
+
+				# Act
+				Create-AzApiManagementApiOperation -ResourceGroup $resourceGroup -ServiceName $serviceName -ApiId $apiId -OperationId $operationId -Method $method -UrlTemplate $urlTemplate
+
+				# Assert
+				Assert-VerifiableMock
+				Assert-MockCalled New-AzApiManagementContext -Times 1
+				Assert-MockCalled New-AzApiManagementOperation -Times 1
+				Assert-MockCalled Set-AzApiManagementPolicy -Times 0
+			}
+			It "Calls new operation on API management operation w/ policy" {
+				# Arrange
+				$resourceGroup = "shopping"
+				$serviceName = "shopping-API-management"
+				$apiId = "shopping-API"
+				$operationId = "orders"
+				$method = "POST"
+				$urlTemplate = "https://{host}.com/{path}{query}"
+				$operationName = "POSTing orders"
+				$description = "API that can process posted orders"
+				$policyFilePath = "/file-path/operation-policy"
+				$context = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.ServiceManagement.Models.PsApiManagementContext
+
+				Mock New-AzApiManagementContext {
+					$ResourceGroup | Should -Be $resourceGroup
+					$ServiceName | Should -Be $serviceName
+					return $context } -Verifiable
+				Mock New-AzApiManagementOperation {
+					$Context | Should -Be $context
+					$ApiId | Should -Be $apiId
+					$OperationId | Should -Be $operationId
+					$Method | Should -Be $method
+					$UrlTemplate | Should -Be $urlTemplate
+					$Description | Should -Be $description } -Verifiable
+				Mock Set-AzApiManagementPolicy {
+					$ApiId | Should -Be $apiId
+					$OperationId | Should -Be $operationId
+					$PolicyFilePath | Should -Be $policyFilePath } -Verifiable
+
+				# Act
+				Create-AzApiManagementApiOperation -ResourceGroup $resourceGroup -ServiceName $serviceName -ApiId $apiId -OperationId $operationId -Method $method -UrlTemplate $urlTemplate -OperationName $operationName -Description $Description -PolicyFilePath $policyFilePath
+
+				# Assert
+				Assert-VerifiableMock
+				Assert-MockCalled New-AzApiManagementContext -Times 1
+				Assert-MockCalled New-AzApiManagementOperation -Times 1
+				Assert-MockCalled Set-AzApiManagementPolicy -Times 1
+			}
+		}
+	}
+}
diff --git a/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.Tests.Unit.pssproj b/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.Tests.Unit.pssproj
@@ -51,6 +51,7 @@
     </ProjectReference>
   </ItemGroup>
   <ItemGroup>
+    <Compile Include="Arcus.Scripting.ApiManagement.tests.ps1" />
     <Compile Include="Arcus.Scripting.DataFactory.tests.ps1" />
     <Compile Include="Arcus.Scripting.KeyVault.tests.ps1" />
     <Compile Include="Arcus.Scripting.DevOps.tests.ps1" />