通过

Azure 实例元数据服务

  • 项目

适用于：✔️ Linux VM ✔️ Windows VM ✔️ 灵活规模集

Azure 实例元数据服务 (IMDS) 提供有关当前正在运行的虚拟机实例的信息。 可以使用它来管理和配置虚拟机。 这些信息包括 SKU、存储、网络配置和即将发生的维护事件。 有关可用数据的完整列表，请参阅终结点类别摘要。

IMDS 可用于运行虚拟机 (VM) 实例和规模集实例。 所有终结点均支持使用 Azure 资源管理器创建和管理的 VM。 只有“实例”类别的“经过证明的”类别和“网络”部分支持通过经典部署模型创建的 VM。 “经过证明的”终结点仅在有限的程度上提供这样的支持。

IMDS 是一个 REST API，在已知的、不可路由的 IP 地址 (169.254.169.254) 上提供。 只能从 VM 中访问它。 VM 与 IMDS 之间的通信绝不会离开主机。 使 HTTP 客户端在查询 IMDS 时绕过 VM 中的 Web 代理。

使用情况

访问 Azure 实例元数据服务

若要访问 IMDS，请从 Azure 资源管理器或 Azure 门户创建一个 VM，并使用以下示例。 如需更多示例，请参阅 Azure 实例元数据示例。

下面是用于检索实例的所有元数据的示例代码。 若要访问特定的数据源，请参阅终结点类别，其中概述了所有可用的功能。

请求

重要

此示例会绕过代理。 查询 IMDS 时，必须绕过代理。 有关其他信息，请参阅代理。

注意

必须使用 VM 的主 NIC 和主 IP 发送 IMDS 请求，并且必须启用 DHCP。

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 需要 PowerShell V6 或更高版本。 请参阅我们的示例存储库，了解具有较旧 PowerShell 版本的示例。

响应

注意

此响应是 JSON 字符串。 以下示例响应显示清晰，可供阅读。

{
    "compute": {
        "azEnvironment": "AZURECHINACLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "chinanorth",
        "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.cn/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.cn/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"
        }]
    }
}

安全性和身份验证

实例元数据服务仅供从不可路由的 IP 地址上正在运行的虚拟机实例中访问。 VM 只能与自己的元数据/功能交互。 API 仅限 HTTP，且从不离开主机。

为了确保请求直接适用于 IMDS，并防止意外的或不需要的请求重定向，请求必须符合以下条件：

  • 必须包含标头 Metadata: true
  • 不得包含 X-Forwarded-For 标头

任何不符合这两项要求的请求都会被服务拒绝。

重要

IMDS 不是敏感数据的通道。 此 API 不进行身份验证，并且对 VM 上的所有进程开放。 应将通过此服务公开的信息视为与 VM 内运行的所有应用程序共享的信息。

如果不需要 VM 上的每个进程都访问 IMDS 终结点，可以通过设置本地防火墙规则来限制访问。 例如，如果只有已知系统服务需要访问实例元数据服务，则可以在 IMDS 终结点上设置防火墙规则，仅允许特定进程访问或拒绝访问其余进程。

代理

IMDS 不用于在代理后使用，系统不支持那样做。 大多数 HTTP 客户端提供了一个选项，供你对你的请求禁用代理，当与 IMDS 通信时必须使用此功能。 有关详细信息，请参阅客户端的文档。

重要

即使你不知道环境中的任何代理配置的信息，也必须重写任何默认的客户端代理设置。 代理配置可以被自动发现，未能绕过这样的配置就必须冒服务中断的风险（如果将来要更改计算机的配置的话）。

速率限制

一般情况下，对 IMDS 的请求限制为（每个虚拟机）每秒 5 个请求。 系统会拒绝超过此阈值的请求，并显示 429 响应。 对托管标识类别请求的限制为每秒 20 个请求，5 个并发请求（基于每个 VM）。

HTTP 谓词

目前支持以下 HTTP 谓词：

谓词 说明
GET 检索请求的资源

参数

终结点可以支持必需的和/或可选的参数。 有关详细信息，请参阅架构以及相关的特定终结点的文档。

查询参数

IMDS 终结点支持 HTTP 查询字符串参数。 例如：

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

指定参数：

名称 值
api-version 2021-01-01
format json

系统会拒绝具有重复的查询参数名称的请求。

路由参数

对于某些返回较大 json blob 的终结点，我们支持将路由参数追加到请求终结点，以便向下筛选到响应的某个子集：

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

参数对应的索引/键将用于逐级向下找到 json 对象（如果你与已分析的表示形式交互）。

例如，/metadata/instance 会返回 json 对象：

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

若要将响应向下筛选到计算属性，则可发送以下请求：

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

类似地，若要筛选到嵌套的属性或特定的数组元素，则可不断地追加键：

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

将会筛选到 Network.interface 属性中的第一个元素，并返回：

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

注意

筛选到叶节点时，format=json 将不起作用。 对于这些查询，需要显式指定 format=text，因为默认格式为 json。

架构

数据格式

默认情况下，IMDS 以 JSON 格式返回数据 (Content-Type: application/json)。 但是，支持响应筛选（请参阅路由参数）的终结点还支持 text 格式。

若要访问非默认响应格式，请在请求中将所请求的格式指定为查询字符串参数。 例如：

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

在 json 响应中，所有基元都将为 string 类型，缺失值或不适用的值始终包括在内，但会被设置为空字符串。

版本控制

IMDS 进行了版本控制，在 HTTP 请求中指定 API 版本是必需的。 此要求的唯一例外是 versions 终结点，该终结点可用于动态检索可用的 API 版本。

在添加更新的版本时，早期版本仍可供访问以保持兼容性（如果脚本依赖于特定的数据格式）。

如果不指定版本，则会收到错误消息，其中会列出受支持的最新版本：

{
    "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"
    ]
}

支持的 API 版本

注意

版本 2023-11-15 仍在推出中，部分区域可能无法使用。

  • 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
  • 2021-01-01
  • 2020-12-01
  • 2020-10-01
  • 2020-09-01
  • 2020-07-15
  • 2020-06-01
  • 2019-11-01
  • 2019-08-15
  • 2019-08-01
  • 2019-06-04
  • 2019-06-01
  • 2019-04-30
  • 2019-03-11
  • 2019-02-01
  • 2018-10-01
  • 2018-04-02
  • 2018-02-01
  • 2017-12-01
  • 2017-10-01
  • 2017-08-01
  • 2017-04-02
  • 2017-03-01

Swagger

可在以下位置找到 IMDS 的完整 Swagger 定义： https://github.com/Azure/azure-rest-api-specs/blob/main/specification/imds/data-plane/readme.md

根终结点

根终结点为 http://169.254.169.254/metadata。

终结点类别

IMDS API 包含多个表示不同数据源的终结点类别，每一个都包含一个或多个终结点。 有关详细信息，请查看每个类别。

类别根 说明 引入的版本
/metadata/attested 请参阅证明数据 2018-10-01
/metadata/identity 请参阅通过 IMDS 托管的托管标识 2018-02-01
/metadata/instance 请参阅实例元数据 2017-04-02
/metadata/loadbalancer 请参阅通过 IMDS 检索负载均衡器元数据 2020-10-01
/metadata/scheduledevents 请参阅通过 IMDS 计划的计划事件 2017-08-01
/metadata/versions 请参阅版本 不适用

版本

列出 API 版本

返回受支持的 API 版本的集合。

GET /metadata/versions

参数

无（此终结点未进行版本控制）。

响应

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

实例元数据

获取 VM 元数据

公开 VM 实例的重要元数据，其中包括计算、网络和存储。

GET /metadata/instance

参数

名称 必需/可选 说明
api-version 必需 用于处理请求的版本。
format 可选* 响应的格式（json 或 text）。 *注意：使用请求参数时可能需要

此终结点支持通过路由参数进行响应筛选。

响应

{
    "compute": {
        "azEnvironment": "AZURECHINACLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "chinanorth",
        "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.cn/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.cn/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"
        }]
    }
}

架构明细：

计算

数据 说明 引入的版本
azEnvironment VM 运行时所在的 Azure 环境 2018-10-01
additionalCapabilities.hibernationEnabled 确定是否在 VM 上启用了休眠 2021-11-01
customData 此功能在 IMDS 中已弃用且已禁用。 它已被 userData 取代 2019-02-01
extendedLocation.type VM 的扩展位置的类型。 2021-03-01
extendedLocation.name VM 的扩展位置的名称 2021-03-01
host.id VM 的主机的名称。 请注意，VM 将具有主机或主机组，但不能同时具有这两者。 2021-11-15
hostGroup.id VM 的主机组的名称。 请注意，VM 将具有主机或主机组，但不能同时具有这两者。 2021-11-15
isHostCompatibilityLayerVm 标识 VM 是否在主机兼容性层上运行 2020-06-01
licenseType Azure 混合权益许可证的类型。 这仅适用于启用了 AHB 的 VM 2020-09-01
location VM 在其中运行的 Azure 区域 2017-04-02
name VM 的名称 2017-04-02
offer 提供 VM 映像的信息，仅适用于从 Azure 映像库部署的映像 2017-04-02
osProfile.adminUsername 指定管理员帐户的名称 2020-07-15
osProfile.computerName 指定计算机的名称 2020-07-15
osProfile.disablePasswordAuthentication 指定是否禁用密码身份验证。 这仅适用于 Linux VM 2020-10-01
osType Linux 或 Windows 2017-04-02
physicalZone VM 的物理区域 2023-11-15
placementGroupId 你的规模集的放置组 2017-08-01
plan 包含名称、产品和发布者的 VM 计划（如果是 Azure 市场映像） 2018-04-02
platformUpdateDomain 正在运行 VM 的更新域 2017-04-02
platformFaultDomain 正在运行 VM 的容错域 2017-04-02
platformSubFaultDomain 运行 VM 的子容错域（如果适用）。 2021-10-01
provider VM 的提供商 2018-10-01
publicKeys 公钥的集合，已分配给 VM 和路径 2018-04-02
publisher VM 映像的发布者 2017-04-02
resourceGroupName 虚拟机的资源组 2017-08-01
resourceId 资源的完全限定 ID 2019-03-11
sku VM 映像的特定 SKU 2017-04-02
securityProfile.secureBootEnabled 标识是否在 VM 上启用了 UEFI 安全启动 2020-06-01
securityProfile.virtualTpmEnabled 标识是否在 VM 上启用了虚拟受信任的平台模块 (TPM) 2020-06-01
securityProfile.encryptionAtHost 确定是否在 VM 上启用了主机加密 2021-11-01
securityProfile.securityType 确定 VM 是否为受信任的 VM 2021-12-13
storageProfile 请参阅下面的“存储配置文件” 2019-06-01
subscriptionId 虚拟机的 Azure 订阅 2017-08-01
tags 虚拟机的标记 2017-08-01
tagsList 格式化为 JSON 数组以方便编程分析的标记 2019-06-04
userData 创建 VM 时指定的一组数据，在预配期间或之后使用（Base64 编码） 2021-01-01
version VM 映像的版本 2017-04-02
virtualMachineScaleSet.id 虚拟机所属的使用灵活业务流程创建的虚拟机规模集的 ID。 此字段不适用于使用统一业务流程创建的虚拟机规模集。 2021-03-01
vmId VM 的唯一标识符。 引用的博客仅适用于具有 SMBIOS < 2.6 的 VM。 对于 SMBIOS >= 2.6 的 VM，来自 DMI 的 UUID 以 little-endian 格式显示，因此不需要切换字节。 2017-04-02
vmScaleSetName 你的规模集的虚拟机规模集名称 2017-12-01
vmSize VM 大小 2017-04-02
zone 虚拟机的可用性区域 2017-12-01

† 此版本尚未完全可用，可能并非在所有区域中都受支持。

存储配置文件

VM 的存储配置文件分为三个类别：映像引用、操作系统磁盘和数据磁盘，以及本地临时磁盘的其他对象。

映像引用对象包含有关 OS 映像的以下信息，请注意，映像可能来自平台也可能来自市场，但不会同时来自这两者：

数据 说明 引入的版本
id 资源 ID 2019-06-01
offer 平台或市场映像的套餐 2019-06-01
publisher 平台或市场映像的发布者 2019-06-01
sku 平台或市场映像的 SKU 2019-06-01
version 映像的版本 2019-06-01
communityGalleryImageId 社区映像的资源 ID，否则为空 2023-07-01
sharedGalleryImageId 直接共享映像的资源 ID，否则为空 2023-07-01
exactVersion 社区映像或直接共享映像的版本 2023-07-01

OS 磁盘对象包含有关 VM 所用 OS 磁盘的以下信息：

数据 说明
caching 缓存要求
createOption 有关 VM 创建方式的信息
diffDiskSettings 临时磁盘设置
diskSizeGB 磁盘大小 (GB)
image 源用户映像虚拟硬盘
managedDisk 托管磁盘参数
name 磁盘名称
vhd 虚拟硬盘
writeAcceleratorEnabled 磁盘上是否启用了 writeAccelerator

数据磁盘阵列包含附加到 VM 的数据磁盘列表。 每个数据磁盘对象包含以下信息：

数据 说明 引入的版本
bytesPerSecondThrottle* 磁盘读取/写入配额（字节） 2021-05-01
caching 缓存要求 2019-06-01
createOption 有关 VM 创建方式的信息 2019-06-01
diffDiskSettings 临时磁盘设置 2019-06-01
diskCapacityBytes* 磁盘大小（字节） 2021-05-01
diskSizeGB 磁盘大小 (GB) 2019-06-01
encryptionSettings 磁盘的加密设置 2019-06-01
image 源用户映像虚拟硬盘 2019-06-01
isSharedDisk* 确定磁盘是否可在资源间共享 2021-05-01
isUltraDisk 标识数据磁盘是否为超级磁盘 2021-05-01
lun 磁盘的逻辑单元号 2019-06-01
managedDisk 托管磁盘参数 2019-06-01
name 磁盘名称 2019-06-01
opsPerSecondThrottle* 磁盘读取/写入配额 (IOPS) 2021-05-01
osType 磁盘中包含的 OS 类型 2019-06-01
vhd 虚拟硬盘 2019-06-01
writeAcceleratorEnabled 磁盘上是否启用了 writeAccelerator 2019-06-01

**这些字段仅针对超级磁盘填充；它们是非超级磁盘中的空字符串。

加密设置 blob 包含有关如何加密磁盘的数据（如果磁盘已加密）：

数据 说明 引入的版本
diskEncryptionKey.sourceVault.id 磁盘加密密钥的位置 2021-11-01
diskEncryptionKey.secretUrl 机密的位置 2021-11-01
keyEncryptionKey.sourceVault.id 密钥加密密钥的位置 2021-11-01
keyEncryptionKey.keyUrl 密钥的位置 2021-11-01

资源磁盘对象包含附加到 VM 的本地临时磁盘（如果有）的大小（以 KB 为单位）。 如果 VM 没有本地临时磁盘，则此值为 0。

数据 说明 引入的版本
resourceDisk.size VM 的本地临时磁盘大小（以 KB 为单位） 2021-02-01

Network

数据 说明 引入的版本
ipv4.privateIpAddress VM 的本地 IPv4 地址 2017-04-02
ipv4.publicIpAddress VM 的公共 IPv4 地址 2017-04-02
subnet.address VM 的子网地址 2017-04-02
subnet.prefix 子网前缀，例如 24 2017-04-02
ipv6.ipAddress VM 的本地 IPv6 地址 2017-04-02
macAddress VM mac 地址 2017-04-02

注意

不保证网络调用返回有序的 nic。

获取用户数据

在创建新 VM 时，可以指定一组要在 VM 预配期间或之后使用的数据，并通过 IMDS 进行检索。 在此处检查端到端用户的数据体验。

若要设置用户数据，请使用此处的快速入门模板。 下面的示例介绍如何通过 IMDS 检索此数据。 此功能随 2021-01-01 及更高版本一并发布。

注意

安全声明：IMDS 对 VM 上的所有应用程序开放，敏感数据不应放在用户数据中。

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

示例 1：跟踪 Azure 上正在运行的 VM

作为服务提供商，可能需要跟踪运行软件的 VM 数目，或者代理需要跟踪 VM 的唯一性。 为了能够获取 VM 的唯一 ID，请使用实例元数据服务中的 vmId 字段。

请求

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"

响应

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

示例 2：不同数据副本的放置

对于某些方案，不同数据副本的放置至关重要。 例如，对于 HDFS 副本放置或者对于通过业务流程协调程序进行的容器放置，可能需要知道正在运行 VM 的 platformFaultDomain 和 platformUpdateDomain。 你还可以使用实例的可用性区域来做出这些决策。 可以通过 IMDS 直接查询此数据。

请求

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"

响应

0

示例 3：获取 VM 标记

VM 标记包含在实例/计算/标记终结点下的实例 API。 标记可能已应用到 Azure VM 中，以逻辑方式将其归入一个分类。 可使用以下请求检索分配给 VM 的标记。

请求

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"

响应

Department:IT;ReferenceNumber:123456;TestStatus:Pending

tags 字段是带有用分号分隔的标记的字符串。 如果标记本身使用了分号，则此输出可能会出现问题。 如果编写分析程序以编程方式提取标记，则应该依赖于 tagsList 字段。 tagsList 字段是不带分隔符的 JSON 数组，因此更易于分析。 可以使用以下请求检索分配给 VM 的 tagsList。

请求

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

响应

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

示例 4：在支持案例期间获取有关 VM 的详细信息

作为服务提供商，你可能会接到支持电话，了解有关 VM 的详细信息。 请求客户共享计算元数据可以提供基本信息，以支持专业人员了解有关 Azure 上的 VM 类型。

请求

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

响应

注意

此响应是 JSON 字符串。 以下示例响应显示清晰，可供阅读。

{
    "azEnvironment": "AZURECHINACLOUD",
    "extendedLocation": {
      "type": "edgeZone",
      "name": "microsoftlosangeles"
    },
    "evictionPolicy": "",
    "additionalCapabilities": {
        "hibernationEnabled": "false"
    },
    "hostGroup": {
      "id": "testHostGroupId"
    },
    "isHostCompatibilityLayerVm": "true",
    "licenseType":  "Windows_Client",
    "location": "chinanorth",
    "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": "chinanorth3-az1",
    "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.cn/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.cn/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"
}

示例 5：获取运行 VM 的 Azure 环境

Azure 具有各种主权云，如由世纪互联运营的 Microsoft Azure。 有时你需要使用 Azure 环境来做出一些运行时决策。 以下示例显示了如何实现此行为。

请求

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"

响应

AzureChinaCloud

此处列出了 Azure 环境的云和值。

云 Azure 环境
全球所有公开上市的 Azure 区域 AzurePublicCloud
Azure Government AzureUSGovernmentCloud
由世纪互联运营的 Microsoft Azure AzureChinaCloud
Azure 德国 AzureGermanCloud

示例 6：检索网络信息

请求

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

响应

{
  "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"
    }
  ]
}

示例 7：检索公共 IP 地址

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"

备注

证明数据

获取“经过证明的”数据

IMDS 可帮助确保提供的数据来自 Azure。 Microsoft 会对此信息的一部分进行签名，以便你可以确认 Azure 市场中的映像是你正在 Azure 上运行的映像。

GET /metadata/attested/document

参数

名称 必需/可选 说明
api-version 必需 用于处理请求的版本。
nonce 可选 用作加密 nonce 的 10 位字符串。 如果未提供值，则 IMDS 使用当前的 UTC 时间戳。

响应

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

签名 blob 是 pkcs7 签名的文档版本。 它包含用于签名的证书以及某些特定于 VM 的详细信息。

对于使用 Azure 资源管理器创建的 VM，该文档包括 vmId、sku、nonce、subscriptionId、文档创建和到期的 timeStamp 以及关于映像的计划信息。 该计划信息只针对 Azure 市场映像进行填充。

对于使用经典部署模型创建的 VM，仅保证填充 vmId 和 subscriptionId。 可以从响应中提取证书，并使用它来确认响应是否有效并来自 Azure。

解码的文档包含以下字段：

数据 说明 引入的版本
licenseType Azure 混合权益许可证的类型。 这仅适用于启用了 AHB 的 VM。 2020-09-01
nonce 可以随请求提供的可选字符串。 如果未提供 nonce，则会使用当前的协调世界时时间戳。 2018-10-01
plan Azure 市场映像计划。 包含计划 ID（名称）、产品映像或产品/服务（产品）和发布者 ID（发布者）。 2018-10-01
timestamp.createdOn 创建签名文档时的 UTC 时间戳 2018-20-01
timestamp.expiresOn 签名文档到期时的 UTC 时间戳 2018-10-01
vmId VM 的唯一标识符 2018-10-01
subscriptionId 虚拟机的 Azure 订阅 2019-04-30
sku VM 映像的特定 SKU（与实例元数据终结点 [/metadata/instance] 中的 compute/sku 属性相关联） 2019-11-01

注意

对于经典（非 Azure 资源管理器）VM，只保证填充 vmId。

示例文档：

{
   "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"
}

签名验证指南

验证签名时，应确认签名是使用 Azure 中的证书创建的。 这是通过验证证书使用者可选名称 (SAN) 来完成的。

示例 SAN DNS Name=chinanorth2.metadata.azure.cn, DNS Name=metadata.azure.cn

注意

公有云和每个主权云的域将有所不同。

云 SAN 中的域
全球所有公开上市的 Azure 区域 *.metadata.azure.com
Azure Government *.metadata.azure.us
由世纪互联运营的 Microsoft Azure *.metadata.azure.cn
Azure 德国 *.metadata.microsoftazure.de

注意

对于域，证书可能不完全匹配。 因此，认证验证应接受任何子域（例如，在中国云正式发布区域中，接受 *.metadata.azure.cn）。

建议不要对中间证书进行证书固定。 如需进一步的指导，请参阅证书固定 - 证书固定和 Azure 服务。 请注意，Azure 实例元数据服务不会为将来的证书颁发机构更改提供通知。 相反，对于所有将来的更新，必须遵循集中的 Azure 证书颁发机构详细信息一文。

示例 1：验证 VM 是否在 Azure 中运行

Azure 市场供应商希望确保其软件仅获许在 Azure 中运行。 如果有人将 VHD 复制到本地环境，则供应商需要能够检测到此操作。 通过 IMDS，这些供应商可以获取能确保只从 Azure 响应的签名数据。

注意

此示例需要安装 jq 实用工具。

验证

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

验证签名是否来自 Azure 并检查证书链中是否存在错误。

# 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

如果在初始请求中提供了 nonce 参数，则可以比较签名文档中的 nonce。

托管标识

可以在 VM 上启用由系统分配的托管标识。 还可以将一个或多个用户分配的托管标识分配给 VM。 然后，可以从 IMDS 请求托管标识的令牌。 使用这些令牌来通过其他 Azure 服务（如 Azure Key Vault）进行身份验证。

有关启用此功能的详细步骤，请参阅获取访问令牌。

负载均衡器元数据

将虚拟机或虚拟机集实例置于 Azure 标准负载均衡器后面时，可以使用 IMDS 检索与负载均衡器和实例相关的元数据。 有关详细信息，请参阅检索负载均衡器信息。

计划事件

可以使用 IMDS 获取计划事件的状态。 然后，用户可以指定一组在发生这些事件时要运行的操作。 有关详细信息，请参阅 Linux 计划事件或 Windows 计划事件。

不同语言的示例代码

下表列出了在 VM 中使用不同语言调用 IMDS 的相关示例：

语言 示例
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

错误和调试

如果找不到某个数据元素，或者请求的格式不正确，则实例元数据服务将返回标准 HTTP 错误。 例如：

HTTP 状态代码 原因
200 OK 请求已成功。
400 Bad Request 查询叶节点时缺少 Metadata: true 标头或缺少参数 format=json
404 Not Found 请求的元素不存在
405 Method Not Allowed 此终结点不支持 HTTP 方法（谓词）。
410 Gone 在一段时间后重试最长 70 秒
429 Too Many Requests 已超出 API 速率限制
500 Service Error 请稍后重试

常见问题

  • 出现了 400 Bad Request, Required metadata header not specified 错误。 这是什么意思呢？

    • IMDS 需要在请求中传递标头 Metadata: true。 将该标头传入 REST 调用将允许访问 IMDS。

  • 为什么我无法获取我的 VM 的计算信息？

    • 当前 IMDS 仅支持 Azure 资源管理器创建的实例。

  • 我一段时间以前通过 Azure 资源管理器创建了 VM。 为什么我无法看到计算元数据信息？

    • 如果在 2016 年 9 月之后创建了 VM，请添加标记以开始查看计算元数据。 如果在 2016 年 9 月之前创建了 VM，请在 VM 实例中添加或删除扩展或数据磁盘以刷新元数据。

  • 用户数据与自定义数据是否相同？

    • 用户数据提供了与自定义数据类似的功能，使你可以将自己的元数据传递给 VM 实例。 不同之处在于，用户数据是通过 IMDS 进行检索的，并且在 VM 实例的整个生存期内保持不变。 现有的自定义数据功能将继续按照本文所述正常运行。 但是，只能通过本地系统文件夹获取自定义数据，而不能通过 IMDS 获取。

  • 为什么我看不到为新版本填充的任何数据？

    • 如果在 2016 年 9 月之后创建了 VM，请添加标记以开始查看计算元数据。 如果在 2016 年 9 月之前创建了 VM，请在 VM 实例中添加或删除扩展或数据磁盘以刷新元数据。

  • 我为什么会收到错误 500 Internal Server Error 或 410 Resource Gone？

    • 请重试请求。 有关详细信息，请参阅临时故障处理。 如果问题持续存在，请在 Azure 门户中为 VM 创建支持问题。

  • 这是否适用于规模集实例？

    • 是，IMDS 适用于规模集实例。

  • 我在规模集中更新了我的标记，但它们未出现在实例中（与单实例 VM 不同）。 我哪里出错了吗？

    • 目前，规模集的标记仅在重启、重置映像或更改实例的磁盘时向 VM 显示。

  • 为什么我在 instance/compute 详细信息中看不到 VM 的 SKU 信息？

    • 对于通过 Azure 市场创建的自定义映像，Azure 平台不会保留自定义映像的 SKU 信息以及从自定义映像创建的任何 VM 的详细信息。 这是由设计决定的，因此所述信息不会出现在 VM 的 instance/compute 详细信息中。

  • 为什么我在调用服务时会发生请求超时？

    • 必须从分配给 VM 的主要网卡的主 IP 地址进行元数据调用。 此外，如果你更改了路由，则 VM 的本地路由表中必须存在 169.254.169.254/32 地址的路由。

      1. 转储本地路由表并查找 IMDS 条目。 例如：

        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. 验证是否存在 169.254.169.254 的路由，并记下相应的网络接口（例如 172.16.69.7）。

      3. 转储接口配置并查找与路由表中引用的接口相对应的接口，注明 MAC（物理）地址。

        ipconfig /all

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

Connection-specific DNS Suffix  . : xic3mnxjiefupcwr1mcs1rjiqa.cx.internal.chinacloudapp.cn
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. 确认该接口对应于 VM 的主 NIC 和主 IP。 可以通过在 Azure 门户中查看网络配置，或通过 Azure CLI 查找它来找到主 NIC 和 IP。 请记下专用 IP（如果使用 CLI，还要记下 MAC 地址）。 下面是一个 PowerShell CLI 示例：

        $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. 如果它们不匹配，请更新路由表，以使主 NIC 和 IP 成为目标。

  • Windows Server 中的故障转移群集

    • 使用故障转移群集查询 IMDS 时，有时需要向路由表添加路由。 下面介绍如何操作：

      1. 使用管理员特权打开命令提示符。

      2. 运行以下命令，并记下 IPv4 路由表中网络目标 (0.0.0.0) 接口的地址。

      route print

      注意

      以下示例输出来自启用了故障转移群集的 Windows Server VM。 为简单起见，输出仅包含 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

      运行以下命令并使用网络目标 (0.0.0.0) 接口的地址，在此示例中为 10.0.1.10。

      route add 169.254.169.254/32 10.0.1.10 metric 1 -p

支持

如果在多次尝试后无法获取元数据响应，则可以在 Azure 门户中创建支持问题。

产品反馈

你可以访问此网址，在“虚拟机”>“实例元数据服务”下向我们的用户反馈渠道提供产品反馈和想法

后续步骤