Skip to main content
Version: Next

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).

ParameterMandatoryDescription
ResourceGroupNameyesThe name of the of resource group under which the API Management deployment exists.
StorageAccountResourceGroupNameyesThe name of the resource group under which the storage account exists.
StorageAccountNameyesThe name of the Storage account for which this cmdlet gets keys.
ServiceNameyesThe name of the API Management deployment that this cmdlet backs up.
ContainerNameyesThe name of the container of the blob for the backup. If the container does not exist, this cmdlet creates it.
BlobNamenoThe 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.
PassThrunoIndicates that this cmdlet returns the backed up PsApiManagement object, if the operation succeeds.
DefaultProfilenoThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
ApiIdyesThe ID to identify the API running in Azure API Management
OperationIdyesThe ID to identify the to-be-created operation on the API
MethodyesThe method of the to-be-created operation on the API
UrlTemplateyesThe URL-template, or endpoint-URL, of the to-be-created operation on the API
OperationNamenoThe optional descriptive name to give to the to-be-created operation on the API (default: OperationId)
DescriptionnoThe optional explanation to describe the to-be-created operation on the API
PolicyFilePathnoThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
FirstNameyesThe first name of the user that is to be created
LastNameyesThe last name of the user that is to be created
MailAddressyesThe email address of the user that is to be created
UserIdnoThe UserId that will be used to create the user
PasswordnoThe password that the user will be able to login with
NotenoA note that will be added to the user
SendNotificationnoWether or not a notification will be sent to the email address of the user
ConfirmationTypenoThe confirmation type that will be used when creating the user, this can be invite (default) or signup
ApiVersionnoThe version of the management API to be used. (default: 2021-08-01)
SubscriptionIdnoThe Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
AccessTokennoThe 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'

Applying user configuration to an Azure API Management service from a configuration file

Apply user configuration to an existing Azure API Management instance. You can create or update users and assign groups and/or subscriptions to these users.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
ConfigurationFileyesPath to the JSON Configuration file containing the user configuration
StrictlyFollowConfigurationFilenoThe switch to indicate whether the configuration file should strictly be followed, for example remove the user from groups not defined in the configuration file
ApiVersionnoThe version of the management API to be used. (default: 2021-08-01)
SubscriptionIdnoThe Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
AccessTokennoThe 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).

Configuration File

The configuration file is a simple JSON file that contains the users that need to be created or updated, the JSON file consists of an array of JSON objects.

The file needs to adhere to the following JSON schema.

Configuration File
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://scripting.arcus-azure.net/Features/powershell/azure-api-management/config.json",
"type": "array",
"title": "The configuration JSON schema",
"$defs": {},
"prefixItems": [{
"type": "object",
"additionalProperties": false,
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"userId": {
"type": "string"
},
"mailAddress": {
"type": "string"
},
"sendNotification": {
"type": "boolean"
},
"confirmationType": {
"type": "string",
"enum": ["signup", "invite"]
},
"note": {
"type": "string"
},
"groups": {
"type": "array",
"prefixItems": [{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"displayName"
]
}
]
},
"subscriptions": {
"type": "array",
"prefixItems": [{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"displayName": {
"type": "string"
},
"scope": {
"type": "string"
},
"allowTracing": {
"type": "boolean"
}
},
"required": [
"id",
"displayName",
"scope",
"allowTracing"
]
}
]
}
},
"required": [
"firstName",
"lastName",
"mailAddress",
"sendNotification",
"confirmationType"
]
}
]
}
Example Configuration File
[
{
"firstName": "John",
"lastName": "Doe",
"mailAddress": "john@doe.com",
"sendNotification": true,
"confirmationType": "signup",
"note": "This is an optional note",
"groups": [
{
"id": "SomeGroupId",
"displayName": "Example Group",
"description": "This is a example group"
}
],
"subscriptions": [
{
"id": "SomeSubscriptionId",
"displayName": "Example Subscription",
"scope": "/products/starter",
"allowTracing": false
}
]
},
{
"firstName": "Jane",
"lastName": "Doe",
"mailAddress": "jane@doe.com",
"sendNotification": true,
"confirmationType": "signup",
"note": "This is an optional note",
"groups": [
{
"id": "SomeGroupId",
"displayName": "Example Group",
"description": "This is a example group"
},
{
"id": "SomeOtherGroupId",
"displayName": "Another Example Group",
"description": "This is another example group"
}
],
"subscriptions": [
{
"id": "SomeSubscriptionId",
"displayName": "Example Subscription",
"scope": "/products/starter",
"allowTracing": false
},
{
"id": "SomeSOtherubscriptionId",
"displayName": "Another Example Subscription",
"scope": "/products/starter",
"allowTracing": false
}
]
}
]

Example

Apply user configuration to an existing Azure API Management instance.

PS> Create-AzApiManagementUserAccountsFromConfig `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ConfigurationFile ".\config.json"
# User configuration has successfully been applied for user with ID 'some-id' to Azure API Management service '$ServiceName' in resource group '$ResourceGroup'

Apply user configuration to an existing Azure API Management instance and strictly adhere to the configuration file.

PS> Create-AzApiManagementUserAccountsFromConfig `
-ResourceGroupName $ResourceGroup `
-ServiceName $ServiceName `
-ConfigurationFile ".\config.json" `
-StrictlyFollowConfigurationFile
# User configuration has successfully been applied for user with ID 'some-id' to Azure API Management service '$ServiceName' in resource group '$ResourceGroup'

Removing a user from an Azure API Management service

Remove a user from an existing Azure API Management instance based on e-mail address.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
MailAddressyesThe email address of the user that is to be removed
SubscriptionIdnoThe Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
AccessTokennoThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
ProductIdyesThe ID to identify the product in Azure API Management
PolicyFilePathyesThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
ApiIdyesThe ID to identify the API running in Azure API Management
PolicyFilePathyesThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management service located in Azure
ApiIdyesThe ID to identify the API running in Azure API Management
OperationIdyesThe ID to identify the operation for which to import the policy
PolicyFilePathyesThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe name of resource group under which API Management exists.
StorageAccountResourceGroupNameyesThe name of the resource group that contains the Storage account.
StorageAccountNameyesThe name of the Storage account for which this cmdlet gets keys.
ServiceNameyesThe name of the API Management instance that will be restored with the backup.
ContainerNameyesThe name of the Azure storage backup source container.
BlobNameyesThe name of the Azure storage backup source blob.
PassThrunoReturns an object representing the item with which you are working. By default, this cmdlet does not generate any output.
DefaultProfilenoThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance located in Azure
ApiIdyesThe ID to identify the API running in Azure API Management
HeaderNamenoThe name of the header where the subscription key should be set. (default: x-api-key)
QueryParamNamenoThe 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.

ParameterMandatoryDescription
ResourceGroupNameyesThe resource group containing the Azure API Management instance
ServiceNameyesThe name of the Azure API Management instance
CertificateFilePathyesThe full file path to the location of the private certificate
CertificatePasswordyesThe 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'