Azure 实例元数据服务

Azure 实例元数据服务提供有关可用于管理和配置虚拟机的正在运行的虚拟机实例的信息。这包括 SKU、网络配置和即将发生的维护事件等信息。若要详细了解可用信息类型，请参阅元数据类别。

Azure 的实例元数据服务是一个 REST 终结点，所有创建的 IaaS VM 可通过 Azure Resource Manager 访问此终结点。该终结点位于已知不可路由的 IP 地址 (169.254.169.254)，该地址只能从 VM 中访问。

Important

此服务在所有 Azure 区域中提供有正式版。它会定期接收更新，发布有关虚拟机实例的新信息。此页反映了最新可用的数据类别。

服务可用性

此服务在所有 Azure 区域中提供有可用的正式版。并非所有 API 版本在所有 Azure 区域中可用。

区域	可用性？	支持的版本
全球所有公开上市的 Azure 区域	正式版	2017-04-02, 2017-08-01
Azure 美国政府	正式版	2017-04-02
Azure 中国	正式版	2017-04-02
Azure 德国	正式版	2017-04-02

当有服务更新和/或有可用的新支持版本时，此表将更新

若要试用实例元数据服务，请在上述区域中从 Azure 资源管理器或 Azure 门户创建一个 VM，并按照以下示例操作。

使用情况

版本控制

已对实例元数据服务进行了版本控制。版本是必需的，全局 Azure 上的当前版本为 2017-08-01。当前支持的版本为（2017-04-02、2017-08-01）

Note

支持的计划事件的前一预览版 {latest} 发布为 api-version。此格式不再受支持，并且将在未来弃用。

添加更新的版本时，早期版本仍可供访问以保持兼容性（如果脚本依赖于特定的数据格式）。但是请注意，在服务正式发布之后，先前的预览版本 (2017-03-01) 可能不再可用。

使用标头

查询实例元数据服务时，必须提供标头 Metadata: true 以确保不会意外重定向请求。

检索元数据

实例元数据可用于运行使用 Azure Resource Manager 创建/管理的 VM。使用以下请求访问虚拟机实例的所有数据类别：

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-04-02"

Note

所有实例元数据查询都区分大小写。

数据输出

默认情况下，实例元数据服务会返回 JSON 格式的数据 (Content-Type: application/json)。但是，如果提出请求，不同 API 可以其他格式返回数据。下表是有关 API 可支持的其他数据格式的参考。

API	默认数据格式	其他格式
/instance	json	text
/scheduledevents	json	无

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

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-04-02&format=text"

“安全”

此实例元数据服务终结点只能从不可路由的 IP 地址上正在运行的虚拟机实例中访问。此外，任何包含X-Forwarded-For标头的请求都会被服务拒绝。还要求请求包含 Metadata: true 标头以确保实际请求是直接计划好的，不属于意外重定向。

错误

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

HTTP 状态代码	原因
200 正常
400 错误的请求	缺少 `Metadata: true` 标头
404 未找到	请求的元素不存在
不允许 405 方法	仅支持 `GET` 和 `POST` 请求
429 请求次数过多	该 API 当前支持每秒最多 5 个查询
500 服务错误	请稍后重试

示例

Note

所有 API 响应都是 JSON 字符串。以下所有响应示例都以美观的形式输出以提高可读性。

检索网络信息

请求

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance/network?api-version=2017-08-01"

响应

Note

此响应是 JSON 字符串。以下响应示例以美观的形式输出以提高可读性。

复制

{

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

    }

  ]

}

检索公共 IP 地址

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-04-02&format=text"

检索实例的所有元数据

请求

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-08-01"

响应

Note

此响应是 JSON 字符串。以下响应示例以美观的形式输出以提高可读性。

复制

{

  "compute": {

    "location": "chinanorth",

    "name": "avset2",

    "offer": "UbuntuServer",

    "osType": "Linux",

    "placementGroupId": "",

    "platformFaultDomain": "1",

    "platformUpdateDomain": "1",

    "publisher": "Canonical",

    "resourceGroupName": "myrg",

    "sku": "16.04-LTS",

    "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",

    "tags": "",

    "version": "16.04.201708030",

    "vmId": "13f56399-bd52-4150-9748-7190aae1ff21",

    "vmSize": "Standard_D1"

  },

  "network": {

    "interface": [

      {

        "ipv4": {

          "ipAddress": [

            {

              "privateIpAddress": "10.1.2.5",

              "publicIpAddress": "X.X.X.X"

            }

          ],

          "subnet": [

            {

              "address": "10.1.2.0",

              "prefix": "24"

            }

          ]

        },

        "ipv6": {

          "ipAddress": []

        },

        "macAddress": "000D3A36DDED"

      }

    ]

  }

}

在 Windows 虚拟机中检索元数据

请求

可以通过 Powershell 实用工具 curl 在 Windows 中检索实例元数据：

复制

curl -H @{'Metadata'='true'} http://169.254.169.254/metadata/instance?api-version=2017-04-02 | select -ExpandProperty Content

或通过 Invoke-RestMethodcmdlet：

复制

Invoke-RestMethod -Headers @{"Metadata"="true"} -URI http://169.254.169.254/metadata/instance?api-version=2017-04-02 -Method get

响应

Note

此响应是 JSON 字符串。以下响应示例以美观的形式输出以提高可读性。

复制

{

  "compute": {

    "location": "chinanorth",

    "name": "SQLTest",

    "offer": "SQL2016SP1-WS2016",

    "osType": "Windows",

    "platformFaultDomain": "0",

    "platformUpdateDomain": "0",

    "publisher": "MicrosoftSQLServer",

    "sku": "Enterprise",

    "version": "13.0.400110",

    "vmId": "453945c8-3923-4366-b2d3-ea4c80e9b70e",

    "vmSize": "Standard_DS2"

  },

  "network": {

    "interface": [

      {

        "ipv4": {

          "ipAddress": [

            {

              "privateIpAddress": "10.0.1.4",

              "publicIpAddress": "X.X.X.X"

            }

          ],

          "subnet": [

            {

              "address": "10.0.1.0",

              "prefix": "24"

            }

          ]

        },

        "ipv6": {

          "ipAddress": [

          ]

        },

        "macAddress": "002248020E1E"

      }

    ]

  }

}

实例元数据数据类别

可通过实例元数据服务获取以下数据类别：

数据	说明	引入的版本
location	VM 在其中运行的 Azure 区域	2017-04-02
name	VM 的名称	2017-04-02
offer	为 VM 映像提供信息。此值只适用于 Azure 映像库中部署的图像。	2017-04-02
publisher	VM 映像的发布者	2017-04-02
sku	VM 映像的特定 SKU	2017-04-02
version	VM 映像的版本	2017-04-02
osType	Linux 或 Windows	2017-04-02
platformUpdateDomain	正在运行 VM 的更新域	2017-04-02
platformFaultDomain	正在运行 VM 的容错域	2017-04-02
vmId	VM 的唯一标识符	2017-04-02
vmSize	VM 大小	2017-04-02
subscriptionId	虚拟机的 Azure 订阅	2017-08-01
tags	虚拟机的标记	2017-08-01
resourceGroupName	虚拟机的资源组	2017-08-01
placementGroupId	虚拟机规模集的放置组	2017-08-01
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
macAddress	VM mac 地址	2017-04-02
scheduledevents	当前在公共预览版中提供。请参阅 scheduledevents	2017-03-01

用法的示例方案

跟踪 Azure 上正在运行的 VM

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

请求

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute/vmId?api-version=2017-04-02&format=text"

响应

复制

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

基于容错/更新域放置容器、数据分区

对于某些方案，不同数据副本的放置至关重要。例如，对于 HDFS 副本放置或者对于通过 orchestrator 放置容器，可能需要知道正在运行 VM 的 platformFaultDomain 和 platformUpdateDomain。可以直接通过实例元数据服务查询此数据。

请求

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute/platformFaultDomain?api-version=2017-04-02&format=text"

响应

复制

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

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

请求

复制

curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute?api-version=2017-04-02"

响应

Note

此响应是 JSON 字符串。以下响应示例以美观的形式输出以提高可读性。

复制

{

  "compute": {

    "location": "chinanorth",

    "name": "IMDSCanary",

    "offer": "RHEL",

    "osType": "Linux",

    "platformFaultDomain": "0",

    "platformUpdateDomain": "0",

    "publisher": "RedHat",

    "sku": "7.2",

    "version": "7.2.20161026",

    "vmId": "5c08b38e-4d57-4c23-ac45-aca61037f084",

    "vmSize": "Standard_DS2"

  }

}

使用 VM 中的不同语言调用元数据服务的示例

语言	示例
Ruby	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.rb
Go Lang	https://github.com/Microsoft/azureimds/blob/master/imdssample.go
Python	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.py
C++	https://github.com/Microsoft/azureimds/blob/master/IMDSSample-windows.cpp
C#	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.cs
JavaScript	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.js
PowerShell	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.ps1
Bash	https://github.com/Microsoft/azureimds/blob/master/IMDSSample.sh

常见问题

我收到错误 400 Bad Request, Required metadata header not specified。这是什么意思呢？
- 实例元数据服务需要在请求中传递标头 Metadata: true。将该标头传入 REST 调用将允许访问实例元数据服务。
为什么我无法获取我的 VM 的计算信息？
- 当前实例元数据服务仅支持 Azure Resource Manager 创建的实例。将来可能添加对云服务 VM 的支持。
我刚才通过 Azure Resource Manager 创建了我的虚拟机。为什么我无法看到计算元数据信息？
- 对于 2016 年 9 月之后创建的所有 VM，请添加标记以开始查看计算元数据。对于早期 VM（在 2016 年 9 月之前创建），请在 VM 中添加/删除扩展或数据磁盘以刷新元数据。
我看不到为新版本 2017-08-01 填充的任何数据
- 对于 2016 年 9 月之后创建的所有 VM，请添加标记以开始查看计算元数据。对于早期 VM（在 2016 年 9 月之前创建），请在 VM 中添加/删除扩展或数据磁盘以刷新元数据。
我为什么会收到错误 500 Internal Server Error？
- 请根据指数后退系统重试请求。如果问题持续出现，请联系 Azure 支持部门。
在何处共享其他问题/评论？
- 请将评论发布到 http://feedback.azure.com。
这是否适用于虚拟机规模集实例？
- 是的，元数据服务可用于规模集实例。
如何获取服务支持？
- 若要获取服务支持，请针对无法在长时间重试后获得元数据响应的 VM，在 Azure 门户中创建支持问题。

后续步骤

详细了解由实例元数据服务提供的公共预览版 scheduledevents API。

立即访问http://market.azure.cn