Api Management Service - Apply Network Configuration Updates

Updates the Microsoft.ApiManagement resource running in the Virtual network to pick the updated DNS changes.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/applynetworkconfigurationupdates?api-version=2021-08-01

URI Parameters

Name In Required Type Description
resourceGroupName
path True
  • string

The name of the resource group.

serviceName
path True
  • string

The name of the API Management service.

Regex pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$

subscriptionId
path True
  • string

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

api-version
query True
  • string

Version of the API to be used with the client request.

Request Body

Name Type Description
location
  • string

Location of the Api Management service to update for a multi-region service. For a service deployed in a single region, this parameter is not required.

Responses

Name Type Description
200 OK

Network configuration updates were successfully applied on the Api Management service.

202 Accepted

Accepted: Location header contains the URL where the status of the long running operation can be checked.

Other Status Codes

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

ApiManagementApplyNetworkConfigurationUpdates

Sample Request

POST https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/applynetworkconfigurationupdates?api-version=2021-08-01

{
  "location": "west us"
}

Sample Response

location: https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/operationresults/dGVjaGVkX01hbmFnZVJvbGVfNWRiNGI3Ng==?api-version=2021-08-01
{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1",
  "name": "apimService1",
  "type": "Microsoft.ApiManagement/service",
  "tags": {
    "UID": "52ed5986-717b-45b4-b17c-3df8db372cff"
  },
  "location": "East Asia",
  "etag": "AAAAAAAXX6Y=",
  "properties": {
    "publisherEmail": "admin@live.com",
    "publisherName": "Contoso",
    "provisioningState": "Succeeded",
    "targetProvisioningState": "",
    "createdAtUtc": "2015-09-22T01:50:34.7921566Z",
    "gatewayUrl": "https://apimService1.azure-api.net",
    "portalUrl": "https://apimService1.portal.azure-api.net",
    "managementApiUrl": "https://apimService1.management.azure-api.net",
    "scmUrl": "https://apimService1.scm.azure-api.net",
    "hostnameConfigurations": [],
    "publicIPAddresses": [
      "207.46.155.24"
    ],
    "virtualNetworkConfiguration": {
      "subnetResourceId": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/virtualNetworks/eastUsVirtualNetwork/subnets/apimSubnet"
    },
    "virtualNetworkType": "External"
  },
  "sku": {
    "name": "Premium",
    "capacity": 1
  }
}

Definitions

AdditionalLocation

Description of an additional API Management resource location.

ApiManagementServiceApplyNetworkConfigurationParameters

Parameter supplied to the Apply Network configuration operation.

ApiManagementServiceIdentity

Identity properties of the Api Management service resource.

ApiManagementServiceResource

A single API Management service resource in List or Get response.

ApiManagementServiceSkuProperties

API Management service resource SKU properties.

ApimIdentityType

The type of identity used for the resource. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user assigned identities. The type 'None' will remove any identities from the service.

ApiVersionConstraint

Control Plane Apis version constraint for the API Management service.

ArmIdWrapper

A wrapper for an ARM resource id

CertificateConfiguration

Certificate configuration which consist of non-trusted intermediates and root certificates.

CertificateInformation

SSL certificate information.

CertificateSource

Certificate Source.

CertificateStatus

Certificate Status.

createdByType

The type of identity that created the resource.

ErrorFieldContract

Error Field contract.

ErrorResponse

Error Response.

HostnameConfiguration

Custom hostname configuration.

HostnameType

Hostname type.

PlatformVersion

Compute Platform Version running the service.

PrivateEndpointServiceConnectionStatus

The private endpoint connection status.

PrivateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

PublicNetworkAccess

Whether or not public endpoint access is allowed for this API Management service. Value is optional but if passed in, must be 'Enabled' or 'Disabled'. If 'Disabled', private endpoints are the exclusive access method. Default value is 'Enabled'

RemotePrivateEndpointConnectionWrapper

Remote Private Endpoint Connection resource.

SkuType

Name of the Sku.

systemData

Metadata pertaining to creation and last modification of the resource.

UserIdentityProperties
VirtualNetworkConfiguration

Configuration of a virtual network to which API Management service is deployed.

VirtualNetworkType

The type of VPN in which API Management service needs to be configured in. None (Default Value) means the API Management service is not part of any Virtual Network, External means the API Management deployment is set up inside a Virtual Network having an Internet Facing Endpoint, and Internal means that API Management deployment is setup inside a Virtual Network having an Intranet Facing Endpoint only.

AdditionalLocation

Description of an additional API Management resource location.

Name Type Default Value Description
disableGateway
  • boolean
False

Property only valid for an Api Management service deployed in multiple locations. This can be used to disable the gateway in this additional location.

gatewayRegionalUrl
  • string

Gateway URL of the API Management service in the Region.

location
  • string

The location name of the additional region among Azure Data center regions.

platformVersion

Compute Platform Version running the service.

privateIPAddresses
  • string[]

Private Static Load Balanced IP addresses of the API Management service which is deployed in an Internal Virtual Network in a particular additional location. Available only for Basic, Standard, Premium and Isolated SKU.

publicIPAddresses
  • string[]

Public Static Load Balanced IP addresses of the API Management service in the additional location. Available only for Basic, Standard, Premium and Isolated SKU.

publicIpAddressId
  • string

Public Standard SKU IP V4 based IP address to be associated with Virtual Network deployed service in the location. Supported only for Premium SKU being deployed in Virtual Network.

sku

SKU properties of the API Management service.

virtualNetworkConfiguration

Virtual network configuration for the location.

zones
  • string[]

A list of availability zones denoting where the resource needs to come from.

ApiManagementServiceApplyNetworkConfigurationParameters

Parameter supplied to the Apply Network configuration operation.

Name Type Description
location
  • string

Location of the Api Management service to update for a multi-region service. For a service deployed in a single region, this parameter is not required.

ApiManagementServiceIdentity

Identity properties of the Api Management service resource.

Name Type Description
principalId
  • string

The principal id of the identity.

tenantId
  • string

The client tenant id of the identity.

type

The type of identity used for the resource. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user assigned identities. The type 'None' will remove any identities from the service.

userAssignedIdentities

The list of user identities associated with the resource. The user identity dictionary key references will be ARM resource ids in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/ providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.

ApiManagementServiceResource

A single API Management service resource in List or Get response.

Name Type Default Value Description
etag
  • string

ETag of the resource.

id
  • string

Resource ID.

identity

Managed service identity of the Api Management service.

location
  • string

Resource location.

name
  • string

Resource name.

properties.additionalLocations

Additional datacenter locations of the API Management service.

properties.apiVersionConstraint

Control Plane Apis version constraint for the API Management service.

properties.certificates

List of Certificates that need to be installed in the API Management service. Max supported certificates that can be installed is 10.

properties.createdAtUtc
  • string

Creation UTC date of the API Management service.The date conforms to the following format: yyyy-MM-ddTHH:mm:ssZ as specified by the ISO 8601 standard.

properties.customProperties
  • object

Custom properties of the API Management service.
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.TripleDes168 will disable the cipher TLS_RSA_WITH_3DES_EDE_CBC_SHA for all TLS(1.0, 1.1 and 1.2).
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11 can be used to disable just TLS 1.1.
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10 can be used to disable TLS 1.0 on an API Management service.
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 can be used to disable just TLS 1.1 for communications with backends.
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 can be used to disable TLS 1.0 for communications with backends.
Setting Microsoft.WindowsAzure.ApiManagement.Gateway.Protocols.Server.Http2 can be used to enable HTTP2 protocol on an API Management service.
Not specifying any of these properties on PATCH operation will reset omitted properties' values to their defaults. For all the settings except Http2 the default value is True if the service was created on or before April 1st 2018 and False otherwise. Http2 setting's default value is False.

You can disable any of next ciphers by using settings Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.[cipher_name]: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA. For example, Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.TLS_RSA_WITH_AES_128_CBC_SHA256:false. The default value is true for them. Note: next ciphers can't be disabled since they are required by Azure CloudService internal components: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384

properties.developerPortalUrl
  • string

DEveloper Portal endpoint URL of the API Management service.

properties.disableGateway
  • boolean
False

Property only valid for an Api Management service deployed in multiple locations. This can be used to disable the gateway in master region.

properties.enableClientCertificate
  • boolean
False

Property only meant to be used for Consumption SKU Service. This enforces a client certificate to be presented on each request to the gateway. This also enables the ability to authenticate the certificate in the policy on the gateway.

properties.gatewayRegionalUrl
  • string

Gateway URL of the API Management service in the Default Region.

properties.gatewayUrl
  • string

Gateway URL of the API Management service.

properties.hostnameConfigurations

Custom hostname configuration of the API Management service.

properties.managementApiUrl
  • string

Management API endpoint URL of the API Management service.

properties.notificationSenderEmail
  • string

Email address from which the notification will be sent.

properties.platformVersion

Compute Platform Version running the service in this location.

properties.portalUrl
  • string

Publisher portal endpoint Url of the API Management service.

properties.privateEndpointConnections

List of Private Endpoint Connections of this service.

properties.privateIPAddresses
  • string[]

Private Static Load Balanced IP addresses of the API Management service in Primary region which is deployed in an Internal Virtual Network. Available only for Basic, Standard, Premium and Isolated SKU.

properties.provisioningState
  • string

The current provisioning state of the API Management service which can be one of the following: Created/Activating/Succeeded/Updating/Failed/Stopped/Terminating/TerminationFailed/Deleted.

properties.publicIPAddresses
  • string[]

Public Static Load Balanced IP addresses of the API Management service in Primary region. Available only for Basic, Standard, Premium and Isolated SKU.

properties.publicIpAddressId
  • string

Public Standard SKU IP V4 based IP address to be associated with Virtual Network deployed service in the region. Supported only for Developer and Premium SKU being deployed in Virtual Network.

properties.publicNetworkAccess

Whether or not public endpoint access is allowed for this API Management service. Value is optional but if passed in, must be 'Enabled' or 'Disabled'. If 'Disabled', private endpoints are the exclusive access method. Default value is 'Enabled'

properties.publisherEmail
  • string

Publisher email.

properties.publisherName
  • string

Publisher name.

properties.restore
  • boolean
False

Undelete Api Management Service if it was previously soft-deleted. If this flag is specified and set to True all other properties will be ignored.

properties.scmUrl
  • string

SCM endpoint URL of the API Management service.

properties.targetProvisioningState
  • string

The provisioning state of the API Management service, which is targeted by the long running operation started on the service.

properties.virtualNetworkConfiguration

Virtual network configuration of the API Management service.

properties.virtualNetworkType None

The type of VPN in which API Management service needs to be configured in. None (Default Value) means the API Management service is not part of any Virtual Network, External means the API Management deployment is set up inside a Virtual Network having an Internet Facing Endpoint, and Internal means that API Management deployment is setup inside a Virtual Network having an Intranet Facing Endpoint only.

sku

SKU properties of the API Management service.

systemData

Metadata pertaining to creation and last modification of the resource.

tags
  • object

Resource tags.

type
  • string

Resource type for API Management resource is set to Microsoft.ApiManagement.

zones
  • string[]

A list of availability zones denoting where the resource needs to come from.

ApiManagementServiceSkuProperties

API Management service resource SKU properties.

Name Type Description
capacity
  • integer

Capacity of the SKU (number of deployed units of the SKU). For Consumption SKU capacity must be specified as 0.

name

Name of the Sku.

ApimIdentityType

The type of identity used for the resource. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user assigned identities. The type 'None' will remove any identities from the service.

Name Type Description
None
  • string
SystemAssigned
  • string
SystemAssigned, UserAssigned
  • string
UserAssigned
  • string

ApiVersionConstraint

Control Plane Apis version constraint for the API Management service.

Name Type Description
minApiVersion
  • string

Limit control plane API calls to API Management service with version equal to or newer than this value.

ArmIdWrapper

A wrapper for an ARM resource id

Name Type Description
id
  • string

CertificateConfiguration

Certificate configuration which consist of non-trusted intermediates and root certificates.

Name Type Description
certificate

Certificate information.

certificatePassword
  • string

Certificate Password.

encodedCertificate
  • string

Base64 Encoded certificate.

storeName enum:
  • CertificateAuthority
  • Root

The System.Security.Cryptography.x509certificates.StoreName certificate store location. Only Root and CertificateAuthority are valid locations.

CertificateInformation

SSL certificate information.

Name Type Description
expiry
  • string

Expiration date of the certificate. The date conforms to the following format: yyyy-MM-ddTHH:mm:ssZ as specified by the ISO 8601 standard.

subject
  • string

Subject of the certificate.

thumbprint
  • string

Thumbprint of the certificate.

CertificateSource

Certificate Source.

Name Type Description
BuiltIn
  • string
Custom
  • string
KeyVault
  • string
Managed
  • string

CertificateStatus

Certificate Status.

Name Type Description
Completed
  • string
Failed
  • string
InProgress
  • string

createdByType

The type of identity that created the resource.

Name Type Description
Application
  • string
Key
  • string
ManagedIdentity
  • string
User
  • string

ErrorFieldContract

Error Field contract.

Name Type Description
code
  • string

Property level error code.

message
  • string

Human-readable representation of property-level error.

target
  • string

Property name.

ErrorResponse

Error Response.

Name Type Description
error.code
  • string

Service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.

error.details

The list of invalid fields send in request, in case of validation error.

error.message
  • string

Human-readable representation of the error.

HostnameConfiguration

Custom hostname configuration.

Name Type Default Value Description
certificate

Certificate information.

certificatePassword
  • string

Certificate Password.

certificateSource

Certificate Source.

certificateStatus

Certificate Status.

defaultSslBinding
  • boolean
False

Specify true to setup the certificate associated with this Hostname as the Default SSL Certificate. If a client does not send the SNI header, then this will be the certificate that will be challenged. The property is useful if a service has multiple custom hostname enabled and it needs to decide on the default ssl certificate. The setting only applied to Proxy Hostname Type.

encodedCertificate
  • string

Base64 Encoded certificate.

hostName
  • string

Hostname to configure on the Api Management service.

identityClientId
  • string

System or User Assigned Managed identity clientId as generated by Azure AD, which has GET access to the keyVault containing the SSL certificate.

keyVaultId
  • string

Url to the KeyVault Secret containing the Ssl Certificate. If absolute Url containing version is provided, auto-update of ssl certificate will not work. This requires Api Management service to be configured with aka.ms/apimmsi. The secret should be of type application/x-pkcs12

negotiateClientCertificate
  • boolean
False

Specify true to always negotiate client certificate on the hostname. Default Value is false.

type

Hostname type.

HostnameType

Hostname type.

Name Type Description
DeveloperPortal
  • string
Management
  • string
Portal
  • string
Proxy
  • string
Scm
  • string

PlatformVersion

Compute Platform Version running the service.

Name Type Description
mtv1
  • string

Platform running the service on Multi Tenant V1 platform.

stv1
  • string

Platform running the service on Single Tenant V1 platform.

stv2
  • string

Platform running the service on Single Tenant V2 platform.

undetermined
  • string

Platform version cannot be determined, as compute platform is not deployed.

PrivateEndpointServiceConnectionStatus

The private endpoint connection status.

Name Type Description
Approved
  • string
Pending
  • string
Rejected
  • string

PrivateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

Name Type Description
actionsRequired
  • string

A message indicating if changes on the service provider require any updates on the consumer.

description
  • string

The reason for approval/rejection of the connection.

status

Indicates whether the connection has been Approved/Rejected/Removed by the owner of the service.

PublicNetworkAccess

Whether or not public endpoint access is allowed for this API Management service. Value is optional but if passed in, must be 'Enabled' or 'Disabled'. If 'Disabled', private endpoints are the exclusive access method. Default value is 'Enabled'

Name Type Description
Disabled
  • string
Enabled
  • string

RemotePrivateEndpointConnectionWrapper

Remote Private Endpoint Connection resource.

Name Type Description
id
  • string

Private Endpoint connection resource id

name
  • string

Private Endpoint Connection Name

properties.groupIds
  • string[]

All the Group ids.

properties.privateEndpoint

The resource of private end point.

properties.privateLinkServiceConnectionState

A collection of information about the state of the connection between service consumer and provider.

properties.provisioningState
  • string

The provisioning state of the private endpoint connection resource.

type
  • string

Private Endpoint Connection Resource Type

SkuType

Name of the Sku.

Name Type Description
Basic
  • string

Basic SKU of Api Management.

Consumption
  • string

Consumption SKU of Api Management.

Developer
  • string

Developer SKU of Api Management.

Isolated
  • string

Isolated SKU of Api Management.

Premium
  • string

Premium SKU of Api Management.

Standard
  • string

Standard SKU of Api Management.

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt
  • string

The timestamp of resource creation (UTC).

createdBy
  • string

The identity that created the resource.

createdByType

The type of identity that created the resource.

lastModifiedAt
  • string

The timestamp of resource last modification (UTC)

lastModifiedBy
  • string

The identity that last modified the resource.

lastModifiedByType

The type of identity that last modified the resource.

UserIdentityProperties

Name Type Description
clientId
  • string

The client id of user assigned identity.

principalId
  • string

The principal id of user assigned identity.

VirtualNetworkConfiguration

Configuration of a virtual network to which API Management service is deployed.

Name Type Description
subnetResourceId
  • string

The full resource ID of a subnet in a virtual network to deploy the API Management service in.

subnetname
  • string

The name of the subnet.

vnetid
  • string

The virtual network ID. This is typically a GUID. Expect a null GUID by default.

VirtualNetworkType

The type of VPN in which API Management service needs to be configured in. None (Default Value) means the API Management service is not part of any Virtual Network, External means the API Management deployment is set up inside a Virtual Network having an Internet Facing Endpoint, and Internal means that API Management deployment is setup inside a Virtual Network having an Intranet Facing Endpoint only.

Name Type Description
External
  • string

The service is part of Virtual Network and it is accessible from Internet.

Internal
  • string

The service is part of Virtual Network and it is only accessible from within the virtual network.

None
  • string

The service is not part of any Virtual Network.