Servizio metadati dell'istanza di Azure

  • Articolo

Si applica a: ✔️ macchine virtuali Linux ✔️ macchine virtuali Windows ✔️ set di scalabilità flessibili

Il servizio metadati dell'istanza di Azure (IMDS) fornisce informazioni sulle istanze di macchine virtuali attualmente in esecuzione. È possibile usarlo per gestire e configurare le macchine virtuali. Queste informazioni includono SKU, archiviazione, configurazioni di rete e gli eventi di manutenzione previsti. Per un elenco completo dei dati disponibili, vedere Riepilogo delle categorie di endpoint.

IMDS è disponibile per l'esecuzione di istanze di macchine virtuali e istanze del set di scalabilità. Tutti gli endpoint supportano le macchine virtuali create e gestite con Azure Resource Manager. Solo la categoria Attestaed e la parte Network della categoria Instance supportano le macchine virtuali create usando il modello di distribuzione classica. L'endpoint attestato esegue questa operazione solo in misura limitata.

IMDS è un'API REST disponibile in un indirizzo IP noto e non instradabile (169.254.169.254). È possibile accedervi solo dall'interno della macchina virtuale. La comunicazione tra la macchina virtuale e IMDS non lascia mai l'host. Fare in modo che i client HTTP ignorino i proxy Web all'interno della macchina virtuale durante l'esecuzione di query su IMDS e considerino 169.254.169.254 lo stesso valore di 168.63.129.16.

Utilizzo

Accedere al servizio metadati dell'istanza di Azure

Per accedere a IMDS, creare una macchina virtuale da Azure Resource Manager o dalla portale di Azure e usare gli esempi seguenti. Per altri esempi, vedere Esempi di metadati dell'istanza di Azure.

Ecco il codice di esempio per recuperare tutti i metadati per un'istanza. Per accedere a un'origine dati specifica, vedere Categorie di endpoint per una panoramica di tutte le funzionalità disponibili.

Richiedi

Importante

In questo esempio vengono ignorati i proxy. È necessario ignorare i proxy durante l'esecuzione di query su IMDS. Per altre informazioni, vedere Proxy .

Nota

Le richieste IMDS devono essere inviate usando la scheda di interfaccia di rete primaria e l'INDIRIZZO IP primario della macchina virtuale e DHCP devono essere abilitati.

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance?api-version=2021-02-01" | ConvertTo-Json -Depth 64

-NoProxy richiede PowerShell V6 o versione successiva. Vedere il repository di esempi per esempi con le versioni precedenti di PowerShell.

Risposta

Nota

La risposta è una stringa JSON. La risposta di esempio che segue è di tipo pretty-print per una migliore leggibilità.

{
    "compute": {
        "azEnvironment": "AZUREPUBLICCLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "westus",
        "name": "examplevmname",
        "offer": "WindowsServer",
        "osProfile": {
            "adminUsername": "admin",
            "computerName": "examplevmname",
            "disablePasswordAuthentication": "true"
        },
        "osType": "Windows",
        "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
        "plan": {
            "name": "planName",
            "product": "planProduct",
            "publisher": "planPublisher"
        },
        "platformFaultDomain": "36",
        "platformSubFaultDomain": "",        
        "platformUpdateDomain": "42",
        "priority": "Regular",
        "publicKeys": [{
                "keyData": "ssh-rsa 0",
                "path": "/home/user/.ssh/authorized_keys0"
            },
            {
                "keyData": "ssh-rsa 1",
                "path": "/home/user/.ssh/authorized_keys1"
            }
        ],
        "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
        "resourceGroupName": "macikgo-test-may-23",
        "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
        "securityProfile": {
            "secureBootEnabled": "true",
            "virtualTpmEnabled": "false",
            "encryptionAtHost": "true",
            "securityType": "TrustedLaunch"
        },
        "sku": "2019-Datacenter",
        "storageProfile": {
            "dataDisks": [{
                "bytesPerSecondThrottle": "979202048",
                "caching": "None",
                "createOption": "Empty",
                "diskCapacityBytes": "274877906944",
                "diskSizeGB": "1024",
                "image": {
                  "uri": ""
                },
                "isSharedDisk": "false",
                "isUltraDisk": "true",
                "lun": "0",
                "managedDisk": {
                  "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampledatadiskname",
                  "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampledatadiskname",
                "opsPerSecondThrottle": "65280",
                "vhd": {
                  "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            }],
            "imageReference": {
                "id": "",
                "offer": "WindowsServer",
                "publisher": "MicrosoftWindowsServer",
                "sku": "2019-Datacenter",
                "version": "latest",
                "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
                "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
                "exactVersion": "1.1686127202.30113"
            },
            "osDisk": {
                "caching": "ReadWrite",
                "createOption": "FromImage",
                "diskSizeGB": "30",
                "diffDiskSettings": {
                    "option": "Local"
                },
                "encryptionSettings": {
                  "enabled": "false",
                  "diskEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  },
                  "keyEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  }
                },
                "image": {
                    "uri": ""
                },
                "managedDisk": {
                    "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                    "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampleosdiskname",
                "osType": "Windows",
                "vhd": {
                    "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            },
            "resourceDisk": {
                "size": "4096"
            }
        },
        "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "tags": "baz:bash;foo:bar",
        "userData": "Zm9vYmFy",
        "version": "15.05.22",
        "virtualMachineScaleSet": {
            "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
        },
        "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
        "vmScaleSetName": "crpteste9vflji9",
        "vmSize": "Standard_A3",
        "zone": ""
    },
    "network": {
        "interface": [{
            "ipv4": {
               "ipAddress": [{
                    "privateIpAddress": "10.144.133.132",
                    "publicIpAddress": ""
                }],
                "subnet": [{
                    "address": "10.144.133.128",
                    "prefix": "26"
                }]
            },
            "ipv6": {
                "ipAddress": [
                 ]
            },
            "macAddress": "0011AAFFBB22"
        }]
    }
}

Sicurezza e autenticazione

Il servizio metadati dell'istanza è accessibile solo dall'interno di un'istanza di macchina virtuale in esecuzione in un indirizzo IP non instradabile. Le macchine virtuali possono interagire solo con i propri metadati/funzionalità. L'API è solo HTTP e non lascia mai l'host.

Per garantire che le richieste siano destinate direttamente a IMDS e impedire il reindirizzamento imprevisto o indesiderato di richieste, richieste:

  • Deve contenere l'intestazione Metadata: true
  • Non deve contenere un'intestazione X-Forwarded-For

Tutte le richieste che non soddisfano entrambi questi requisiti vengono rifiutate dal servizio.

Importante

IMDS non è un canale per i dati sensibili. L'API non è autenticata e aperta a tutti i processi nella macchina virtuale. Le informazioni esposte tramite questo servizio devono essere considerate come informazioni condivise a tutte le applicazioni in esecuzione nella macchina virtuale.

Se non è necessario per ogni processo della macchina virtuale per accedere all'endpoint IMDS, è possibile impostare regole del firewall locali per limitare l'accesso. Ad esempio, se solo un servizio di sistema noto deve accedere al servizio metadati dell'istanza, è possibile impostare una regola del firewall nell'endpoint IMDS, consentendo solo al processo specifico o negando l'accesso per il resto dei processi.

Proxy

IMDS non è progettato per essere usato dietro un proxy e in questo modo non è supportato. La maggior parte dei client HTTP offre un'opzione per disabilitare i proxy nelle richieste e questa funzionalità deve essere usata durante la comunicazione con IMDS. Per informazioni dettagliate, consultare la documentazione del client.

Importante

Anche se non si conosce alcuna configurazione proxy nell'ambiente, è comunque necessario eseguire l'override di tutte le impostazioni proxy client predefinite. Le configurazioni proxy possono essere individuate automaticamente e non è possibile ignorare tali configurazioni esponendo i rischi di interruzione in caso di modifica della configurazione del computer in futuro.

Limitazione della frequenza

In generale, le richieste a IMDS sono limitate a 5 richieste al secondo (per ogni macchina virtuale). Le richieste che superano questa soglia verranno rifiutate con risposte 429. Le richieste alla categoria Identità gestita sono limitate a 20 richieste al secondo e 5 richieste simultanee (per ogni macchina virtuale).

Verbi HTTP

Sono attualmente supportati i verbi HTTP seguenti:

Verbo Descrizione
GET Recuperare la risorsa richiesta

Parametri

Gli endpoint possono supportare parametri obbligatori e/o facoltativi. Per informazioni dettagliate, vedere Schema e la documentazione per l'endpoint specifico in questione.

Parametri di query

Gli endpoint IMDS supportano i parametri della stringa di query HTTP. Ad esempio:

http://169.254.169.254/metadata/instance/compute?api-version=2021-01-01&format=json

Specifica i parametri:

Nome Valore
api-version 2021-01-01
format json

Le richieste con nomi di parametri di query duplicati verranno rifiutate.

Parametri di route

Per alcuni endpoint che restituiscono BLOB JSON di dimensioni maggiori, è supportato l'aggiunta di parametri di route all'endpoint della richiesta per filtrare verso il basso in un subset della risposta:

http://169.254.169.254/metadata/<endpoint>/[<filter parameter>/...]?<query parameters>

I parametri corrispondono agli indici o alle chiavi che verrebbero usati per scorrere l'oggetto JSON durante l'interazione con una rappresentazione analizzata.

Ad esempio, restituisce /metadata/instance l'oggetto json:

{
    "compute": { ... },
    "network": {
        "interface": [
            {
                "ipv4": {
                   "ipAddress": [{
                        "privateIpAddress": "10.144.133.132",
                        "publicIpAddress": ""
                    }],
                    "subnet": [{
                        "address": "10.144.133.128",
                        "prefix": "26"
                    }]
                },
                "ipv6": {
                    "ipAddress": [
                     ]
                },
                "macAddress": "0011AAFFBB22"
            },
            ...
        ]
    }
}

Se si vuole filtrare la risposta in base alla sola proprietà di calcolo, inviare la richiesta:

http://169.254.169.254/metadata/instance/compute?api-version=<version>

Analogamente, se si vuole filtrare in base a una proprietà annidata o a un elemento di matrice specifico, si continuano ad accodare le chiavi:

http://169.254.169.254/metadata/instance/network/interface/0?api-version=<version>

filtra il primo elemento dalla Network.interface proprietà e restituisce:

{
    "ipv4": {
       "ipAddress": [{
            "privateIpAddress": "10.144.133.132",
            "publicIpAddress": ""
        }],
        "subnet": [{
            "address": "10.144.133.128",
            "prefix": "26"
        }]
    },
    "ipv6": {
        "ipAddress": [
         ]
    },
    "macAddress": "0011AAFFBB22"
}

Nota

Quando si filtra un nodo foglia, format=json non funziona. Per queste query format=text è necessario specificare in modo esplicito poiché il formato predefinito è json.

Schema

Formato dati

Per impostazione predefinita, IMDS restituisce i dati in formato JSON (Content-Type: application/json). Tuttavia, gli endpoint che supportano il filtro delle risposte (vedere Parametri di route) supportano anche il formato text.

Per accedere a un formato di risposta non predefinito, specificare il formato richiesto come parametro della stringa di query nella richiesta. Ad esempio:

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance?api-version=2017-08-01&format=text"

Nelle risposte JSON tutte le primitive saranno di tipo stringe i valori mancanti o non validi vengono sempre inclusi, ma verranno impostati su una stringa vuota.

Controllo delle versioni

IMDS è sottoposto a controllo delle versioni e specifica la versione dell'API nella richiesta HTTP è obbligatoria. L'unica eccezione a questo requisito è l'endpoint delle versioni , che può essere usato per recuperare in modo dinamico le versioni api disponibili.

Quando vengono aggiunte versioni più recenti, quelle precedenti rimangono comunque accessibili per la compatibilità, se gli script presentano dipendenze in formati di dati specifici.

Quando non si specifica una versione, viene visualizzato un errore con un elenco delle versioni supportate più recenti:

{
    "error": "Bad request. api-version was not specified in the request. For more information refer to aka.ms/azureimds",
    "newest-versions": [
        "2020-10-01",
        "2020-09-01",
        "2020-07-15"
    ]
}

Versioni API supportate

Nota

La versione 2023-11-15 è ancora in fase di implementazione, potrebbe non essere disponibile in alcune aree.

  • 2023-11-15
  • 2023-07-01
  • 2021-12-13
  • 2021-11-15
  • 2021-11-01
  • 2021-10-01
  • 2021-08-01
  • 2021-05-01
  • 2021-03-01
  • 2021-02-01
  • 01-2021-01
  • 2020-12-01
  • 01/10/2020
  • 01-09-2020
  • 15-07-2020
  • 2020-06-01
  • 01-11-2019
  • 2019-08-15
  • 2019-08-01
  • 2019-06-04
  • 01/06/2019
  • 2019-04-30
  • 2019-03-11
  • 2019-02-01
  • 2018-10-01
  • 2018-04-02
  • 2018-02-01
  • 2017-12-01
  • 2017-10-01
  • 01-08-2017
  • 2017-04-02
  • 2017-03-01

Swagger

Una definizione Swagger completa per IMDS è disponibile all'indirizzo: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/imds/data-plane/readme.md

Disponibilità a livello di area

Il servizio è disponibile a livello generale in tutti i cloud di Azure.

Endpoint radice

L'endpoint radice è http://169.254.169.254/metadata.

Categorie di endpoint

L'API IMDS contiene più categorie di endpoint che rappresentano origini dati diverse, ognuna delle quali contiene uno o più endpoint. Per informazioni dettagliate, vedere ogni categoria.

Radice categoria Descrizione Versione introdotta
/metadata/attested Vedere Dati con attestazione 2018-10-01
/metadata/identity Vedere Identità gestita tramite IMDS 2018-02-01
/metadata/instance Vedere Metadati dell'istanza 2017-04-02
/metadata/loadbalancer Vedere Recuperare i metadati del servizio di bilanciamento del carico tramite IMDS 01/10/2020
/metadata/scheduledevents Vedere Eventi pianificati tramite IMDS 01-08-2017
/metadata/versions Vedere Versioni N/D

Versioni

Elencare le versioni dell'API

Restituisce il set di versioni API supportate.

GET /metadata/versions

Parametri

Nessuno (questo endpoint non è stato modificato).

Response

{
  "apiVersions": [
    "2017-03-01",
    "2017-04-02",
    ...
  ]
}

Metadati dell'istanza

Ottenere i metadati della macchina virtuale

Espone i metadati importanti per l'istanza della macchina virtuale, tra cui calcolo, rete e archiviazione.

GET /metadata/instance

Parametri

Nome Obbligatorio/facoltativo Descrizione
api-version Richiesto Versione usata per gestire la richiesta.
format Opzionale* Formato (json o text) della risposta. *Nota: può essere necessario quando si usano parametri di richiesta

Questo endpoint supporta il filtro delle risposte tramite parametri di route.

Response

{
    "compute": {
        "azEnvironment": "AZUREPUBLICCLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "westus",
        "name": "examplevmname",
        "offer": "WindowsServer",
        "osProfile": {
            "adminUsername": "admin",
            "computerName": "examplevmname",
            "disablePasswordAuthentication": "true"
        },
        "osType": "Windows",
        "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
        "plan": {
            "name": "planName",
            "product": "planProduct",
            "publisher": "planPublisher"
        },
        "platformFaultDomain": "36",
        "platformSubFaultDomain": "",        
        "platformUpdateDomain": "42",
        "priority": "Regular",
        "publicKeys": [{
                "keyData": "ssh-rsa 0",
                "path": "/home/user/.ssh/authorized_keys0"
            },
            {
                "keyData": "ssh-rsa 1",
                "path": "/home/user/.ssh/authorized_keys1"
            }
        ],
        "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
        "resourceGroupName": "macikgo-test-may-23",
        "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
        "securityProfile": {
            "secureBootEnabled": "true",
            "virtualTpmEnabled": "false",
            "encryptionAtHost": "true",
            "securityType": "TrustedLaunch"
        },
        "sku": "2019-Datacenter",
        "storageProfile": {
            "dataDisks": [{
                "bytesPerSecondThrottle": "979202048",
                "caching": "None",
                "createOption": "Empty",
                "diskCapacityBytes": "274877906944",
                "diskSizeGB": "1024",
                "image": {
                  "uri": ""
                },
                "isSharedDisk": "false",
                "isUltraDisk": "true",
                "lun": "0",
                "managedDisk": {
                  "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampledatadiskname",
                  "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampledatadiskname",
                "opsPerSecondThrottle": "65280",
                "vhd": {
                  "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            }],
            "imageReference": {
                "id": "",
                "offer": "WindowsServer",
                "publisher": "MicrosoftWindowsServer",
                "sku": "2019-Datacenter",
                "version": "latest",
                "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
                "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
                "exactVersion": "1.1686127202.30113"
            },
            "osDisk": {
                "caching": "ReadWrite",
                "createOption": "FromImage",
                "diskSizeGB": "30",
                "diffDiskSettings": {
                    "option": "Local"
                },
                "encryptionSettings": {
                  "enabled": "false",
                  "diskEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  },
                  "keyEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  }
                },
                "image": {
                    "uri": ""
                },
                "managedDisk": {
                    "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                    "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampleosdiskname",
                "osType": "Windows",
                "vhd": {
                    "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            },
            "resourceDisk": {
                "size": "4096"
            }
        },
        "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "tags": "baz:bash;foo:bar",
        "userData": "Zm9vYmFy",
        "version": "15.05.22",
        "virtualMachineScaleSet": {
            "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
        },
        "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
        "vmScaleSetName": "crpteste9vflji9",
        "vmSize": "Standard_A3",
        "zone": ""
    },
    "network": {
        "interface": [{
            "ipv4": {
               "ipAddress": [{
                    "privateIpAddress": "10.144.133.132",
                    "publicIpAddress": ""
                }],
                "subnet": [{
                    "address": "10.144.133.128",
                    "prefix": "26"
                }]
            },
            "ipv6": {
                "ipAddress": [
                 ]
            },
            "macAddress": "0011AAFFBB22"
        }]
    }
}

Scomposizione dello schema:

Calcolo

Dati Descrizione Versione introdotta
azEnvironment Ambiente di Azure in cui è in esecuzione la macchina virtuale 2018-10-01
additionalCapabilities.hibernationEnabled Identifica se l'ibernazione è abilitata nella macchina virtuale 2021-11-01
customData Questa funzionalità è deprecata e disabilitata in IMDS. È stato sostituito da userData 2019-02-01
evictionPolicy Imposta la modalità di rimozione di una macchina virtuale spot. 2020-12-01
extendedLocation.type Tipo della posizione estesa della macchina virtuale. 2021-03-01
extendedLocation.name Nome della posizione estesa della macchina virtuale 2021-03-01
host.id Nome dell'host della macchina virtuale. Si noti che una macchina virtuale avrà un host o un hostGroup, ma non entrambi. 2021-11-15
hostGroup.id Nome del gruppo host della macchina virtuale. Si noti che una macchina virtuale avrà un host o un hostGroup, ma non entrambi. 2021-11-15
isHostCompatibilityLayerVm Identifica se la macchina virtuale viene eseguita nel livello di compatibilità host 2020-06-01
licenseType Tipo di licenza per Vantaggio Azure Hybrid. Questa opzione è presente solo per le macchine virtuali abilitate per AHB 01-09-2020
location Area di Azure in cui la macchina virtuale è in esecuzione 2017-04-02
name Nome della VM 2017-04-02
offer Offre informazioni per l'immagine di macchina virtuale ed è presente solo per le immagini distribuite dalla raccolta immagini di Azure 2017-04-02
osProfile.adminUsername Specifica il nome dell'account amministratore 15-07-2020
osProfile.computerName Specifica il nome del computer 15-07-2020
osProfile.disablePasswordAuthentication Specifica se l'autenticazione della password è disabilitata. Questo è presente solo per le macchine virtuali Linux 01/10/2020
osType Linux o Windows 2017-04-02
physicalZone Zona fisica della macchina virtuale 2023-11-15
placementGroupId Gruppo di posizionamento del set di scalabilità 01-08-2017
plan Pianificare il nome, il prodotto e l'editore per una macchina virtuale se si tratta di un'immagine di Azure Marketplace 2018-04-02
platformUpdateDomain Dominio di aggiornamento in cui è in esecuzione la macchina virtuale 2017-04-02
platformFaultDomain Dominio di errore in cui è in esecuzione la macchina virtuale 2017-04-02
platformSubFaultDomain Dominio di errore secondario in cui è in esecuzione la macchina virtuale, se applicabile. 2021-10-01
priority Priorità della macchina virtuale. Per altre informazioni, vedere Macchine virtuali spot 2020-12-01
provider Provider della macchina virtuale 2018-10-01
publicKeys Raccolta di chiavi pubbliche assegnate alla macchina virtuale e ai percorsi 2018-04-02
publisher Autore dell'immagine della macchina virtuale 2017-04-02
resourceGroupName Gruppo di risorse per la macchina virtuale 01-08-2017
resourceId ID completo della risorsa 2019-03-11
sku SKU specifica per l'immagine della macchina virtuale 2017-04-02
securityProfile.secureBootEnabled Identifica se l'avvio protetto UEFI è abilitato nella macchina virtuale 2020-06-01
securityProfile.virtualTpmEnabled Identifica se il modulo TPM (Trusted Platform Module) virtuale è abilitato nella macchina virtuale 2020-06-01
securityProfile.encryptionAtHost Identifica se la crittografia nell'host è abilitata nella macchina virtuale 2021-11-01
securityProfile.securityType Identifica se la macchina virtuale è una macchina virtuale attendibile o una macchina virtuale riservata 2021-12-13
storageProfile Vedere Profilo di archiviazione di seguito 01/06/2019
subscriptionId Sottoscrizione di Azure per la macchina virtuale 01-08-2017
tags Tag per la macchina virtuale 01-08-2017
tagsList Tag formattati come matrice JSON per un'analisi più semplice a livello programmatico 2019-06-04
userData Set di dati specificato quando la macchina virtuale è stata creata per l'uso durante o dopo il provisioning (con codifica Base64) 01-2021-01
version Versione dell'immagine della macchina virtuale 2017-04-02
virtualMachineScaleSet.id ID del set di scalabilità di macchine virtuali creato con orchestrazione flessibile di cui fa parte la macchina virtuale. Questo campo non è disponibile per set di scalabilità di macchine virtuali creato con orchestrazione uniforme. 2021-03-01
vmId Identificatore univoco per la macchina virtuale. Il blog ha fatto riferimento solo alle macchine virtuali con SMBIOS < 2.6. Per le macchine virtuali con SMBIOS >= 2.6, l'UUID di DMI viene visualizzato in formato little-endian, pertanto non è necessario cambiare byte. 2017-04-02
vmScaleSetName Nome del set di scalabilità di macchine virtuali del set di scalabilità 2017-12-01
vmSize Dimensioni macchina virtuale 2017-04-02
zone Zona di disponibilità della macchina virtuale 2017-12-01

† Questa versione non è ancora completamente disponibile e potrebbe non essere supportata in tutte le aree.

Profilo di archiviazione

Il profilo di archiviazione di una macchina virtuale è suddiviso in tre categorie: riferimento alle immagini, disco del sistema operativo e dischi dati, oltre a un oggetto aggiuntivo per il disco temporaneo locale.

L'oggetto riferimento all'immagine contiene le informazioni seguenti sull'immagine del sistema operativo. Si noti che un'immagine può provenire dalla piattaforma, dal marketplace, dalla raccolta community o dalla raccolta condivisa diretta, ma non da entrambe:

Dati Descrizione Versione introdotta
id ID risorsa 01/06/2019
offer Offerta dell'immagine della piattaforma o del marketplace 01/06/2019
publisher Autore dell'immagine della piattaforma o del marketplace 01/06/2019
sku Sku dell'immagine della piattaforma o del marketplace 01/06/2019
version Versione dell'immagine 01/06/2019
communityGalleryImageId ID risorsa dell'immagine della community, vuoto in caso contrario 2023-07-01
sharedGalleryImageId ID risorsa o immagine condivisa diretta, vuota in caso contrario 2023-07-01
exactVersion Versione della community o immagine condivisa diretta 2023-07-01

L'oggetto disco del sistema operativo contiene le informazioni seguenti sul disco del sistema operativo usato dalla macchina virtuale:

Dati Descrizione
caching Requisiti per la memorizzazione nella cache
createOption Informazioni sul modo in cui è stata creata la macchina virtuale
diffDiskSettings Impostazioni disco temporaneo
diskSizeGB Dimensioni del disco in GB
image Disco rigido virtuale dell'immagine utente di origine
managedDisk Parametri del disco gestito
name Nome del disco
vhd Disco rigido virtuale
writeAcceleratorEnabled Indica se writeAccelerator è abilitato sul disco

L'array di dischi dati contiene un elenco di dischi dati collegati alla macchina virtuale. Ogni oggetto disco dati contiene le informazioni seguenti:

Dati Descrizione Versione introdotta
bytesPerSecondThrottle* Quota di lettura/scrittura su disco in byte 2021-05-01
caching Requisiti per la memorizzazione nella cache 01/06/2019
createOption Informazioni sul modo in cui è stata creata la macchina virtuale 01/06/2019
diffDiskSettings Impostazioni disco temporaneo 01/06/2019
diskCapacityBytes* Dimensioni del disco in byte 2021-05-01
diskSizeGB Dimensioni del disco in GB 01/06/2019
encryptionSettings Impostazioni di crittografia per il disco 01/06/2019
image Disco rigido virtuale dell'immagine utente di origine 01/06/2019
isSharedDisk* Identifica se il disco è condiviso tra le risorse 2021-05-01
isUltraDisk Identifica se il disco dati è un disco Ultra 2021-05-01
lun Numero di unità logica del disco 01/06/2019
managedDisk Parametri del disco gestito 01/06/2019
name Nome del disco 01/06/2019
opsPerSecondThrottle* Quota di lettura/scrittura su disco in operazioni di I/O al secondo 2021-05-01
osType Tipo di sistema operativo incluso nel disco 01/06/2019
vhd Disco rigido virtuale 01/06/2019
writeAcceleratorEnabled Indica se writeAccelerator è abilitato sul disco 01/06/2019

*Questi campi vengono popolati solo per i dischi Ultra; sono stringhe vuote da dischi non Ultra.

Il BLOB delle impostazioni di crittografia contiene dati sulla modalità di crittografia del disco (se crittografato):

Dati Descrizione Versione introdotta
diskEncryptionKey.sourceVault.id Percorso della chiave di crittografia del disco 2021-11-01
diskEncryptionKey.secretUrl Posizione del segreto 2021-11-01
keyEncryptionKey.sourceVault.id Posizione della chiave di crittografia della chiave 2021-11-01
keyEncryptionKey.keyUrl Posizione della chiave 2021-11-01

L'oggetto disco risorse contiene le dimensioni del disco temporaneo locale collegato alla macchina virtuale, se presente, in kilobyte. Se non è presente alcun disco temporaneo locale per la macchina virtuale, questo valore è 0.

Dati Descrizione Versione introdotta
resourceDisk.size Dimensioni del disco temporaneo locale per la macchina virtuale (in kB) 2021-02-01

Rete

Dati Descrizione Versione introdotta
ipv4.privateIpAddress Indirizzo IPv4 locale della macchina virtuale 2017-04-02
ipv4.publicIpAddress Indirizzo IPv4 pubblico della macchina virtuale 2017-04-02
subnet.address Indirizzo della subnet della macchina virtuale 2017-04-02
subnet.prefix Prefisso della subnet, ad esempio 24 2017-04-02
ipv6.ipAddress Indirizzo IPv6 locale della macchina virtuale 2017-04-02
macAddress Indirizzo mac della macchina virtuale 2017-04-02

Nota

Le schede di interfaccia di rete restituite dalla chiamata di rete non sono sicuramente in ordine.

Ottenere i dati utente

Quando si crea una nuova macchina virtuale, è possibile specificare un set di dati da usare durante o dopo il provisioning della macchina virtuale e recuperarlo tramite IMDS. Controllare l'esperienza dei dati dell'utente finale qui.

Per configurare i dati utente, usare il modello di avvio rapido qui. L'esempio seguente illustra come recuperare questi dati tramite IMDS. Questa funzionalità viene rilasciata con la versione 2021-01-01 e versioni successive.

Nota

Avviso di sicurezza: IMDS è aperto a tutte le applicazioni nella macchina virtuale, i dati sensibili non devono essere inseriti nei dati utente.

$userData = Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/userData?api-version=2021-01-01&format=text"
[System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($userData))

Esempio 1: Rilevamento della macchina virtuale in esecuzione in Azure

Come provider di servizi, potrebbe essere necessario tenere traccia del numero di macchine virtuali che eseguono il proprio software o avere agenti che devono verificare l'univocità della macchina virtuale. Per poter ottenere un ID univoco per una macchina virtuale, usare il campo vmId dal Servizio metadati dell'istanza.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/vmId?api-version=2017-08-01&format=text"

Response

5c08b38e-4d57-4c23-ac45-aca61037f084

Esempio 2: Posizionamento di repliche di dati diverse

Per alcuni scenari, il posizionamento di repliche dati diverse è di importanza primaria. Ad esempio, il posizionamento della replica HDFS o il posizionamento dei contenitori tramite un agente di orchestrazione potrebbe richiedere di conoscere e platformFaultDomain platformUpdateDomain la macchina virtuale è in esecuzione. Per prendere decisioni di questo tipo è anche possibile basarsi sulle zone di disponibilità per le istanze. È possibile eseguire query sui dati direttamente tramite IMDS.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/platformFaultDomain?api-version=2017-08-01&format=text"

Response

0

Esempio 3: Ottenere i tag della macchina virtuale

I tag delle macchine virtuali sono inclusi nell'endpoint instance/compute/tags dell'API. È possibile che i tag siano stati applicati alla macchina virtuale di Azure per essere organizzati in modo logico in una tassonomia. I tag assegnati a una macchina virtuale possono essere recuperati tramite la richiesta seguente.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/tags?api-version=2017-08-01&format=text"

Response

Department:IT;ReferenceNumber:123456;TestStatus:Pending

Il campo tags è una stringa con i tag delimitati da punto e virgola. Questo output può essere un problema se i punti e virgola vengono usati nei tag stessi. Se un parser viene scritto per estrarre i tag a livello di codice, è necessario basarsi sul tagsList campo . Il tagsList campo è una matrice JSON senza delimitatori e di conseguenza è più facile da analizzare. I tagList assegnati a una macchina virtuale possono essere recuperati usando la richiesta seguente.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/tagsList?api-version=2019-06-04" | ConvertTo-Json -Depth 64

Response

{
    "value":  [
                  {
                      "name":  "Department",
                      "value":  "IT"
                  },
                  {
                      "name":  "ReferenceNumber",
                      "value":  "123456"
                  },
                  {
                      "name":  "TestStatus",
                      "value":  "Pending"
                  }
              ],
    "Count":  3
}

Esempio 4: Ottenere altre informazioni sulla macchina virtuale durante il caso di supporto

Come provider di servizi è possibile ricevere una chiamata di supporto per la quale occorre sapere altre informazioni sulla macchina virtuale. Chiedere al cliente di condividere i metadati di calcolo può risultare utile per avere informazioni di base che consentano al personale del supporto tecnico di conoscere il tipo di macchina virtuale in Azure.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute?api-version=2020-09-01" | ConvertTo-Json -Depth 64

Risposta

Nota

La risposta è una stringa JSON. La risposta di esempio che segue è di tipo pretty-print per una migliore leggibilità.

{
    "azEnvironment": "AZUREPUBLICCLOUD",
    "extendedLocation": {
      "type": "edgeZone",
      "name": "microsoftlosangeles"
    },
    "evictionPolicy": "",
    "additionalCapabilities": {
        "hibernationEnabled": "false"
    },
    "hostGroup": {
      "id": "testHostGroupId"
    },
    "isHostCompatibilityLayerVm": "true",
    "licenseType":  "Windows_Client",
    "location": "westus",
    "name": "examplevmname",
    "offer": "WindowsServer",
    "osProfile": {
        "adminUsername": "admin",
        "computerName": "examplevmname",
        "disablePasswordAuthentication": "true"
    },
    "osType": "Windows",
    "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
    "plan": {
        "name": "planName",
        "product": "planProduct",
        "publisher": "planPublisher"
    },
    "platformFaultDomain": "36",
    "platformUpdateDomain": "42",
    "priority": "Regular",
    "publicKeys": [{
            "keyData": "ssh-rsa 0",
            "path": "/home/user/.ssh/authorized_keys0"
        },
        {
            "keyData": "ssh-rsa 1",
            "path": "/home/user/.ssh/authorized_keys1"
        }
    ],
    "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
    "physicalZone": "useast-AZ01",
    "resourceGroupName": "macikgo-test-may-23",
    "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
    "securityProfile": {
        "secureBootEnabled": "true",
        "virtualTpmEnabled": "false",
        "encryptionAtHost": "true",
        "securityType": "TrustedLaunch"
    },
    "sku": "2019-Datacenter",
    "storageProfile": {
        "dataDisks": [{
            "bytesPerSecondThrottle": "979202048",
            "caching": "None",
            "createOption": "Empty",
            "diskCapacityBytes": "274877906944",
            "diskSizeGB": "1024",
            "image": {
              "uri": ""
            },
            "isSharedDisk": "false",
            "isUltraDisk": "true",
            "lun": "0",
            "managedDisk": {
              "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/MicrosoftCompute/disks/exampledatadiskname",
              "storageAccountType": "StandardSSD_LRS"
            },
            "name": "exampledatadiskname",
            "opsPerSecondThrottle": "65280",
            "vhd": {
              "uri": ""
            },
            "writeAcceleratorEnabled": "false"
        }],
        "imageReference": {
            "id": "",
            "offer": "WindowsServer",
            "publisher": "MicrosoftWindowsServer",
            "sku": "2019-Datacenter",
            "version": "latest",
            "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
            "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
            "exactVersion": "1.1686127202.30113"
        },
        "osDisk": {
            "caching": "ReadWrite",
            "createOption": "FromImage",
            "diskSizeGB": "30",
            "diffDiskSettings": {
                "option": "Local"
            },
            "encryptionSettings": {
              "enabled": "false",
              "diskEncryptionKey": {
                "sourceVault": {
                  "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                },
                "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
              },
              "keyEncryptionKey": {
                "sourceVault": {
                  "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                },
                "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
              }
            },
            "image": {
                "uri": ""
            },
            "managedDisk": {
                "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                "storageAccountType": "StandardSSD_LRS"
            },
            "name": "exampleosdiskname",
            "osType": "Windows",
            "vhd": {
                "uri": ""
            },
            "writeAcceleratorEnabled": "false"
        },
        "resourceDisk": {
            "size": "4096"
        }
    },
    "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "tags": "baz:bash;foo:bar",
    "version": "15.05.22",
    "virtualMachineScaleSet": {
      "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
    },
    "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
    "vmScaleSetName": "crpteste9vflji9",
    "vmSize": "Standard_A3",
    "zone": "3"
}

Esempio 5: Ottenere l'ambiente di Azure in cui è in esecuzione la macchina virtuale

Azure offre vari cloud sovrani, ad esempio Azure per enti pubblici. In taluni casi, per alcune decisioni di runtime è necessario l'ambiente di Azure. L'esempio seguente illustra come è possibile ottenere questo comportamento.

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/azEnvironment?api-version=2018-10-01&format=text"

Response

AzurePublicCloud

Il cloud e i valori dell'ambiente di Azure sono elencati qui.

Cloud Ambiente di Azure
Tutte le aree globali di Azure disponibili a livello generale AzurePublicCloud
Azure Government AzureUSGovernmentCloud
Microsoft Azure gestito da 21Vianet AzureChinaCloud
Azure Germania AzureGermanCloud

Esempio 6: Recuperare le informazioni di rete

Richiedi

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/network?api-version=2017-08-01" | ConvertTo-Json  -Depth 64

Response

{
  "interface": [
    {
      "ipv4": {
        "ipAddress": [
          {
            "privateIpAddress": "10.1.0.4",
            "publicIpAddress": "X.X.X.X"
          }
        ],
        "subnet": [
          {
            "address": "10.1.0.0",
            "prefix": "24"
          }
        ]
      },
      "ipv6": {
        "ipAddress": []
      },
      "macAddress": "000D3AF806EC"
    }
  ]
}

Esempio 7: Recuperare l'indirizzo IP pubblico

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text"

Nota

  • Per recuperare le informazioni IMDS per l'indirizzo IP pubblico dello SKU Standard , vedere l'API metadati del servizio di bilanciamento del carico per altre informazioni.

Dati attestati

Ottenere dati attestati

IMDS consente di garantire che i dati forniti proveniranno da Azure. Microsoft firma parte di queste informazioni, in modo da poter verificare che un'immagine in Azure Marketplace sia quella in esecuzione in Azure.

GET /metadata/attested/document

Parametri

Nome Obbligatorio/facoltativo Descrizione
api-version Richiesto Versione usata per gestire la richiesta.
nonce Facoltativo Stringa a 10 cifre che funge da nonce crittografico. Se non viene specificato alcun valore, IMDS usa il timestamp UTC corrente.

Response

{
    "encoding":"pkcs7",
    "signature":"MIIEEgYJKoZIhvcNAQcCoIIEAzCCA/8CAQExDzANBgkqhkiG9w0BAQsFADCBugYJKoZIhvcNAQcBoIGsBIGpeyJub25jZSI6IjEyMzQ1NjY3NjYiLCJwbGFuIjp7Im5hbWUiOiIiLCJwcm9kdWN0IjoiIiwicHVibGlzaGVyIjoiIn0sInRpbWVTdGFtcCI6eyJjcmVhdGVkT24iOiIxMS8yMC8xOCAyMjowNzozOSAtMDAwMCIsImV4cGlyZXNPbiI6IjExLzIwLzE4IDIyOjA4OjI0IC0wMDAwIn0sInZtSWQiOiIifaCCAj8wggI7MIIBpKADAgECAhBnxW5Kh8dslEBA0E2mIBJ0MA0GCSqGSIb3DQEBBAUAMCsxKTAnBgNVBAMTIHRlc3RzdWJkb21haW4ubWV0YWRhdGEuYXp1cmUuY29tMB4XDTE4MTEyMDIxNTc1N1oXDTE4MTIyMDIxNTc1NlowKzEpMCcGA1UEAxMgdGVzdHN1YmRvbWFpbi5tZXRhZGF0YS5henVyZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAML/tBo86ENWPzmXZ0kPkX5dY5QZ150mA8lommszE71x2sCLonzv4/UWk4H+jMMWRRwIea2CuQ5RhdWAHvKq6if4okKNt66fxm+YTVz9z0CTfCLmLT+nsdfOAsG1xZppEapC0Cd9vD6NCKyE8aYI1pliaeOnFjG0WvMY04uWz2MdAgMBAAGjYDBeMFwGA1UdAQRVMFOAENnYkHLa04Ut4Mpt7TkJFfyhLTArMSkwJwYDVQQDEyB0ZXN0c3ViZG9tYWluLm1ldGFkYXRhLmF6dXJlLmNvbYIQZ8VuSofHbJRAQNBNpiASdDANBgkqhkiG9w0BAQQFAAOBgQCLSM6aX5Bs1KHCJp4VQtxZPzXF71rVKCocHy3N9PTJQ9Fpnd+bYw2vSpQHg/AiG82WuDFpPReJvr7Pa938mZqW9HUOGjQKK2FYDTg6fXD8pkPdyghlX5boGWAMMrf7bFkup+lsT+n2tRw2wbNknO1tQ0wICtqy2VqzWwLi45RBwTGB6DCB5QIBATA/MCsxKTAnBgNVBAMTIHRlc3RzdWJkb21haW4ubWV0YWRhdGEuYXp1cmUuY29tAhBnxW5Kh8dslEBA0E2mIBJ0MA0GCSqGSIb3DQEBCwUAMA0GCSqGSIb3DQEBAQUABIGAld1BM/yYIqqv8SDE4kjQo3Ul/IKAVR8ETKcve5BAdGSNkTUooUGVniTXeuvDj5NkmazOaKZp9fEtByqqPOyw/nlXaZgOO44HDGiPUJ90xVYmfeK6p9RpJBu6kiKhnnYTelUk5u75phe5ZbMZfBhuPhXmYAdjc7Nmw97nx8NnprQ="
}

Il BLOB di firma è una versione con firma pkcs7 del documento. Contiene il certificato usato per la firma insieme a determinati dettagli specifici della macchina virtuale.

Per le macchine virtuali create con Azure Resource Manager, il documento include vmId, sku, nonce, subscriptionId, timeStamp per la creazione e la scadenza del documento e le informazioni sul piano relative all'immagine. Le informazioni sul piano vengono popolate solo per le immagini di Azure Marketplace.

Per le macchine virtuali create usando il modello di distribuzione classica, è vmId garantito che solo e subscriptionId vengano popolate. È possibile estrarre il certificato dalla risposta e usarlo per confermare che la risposta è valida e proviene da Azure.

Il documento decodificato contiene i campi seguenti:

Dati Descrizione Versione introdotta
licenseType Tipo di licenza per Vantaggio Azure Hybrid. Questa opzione è presente solo per le macchine virtuali abilitate per AHB. 01-09-2020
nonce Stringa che può essere fornita facoltativamente con la richiesta. Se non è stato specificato alcun nonce valore, viene utilizzato il timestamp timestamp Coordinated Universal Time corrente. 2018-10-01
plan Piano di immagini di Azure Marketplace. Contiene l'ID del piano (nome), l'immagine del prodotto o l'offerta (prodotto) e l'ID editore (editore). 2018-10-01
timestamp.createdOn Timestamp UTC per il momento in cui è stato creato il documento firmato 2018-20-01
timestamp.expiresOn Timestamp UTC per la scadenza del documento firmato 2018-10-01
vmId Identificatore univoco della macchina virtuale 2018-10-01
subscriptionId Sottoscrizione di Azure per la macchina virtuale 2019-04-30
sku SKU specifico per l'immagine della macchina virtuale (correlato alla compute/sku proprietà dall'endpoint dei metadati dell'istanza [/metadata/instance]) 01-11-2019

Nota

Per le macchine virtuali classiche (non Azure Resource Manager), è garantito che venga popolato solo il valore vmId.

Documento di esempio:

{
   "nonce":"20201130-211924",
   "plan":{
      "name":"planName",
      "product":"planProduct",
      "publisher":"planPublisher"
   },
   "sku":"Windows-Server-2012-R2-Datacenter",
   "subscriptionId":"8d10da13-8125-4ba9-a717-bf7490507b3d",
   "timeStamp":{
      "createdOn":"11/30/20 21:19:19 -0000",
      "expiresOn":"11/30/20 21:19:24 -0000"
   },
   "vmId":"02aab8a4-74ef-476e-8182-f6d2ba4166a6"
}

Linee guida per la convalida della firma

Quando si convalida la firma, è necessario verificare che la firma sia stata creata con un certificato da Azure. Questa operazione viene eseguita convalidando il nome alternativo soggetto del certificato (SAN).

San di esempio DNS Name=eastus.metadata.azure.com, DNS Name=metadata.azure.com

Nota

Il dominio per il cloud pubblico e ogni cloud sovrano sarà diverso.

Cloud Dominio in SAN
Tutte le aree globali di Azure disponibili a livello generale *.metadata.azure.com
Azure Government *.metadata.azure.us
Azure gestito da 21Vianet *.metadata.azure.cn
Azure Germania *.metadata.microsoftazure.de

Nota

I certificati potrebbero non avere una corrispondenza esatta per il dominio. Per questo motivo, la convalida della certificazione deve accettare qualsiasi sottodominio( ad esempio, nelle aree di disponibilità generale del cloud pubblico accettare *.metadata.azure.com).

Non è consigliabile aggiungere certificati per i certificati intermedi. Per altre indicazioni, vedere Aggiunta di certificati - Aggiunta di certificati e servizi di Azure. Si noti che il servizio metadati dell'istanza di Azure NON offrirà notifiche per le modifiche future dell'autorità di certificazione. È invece necessario seguire l'articolo dei dettagli centralizzati dell'autorità di certificazione di Azure per tutti gli aggiornamenti futuri.

Esempio 1: Verificare che la macchina virtuale sia in esecuzione in Azure

I fornitori in Azure Marketplace vogliono assicurarsi che il software sia concesso in licenza per l'esecuzione solo in Azure. Se un utente copia il disco rigido virtuale in un ambiente locale, il fornitore deve essere in grado di rilevare il disco rigido virtuale. Tramite IMDS, questi fornitori possono ottenere dati firmati che garantiscono la risposta solo da Azure.

Nota

Questo esempio richiede l'installazione dell'utilità jq.

Convalida

# Get the signature
$attestedDoc = Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri http://169.254.169.254/metadata/attested/document?api-version=2020-09-01
# Decode the signature
$signature = [System.Convert]::FromBase64String($attestedDoc.signature)

Verificare che la firma provena da Microsoft Azure e controlli la catena di certificati per verificare la presenza di errori.

# Get certificate chain
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]($signature)
$chain = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Chain
$chain.Build($cert)
# Print the Subject of each certificate in the chain
foreach($element in $chain.ChainElements)
{
    Write-Host $element.Certificate.Subject
}

# Get the content of the signed document
Add-Type -AssemblyName System.Security
$signedCms = New-Object -TypeName System.Security.Cryptography.Pkcs.SignedCms
$signedCms.Decode($signature);
$content = [System.Text.Encoding]::UTF8.GetString($signedCms.ContentInfo.Content)
Write-Host "Attested data: " $content
$json = $content | ConvertFrom-Json
# Do additional validation here

L'oggetto nonce nel documento firmato può essere confrontato se è stato specificato un nonce parametro nella richiesta iniziale.

Identità gestita

Un'identità gestita, assegnata dal sistema, può essere abilitata nella macchina virtuale. È anche possibile assegnare una o più identità gestite assegnate dall'utente alla macchina virtuale. È quindi possibile richiedere token per le identità gestite da IMDS. Usare questi token per eseguire l'autenticazione con altri servizi di Azure, ad esempio Azure Key Vault.

Per i passaggi dettagliati per abilitare questa funzionalità, vedere Acquisire un token di accesso.

Metadati del servizio di bilanciamento del carico

Quando si inseriscono istanze del set di macchine virtuali o di una macchina virtuale dietro un'istanza di Azure Load Balancer Standard, è possibile usare IMDS per recuperare i metadati correlati al servizio di bilanciamento del carico e alle istanze. Per altre informazioni, vedere Recuperare informazioni sul servizio di bilanciamento del carico.

Eventi pianificati

È possibile ottenere lo stato degli eventi pianificati usando IMDS. L'utente può quindi specificare un set di azioni da eseguire su questi eventi. Per altre informazioni, vedere Eventi pianificati per Linux o Eventi pianificati per Windows.

Codice di esempio in linguaggi diversi

La tabella seguente elenca gli esempi di chiamata a IMDS usando lingue diverse all'interno della macchina virtuale:

Lingua Esempio
Bash https://github.com/Microsoft/azureimds/blob/master/IMDSSample.sh
C# https://github.com/Microsoft/azureimds/blob/master/IMDSSample.cs
Go https://github.com/Microsoft/azureimds/blob/master/imdssample.go
Java https://github.com/Microsoft/azureimds/blob/master/imdssample.java
NodeJS https://github.com/Microsoft/azureimds/blob/master/IMDSSample.js
Perl https://github.com/Microsoft/azureimds/blob/master/IMDSSample.pl
PowerShell https://github.com/Microsoft/azureimds/blob/master/IMDSSample.ps1
Puppet https://github.com/keirans/azuremetadata
Python https://github.com/Microsoft/azureimds/blob/master/IMDSSample.py
Ruby https://github.com/Microsoft/azureimds/blob/master/IMDSSample.rb

Errori e debug

Se è presente un elemento dati non trovato o una richiesta in formato non valido, il servizio metadati dell'istanza restituisce errori HTTP standard. Ad esempio:

Codice di stato HTTP Motivo
200 OK La richiesta è stata completata.
400 Bad Request Intestazione Metadata: true mancante o parametro format=json mancante durante l'esecuzione di query su un nodo foglia
404 Not Found L'elemento richiesto non esiste
405 Method Not Allowed Il metodo HTTP (verbo) non è supportato nell'endpoint.
410 Gone Riprovare tra qualche istante per un massimo di 70 secondi
429 Too Many Requests Sono stati superati i limiti di frequenza API
500 Service Error Ripetere l'operazione in un secondo momento

Domande frequenti

  • Viene visualizzato l'errore 400 Bad Request, Required metadata header not specified. Che cosa significa?

    • IMDS richiede che l'intestazione Metadata: true venga passata nella richiesta. Il passaggio di questa intestazione nella chiamata REST consente l'accesso a IMDS.

  • Perché non si ricevono informazioni di calcolo per la macchina virtuale?

    • Attualmente, IMDS supporta solo le istanze create con Azure Resource Manager.

  • La macchina virtuale è stata creata tramite Azure Resource Manager qualche tempo fa. Perché non riesco a vedere le informazioni sui metadati di calcolo?

    • Se la macchina virtuale è stata creata dopo settembre 2016, aggiungere un tag per iniziare a visualizzare i metadati di calcolo. Se la macchina virtuale è stata creata prima di settembre 2016, aggiungere o rimuovere estensioni o dischi dati all'istanza della macchina virtuale per aggiornare i metadati.

  • I dati utente sono gli stessi dei dati personalizzati?

    • I dati utente offrono la funzionalità simile ai dati personalizzati, consentendo di passare i propri metadati all'istanza della macchina virtuale. La differenza è che i dati utente vengono recuperati tramite IMDS e sono persistenti per tutta la durata dell'istanza della macchina virtuale. La funzionalità dati personalizzati esistente continuerà a funzionare come descritto in questo articolo. Tuttavia, è possibile ottenere dati personalizzati solo tramite la cartella di sistema locale, non tramite IMDS.

  • Perché non vengono visualizzati tutti i dati popolati per una nuova versione?

    • Se la macchina virtuale è stata creata dopo settembre 2016, aggiungere un tag per iniziare a visualizzare i metadati di calcolo. Se la macchina virtuale è stata creata prima di settembre 2016, aggiungere o rimuovere estensioni o dischi dati all'istanza della macchina virtuale per aggiornare i metadati.

  • Perché viene visualizzato l'errore 500 Internal Server Error o 410 Resource Gone?

    • Riprovare a eseguire la richiesta. Per altre informazioni, vedere Gestione degli errori temporanei. Se il problema persiste, creare un problema di supporto nel portale di Azure per la macchina virtuale.

  • Questa operazione funziona per le istanze del set di scalabilità?

    • Sì, IMDS è disponibile per le istanze del set di scalabilità.

  • I tag sono stati aggiornati nei set di scalabilità, ma non vengono visualizzati nelle istanze (a differenza delle macchine virtuali a istanza singola). Sto facendo qualcosa di sbagliato?

    • Attualmente i tag per i set di scalabilità vengono visualizzati solo alla macchina virtuale in caso di riavvio, ricreazione dell'immagine o modifica del disco nell'istanza.

  • Perché non vengono visualizzate le informazioni sullo SKU per la macchina virtuale nei instance/compute dettagli?

    • Per le immagini personalizzate create da Azure Marketplace, la piattaforma Azure non mantiene le informazioni sullo SKU per l'immagine personalizzata e i dettagli per le macchine virtuali create dall'immagine personalizzata. Questa operazione è progettata e quindi non è stata rilevata nei dettagli della macchina virtuale instance/compute .

  • Perché il timeout della richiesta (o non è riuscito a connettersi) per la chiamata al servizio?

    • Le chiamate ai metadati devono essere effettuate dall'indirizzo IP primario assegnato alla scheda di rete primaria della macchina virtuale. Inoltre, se sono state modificate le route, nella tabella di routing locale della macchina virtuale deve essere presente una route per l'indirizzo 169.254.169.254/32.

      1. Eseguire il dump della tabella di routing locale e cercare la voce IMDS. Ad esempio:

        route print

        IPv4 Route Table
===========================================================================
Active Routes:
Network Destination        Netmask          Gateway       Interface  Metric
        0.0.0.0          0.0.0.0      172.16.69.1      172.16.69.7     10
        127.0.0.0        255.0.0.0         On-link         127.0.0.1    331
        127.0.0.1  255.255.255.255         On-link         127.0.0.1    331
127.255.255.255  255.255.255.255         On-link         127.0.0.1    331
    168.63.129.16  255.255.255.255      172.16.69.1      172.16.69.7     11
169.254.169.254  255.255.255.255      172.16.69.1      172.16.69.7     11
... (continues) ...

      2. Verificare che esista una route per 169.254.169.254e prendere nota dell'interfaccia di rete corrispondente , ad esempio 172.16.69.7.

      3. Eseguire il dump della configurazione dell'interfaccia e trovare l'interfaccia corrispondente a quella a cui si fa riferimento nella tabella di routing, notando l'indirizzo MAC (fisico).

        ipconfig /all

        ... (continues) ...
Ethernet adapter Ethernet:

Connection-specific DNS Suffix  . : xic3mnxjiefupcwr1mcs1rjiqa.cx.internal.cloudapp.net
Description . . . . . . . . . . . : Microsoft Hyper-V Network Adapter
Physical Address. . . . . . . . . : 00-0D-3A-E5-1C-C0
DHCP Enabled. . . . . . . . . . . : Yes
Autoconfiguration Enabled . . . . : Yes
Link-local IPv6 Address . . . . . : fe80::3166:ce5a:2bd5:a6d1%3(Preferred)
IPv4 Address. . . . . . . . . . . : 172.16.69.7(Preferred)
Subnet Mask . . . . . . . . . . . : 255.255.255.0
... (continues) ...

      4. Verificare che l'interfaccia corrisponda alla scheda di interfaccia di rete primaria e all'indirizzo IP primario della macchina virtuale. È possibile trovare la scheda di interfaccia di rete primaria e l'indirizzo IP esaminando la configurazione di rete nella portale di Azure oppure cercandola con l'interfaccia della riga di comando di Azure. Si notino gli INDIRIZZI IP privati (e l'indirizzo MAC se si usa l'interfaccia della riga di comando). Ecco un esempio dell'interfaccia della riga di comando di PowerShell:

        $ResourceGroup = '<Resource_Group>'
$VmName = '<VM_Name>'
$NicNames = az vm nic list --resource-group $ResourceGroup --vm-name $VmName | ConvertFrom-Json | Foreach-Object { $_.id.Split('/')[-1] }
foreach($NicName in $NicNames)
{
    $Nic = az vm nic show --resource-group $ResourceGroup --vm-name $VmName --nic $NicName | ConvertFrom-Json
    Write-Host $NicName, $Nic.primary, $Nic.macAddress
}

        wintest767 True 00-0D-3A-E5-1C-C0

      5. Se non corrispondono, aggiornare la tabella di routing in modo che la scheda di interfaccia di rete primaria e l'INDIRIZZO IP siano destinati.

  • Failover del clustering in Windows Server

    • Quando si esegue una query su IMDS con il clustering di failover, a volte è necessario aggiungere una route alla tabella di routing. Ecco come fare:

      1. Aprire un prompt dei comandi con privilegi di amministratore.

      2. Eseguire il comando seguente e prendere nota dell'indirizzo dell'interfaccia per la destinazione di rete (0.0.0.0) nella tabella di route IPv4.

      route print

      Nota

      L'output di esempio seguente proviene da una macchina virtuale Windows Server con cluster di failover abilitato. Per semplicità, l'output contiene solo la tabella di route IPv4.

      IPv4 Route Table
===========================================================================
Active Routes:
Network Destination        Netmask          Gateway       Interface  Metric
        0.0.0.0          0.0.0.0         10.0.1.1        10.0.1.10    266
        10.0.1.0  255.255.255.192         On-link         10.0.1.10    266
        10.0.1.10  255.255.255.255         On-link         10.0.1.10    266
        10.0.1.15  255.255.255.255         On-link         10.0.1.10    266
        10.0.1.63  255.255.255.255         On-link         10.0.1.10    266
        127.0.0.0        255.0.0.0         On-link         127.0.0.1    331
        127.0.0.1  255.255.255.255         On-link         127.0.0.1    331
127.255.255.255  255.255.255.255         On-link         127.0.0.1    331
    169.254.0.0      255.255.0.0         On-link     169.254.1.156    271
    169.254.1.156  255.255.255.255         On-link     169.254.1.156    271
169.254.255.255  255.255.255.255         On-link     169.254.1.156    271
        224.0.0.0        240.0.0.0         On-link         127.0.0.1    331
        224.0.0.0        240.0.0.0         On-link     169.254.1.156    271
255.255.255.255  255.255.255.255         On-link         127.0.0.1    331
255.255.255.255  255.255.255.255         On-link     169.254.1.156    271
255.255.255.255  255.255.255.255         On-link         10.0.1.10    266

      Eseguire il comando seguente e usare l'indirizzo dell'interfaccia per la destinazione di rete (), ovvero (0.0.0.010.0.1.10) in questo esempio.

      route add 169.254.169.254/32 10.0.1.10 metric 1 -p

Supporto tecnico

Se non è possibile ottenere una risposta ai metadati dopo più tentativi, è possibile creare un problema di supporto nel portale di Azure.

Feedback sul prodotto

È possibile fornire commenti e suggerimenti sui prodotti al canale di feedback degli utenti in Macchine virtuali > Servizio metadati dell'istanza qui

Passaggi successivi