Azure API Management
Installation
To have access to the following features, you have to import the module:
PS> Install-Module -Name Arcus.Scripting.ApiManagement
Backing up an API Management service
Backs up an API Management service (with built-in storage context retrieval).
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The name of the of resource group under which the API Management deployment exists. |
StorageAccountResourceGroupName | yes | The name of the resource group under which the storage account exists. |
StorageAccountName | yes | The name of the Storage account for which this cmdlet gets keys. |
ServiceName | yes | The name of the API Management deployment that this cmdlet backs up. |
ContainerName | yes | The name of the container of the blob for the backup. If the container does not exist, this cmdlet creates it. |
BlobName | no | The name of the blob for the backup. If the blob does not exist, this cmdlet creates it (default value based on pattern: {Name}-{yyyy-MM-dd-HH-mm}.apimbackup. |
PassThru | no | Indicates that this cmdlet returns the backed up PsApiManagement object, if the operation succeeds. |
DefaultProfile | no | The credentials, account, tenant, and subscription used for communication with azure. |
Example
Simplest way to back up an API Management service.
PS> Backup-AzApiManagementService `
-ResourceGroupName "my-resource-group" `
-StorageAccountResourceGroupName "my-storage-account-resource-group" `
-StorageAccountName "my-storage-account" `
-ServiceName "my-service" `
-ContainerName "my-target-blob-container"
# New Azure storage context for storage account 'my-storage-account' with storage key created!
# Azure API management service 'my-service' in resource group 'my-resource-group' is backed-up!
Creating a new API operation in the Azure API Management instance
Create an operation on an existing API in Azure API Management.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
ApiId | yes | The ID to identify the API running in Azure 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 Azure API Management instance with using the default base operation policy.
PS> Create-AzApiManagementApiOperation `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId `
-OperationId $OperationId `
-Method $Method `
-UrlTemplate $UrlTemplate
# New API operation '$OperationName' was added on Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Creates a new API operation on the Azure API Management instance with using a specific operation policy.
PS> Create-AzApiManagementApiOperation `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId `
-OperationId $OperationId `
-Method $Method `
-UrlTemplate $UrlTemplate `
-OperationName $OperationName `
-Description $Description `
-PolicyFilePath $PolicyFilePath
# New API operation '$OperationName' was added on Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
# Updated policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Creating a new user in an Azure API Management service
Sign-up or invite a new user in an existing Azure API Management instance.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
FirstName | yes | The first name of the user that is to be created |
LastName | yes | The last name of the user that is to be created |
MailAddress | yes | The email address of the user that is to be created |
UserId | no | The UserId that will be used to create the user |
Password | no | The password that the user will be able to login with |
Note | no | A note that will be added to the user |
SendNotification | no | Wether or not a notification will be sent to the email address of the user |
ConfirmationType | no | The confirmation type that will be used when creating the user, this can be invite (default) or signup |
ApiVersion | no | The version of the management API to be used. (default: 2021-08-01) |
SubscriptionId | no | The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). |
AccessToken | no | The access token to be used to add the user to the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). |
Example
Invite a new user in an existing Azure API Management instance.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress
# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Invite a new user in an existing Azure API Management instance and specify a UserId.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress `
-UserId $UserId
# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Invite a new user in an existing Azure API Management instance and include a note.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress `
-Note $Note
# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Invite a new user in an existing Azure API Management instance and send a notification.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress `
-SendNotification
# Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Signup a new user in an existing Azure API Management instance.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress `
-ConfirmationType signup
# Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
# Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in
Signup a new user in an existing Azure API Management instance and specify a password.
PS> Create-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-FirstName $FirstName `
-LastName $LastName `
-MailAddress $MailAddress `
-Password $Password `
-ConfirmationType signup
# Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Removing a user from an Azure API Management service
Remove a user from an existing Azure API Management instance based on e-mail address.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
MailAddress | yes | The email address of the user that is to be removed |
SubscriptionId | no | The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). |
AccessToken | no | The access token to be used to add the user to the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). |
Example
Remove a user from an existing Azure API Management instance.
PS> Remove-AzApiManagementUserAccount `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-MailAddress $MailAddress
# Removed the user account with e-mail '$MailAddress' and ID '1' for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Importing a policy to a product in the Azure API Management instance
Imports a policy from a file to a product in Azure API Management.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
ProductId | yes | The ID to identify the product in Azure API Management |
PolicyFilePath | yes | The path to the file containing the to-be-imported policy |
PS> Import-AzApiManagementProductPolicy `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ProductId $ProductId `
-PolicyFilePath $PolicyFilePath
# Successfully updated the product policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName
Importing a policy to an API in the Azure API Management instance
Imports a base-policy from a file to an API in Azure API Management.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
ApiId | yes | The ID to identify the API running in Azure API Management |
PolicyFilePath | yes | The path to the file containing the to-be-imported policy |
PS> Import-AzApiManagementApiPolicy `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId `
-PolicyFilePath $PolicyFilePath
# Successfully updated API policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Importing a policy to an operation in the Azure API Management instance
Imports a policy from a file to an API operation in Azure API Management.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management service located in Azure |
ApiId | yes | The ID to identify the API running in Azure API Management |
OperationId | yes | The ID to identify the operation for which to import the policy |
PolicyFilePath | yes | The path to the file containing the to-be-imported policy |
PS> Import-AzApiManagementOperationPolicy `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId `
-OperationId $OperationId `
-PolicyFilePath $PolicyFilePath
# USuccessfully updated the operation policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName
Removing all Azure API Management defaults from the instance
Remove all default API's and products from the Azure API Management instance ('echo-api' API, 'starter' & 'unlimited' products), including the subscriptions.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
PS> Remove-AzApiManagementDefaults `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName
# Removed 'echo' API in the Azure API Management service $ServiceName in resource group $ResourceGroupName
# Removed 'starter' product in the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
# Removed 'unlimited' product in the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Restoring an API Management service
The Restore-AzApiManagement cmdlet restores an API Management Service from the specified backup residing in an Azure Storage blob.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The name of resource group under which API Management exists. |
StorageAccountResourceGroupName | yes | The name of the resource group that contains the Storage account. |
StorageAccountName | yes | The name of the Storage account for which this cmdlet gets keys. |
ServiceName | yes | The name of the API Management instance that will be restored with the backup. |
ContainerName | yes | The name of the Azure storage backup source container. |
BlobName | yes | The name of the Azure storage backup source blob. |
PassThru | no | Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. |
DefaultProfile | no | The credentials, account, tenant, and subscription used for communication with azure. |
PS> Restore-AzApiManagementService `
-ResourceGroupName $ResourceGroupName `
-$StorageAccountResourceGroupName `
-StorageAccountName $StorageAccountName `
-ServiceName $ServiceName `
-ContainerName $ContainerName `
-BlobName $BlobName
# Azure API Management service '$ServiceName' in resource group '$ResourceGroupName' is restored!
Setting authentication keys to an API in the Azure API Management instance
Sets the subscription header/query parameter name to an API in Azure API Management.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance located in Azure |
ApiId | yes | The ID to identify the API running in Azure API Management |
HeaderName | no | The name of the header where the subscription key should be set. (default: x-api-key) |
QueryParamName | no | The name of the query parameter where the subscription key should be set. (default: apiKey) |
Using default
PS> Set-AzApiManagementApiSubscriptionKey `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId
# Using API Management instance '$ServiceName' in resource group '$ResourceGroup'
# Subscription key header 'x-api-key' was assigned
# Subscription key query parameter 'apiKey' was assigned
User-defined values
PS> Set-AzApiManagementApiSubscriptionKey `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ApiId $ApiId `
-HeaderName "my-api-key" `
-QueryParamName "myApiKey"
# Subscription key header 'my-api-key' was assigned for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
# Subscription key query parameter 'myApiKey' was assigned for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
Uploading private certificates to the Azure API Management certificate store
Uploads a private certificate to the Azure API Management certificate store, allowing authentication against backend services.
| Parameter | Mandatory | Description |
|---|---|---|
ResourceGroupName | yes | The resource group containing the Azure API Management instance |
ServiceName | yes | The name of the Azure API Management instance |
CertificateFilePath | yes | The full file path to the location of the private certificate |
CertificatePassword | yes | The password for the private certificate |
Example
PS> Upload-AzApiManagementCertificate `
-ResourceGroupName "my-resource-group" `
-ServiceName "my-api-management-instance" `
-CertificateFilePath "c:\temp\certificate.pfx" `
-CertificatePassword "P@ssw0rd"
# Uploaded private certificate at 'C:\temp\certificate.pfx' for the Azure API Management service 'my-api-management-instance' in resource group 'my-resource-group'