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默认数据格式其他格式

/instancejsontext

/scheduledeventsjson无

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

复制

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"

}

]

}

}

实例元数据数据类别

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

数据说明引入的版本

locationVM 在其中运行的 Azure 区域2017-04-02

nameVM 的名称2017-04-02

offer为 VM 映像提供信息。 此值只适用于 Azure 映像库中部署的图像。2017-04-02

publisherVM 映像的发布者2017-04-02

skuVM 映像的特定 SKU2017-04-02

versionVM 映像的版本2017-04-02

osTypeLinux 或 Windows2017-04-02

platformUpdateDomain正在运行 VM 的更新域2017-04-02

platformFaultDomain正在运行 VM 的容错域2017-04-02

vmIdVM 的唯一标识符2017-04-02

vmSizeVM 大小2017-04-02

subscriptionId虚拟机的 Azure 订阅2017-08-01

tags虚拟机的标记2017-08-01

resourceGroupName虚拟机的资源组2017-08-01

placementGroupId虚拟机规模集的放置组2017-08-01

ipv4/privateIpAddressVM 的本地 IPv4 地址2017-04-02

ipv4/publicIpAddressVM 的公共 IPv4 地址2017-04-02

subnet/addressVM 的子网地址2017-04-02

subnet/prefix子网前缀，例如 242017-04-02

macAddressVM mac 地址2017-04-02

scheduledevents当前在公共预览版中提供。请参阅scheduledevents2017-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"

响应

复制

0

在支持案例期间获取有关 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 中的不同语言调用元数据服务的示例

语言示例

Rubyhttps://github.com/Microsoft/azureimds/blob/master/IMDSSample.rb

Go Langhttps://github.com/Microsoft/azureimds/blob/master/imdssample.go

Pythonhttps://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

JavaScripthttps://github.com/Microsoft/azureimds/blob/master/IMDSSample.js

PowerShellhttps://github.com/Microsoft/azureimds/blob/master/IMDSSample.ps1

Bashhttps://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 门户中创建支持问题。

后续步骤                 立即访问http://market.azure.cn

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