Azure Compute Virtual Machines API

This document provides comprehensive details on the Azure Compute Virtual Machines API. This API allows you to programmatically manage virtual machines within your Azure environment.

Overview

The Azure Virtual Machines API enables you to perform a wide range of operations on your virtual machines, including creation, configuration, deployment, and management. It's a critical component for automating infrastructure tasks and building scalable cloud solutions.

Key features include:

Core Operations

List Virtual Machines

GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines

Retrieves a list of all virtual machines within a specified resource group. You can filter the results by resource group or subscription.

Parameters:

subscriptionId (string, required): The Azure subscription ID.

resourceGroupName (string, required): The name of the resource group.

GET https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01

Get Virtual Machine Details

GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}

Retrieves the details of a specific virtual machine.

Parameters:

subscriptionId (string, required): The Azure subscription ID.

resourceGroupName (string, required): The name of the resource group.

vmName (string, required): The name of the virtual machine.

GET https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME?api-version=2023-07-01

Create or Update Virtual Machine

PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}

Creates a new virtual machine or updates an existing one. This is a complex operation that requires a detailed JSON payload defining the VM's configuration.

Parameters:

subscriptionId (string, required): The Azure subscription ID.

resourceGroupName (string, required): The name of the resource group.

vmName (string, required): The name of the virtual machine.

Request Body Example (Simplified):


{
  "location": "eastus",
  "properties": {
    "hardwareProfile": {
      "vmSize": "Standard_DS2_v2"
    },
    "osProfile": {
      "computerName": "myVM",
      "adminUsername": "azureuser",
      "adminPassword": "YOUR_STRONG_PASSWORD"
    },
    "storageProfile": {
      "imageReference": {
        "publisher": "MicrosoftWindowsServer",
        "offer": "WindowsServer",
        "sku": "2019-Datacenter",
        "version": "latest"
      },
      "osDisk": {
        "createOption": "FromImage",
        "managedDisk": {
          "storageAccountType": "Standard_LRS"
        }
      }
    },
    "networkProfile": {
      "networkInterfaces": [
        {
          "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Network/networkInterfaces/YOUR_NIC_NAME",
          "properties": {
            "primary": true
          }
        }
      ]
    }
  }
}
            

PUT https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME?api-version=2023-07-01
Content-Type: application/json
{
  "location": "eastus",
  "properties": {
    "hardwareProfile": { "vmSize": "Standard_DS2_v2" },
    "osProfile": {
      "computerName": "myVM",
      "adminUsername": "azureuser",
      "adminPassword": "YOUR_STRONG_PASSWORD"
    },
    "storageProfile": {
      "imageReference": {
        "publisher": "MicrosoftWindowsServer",
        "offer": "WindowsServer",
        "sku": "2019-Datacenter",
        "version": "latest"
      },
      "osDisk": {
        "createOption": "FromImage",
        "managedDisk": { "storageAccountType": "Standard_LRS" }
      }
    },
    "networkProfile": {
      "networkInterfaces": [
        {
          "id": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Network/networkInterfaces/YOUR_NIC_NAME",
          "properties": { "primary": true }
        }
      ]
    }
  }
}

Delete Virtual Machine

DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}

Deletes a virtual machine. This operation will also delete associated OS disks unless they are configured to be retained.

Parameters:

subscriptionId (string, required): The Azure subscription ID.

resourceGroupName (string, required): The name of the resource group.

vmName (string, required): The name of the virtual machine.

DELETE https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME?api-version=2023-07-01

Advanced Operations

Start Virtual Machine

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/start

Starts a stopped virtual machine.

POST https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME/start?api-version=2023-07-01

Stop Virtual Machine

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/powerOff

Stops a running virtual machine. You can optionally deallocate the VM to release compute resources.

Query Parameters:

deallocate (boolean, optional): If true, the VM will be deallocated.

POST https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME/powerOff?api-version=2023-07-01&deallocate=true

Restart Virtual Machine

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/restart

Restarts a virtual machine.

POST https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME/restart?api-version=2023-07-01

Managing Disks

Attach Data Disk

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/attachDataDisk

Attaches an existing managed disk as a data disk to a virtual machine.

Request Body Example:


{
  "lun": 0,
  "managedDiskId": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/disks/YOUR_DISK_NAME"
}
                

POST https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME/attachDataDisk?api-version=2023-07-01
Content-Type: application/json
{
  "lun": 0,
  "managedDiskId": "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/disks/YOUR_DISK_NAME"
}

Detach Data Disk

POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/detachDataDisk

Detaches a data disk from a virtual machine. Note that the disk itself is not deleted.

Request Body Example:


{
  "lun": 0
}
                

POST https://management.azure.com/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/YOUR_RESOURCE_GROUP/providers/Microsoft.Compute/virtualMachines/YOUR_VM_NAME/detachDataDisk?api-version=2023-07-01
Content-Type: application/json
{
  "lun": 0
}

API Versioning

The Azure Compute Virtual Machines API is versioned to allow for backward compatibility and gradual introduction of new features. Always specify the desired api-version in your requests.

Current stable version: 2023-07-01

Refer to the official Azure Compute REST API documentation for the most up-to-date information on API versions and capabilities.