你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 REST API 为 Azure 资源引入自定义指标

项目
10/15/2024

本文展示了如何通过 REST API 将 Azure 资源的自定义指标发送到 Azure Monitor 指标存储。当这些指标位于 Azure Monitor 中时，你可以像对标准指标一样对其执行所有操作。例如，可以生成图表和警报，并将指标路由到其他外部工具。

注意

REST API 仅允许为 Azure 资源发送自定义指标。若要发送其他环境中或本地的资源的指标，可以使用 Application Insights。

发送 REST 请求以引入自定义指标

将自定义指标发送到 Azure Monitor 时，指标中报告的每个数据点或值都必须包括以下信息。

身份验证令牌
主题
区域
Timestamp
命名空间
Name
维度键
维度值
指标值

身份验证

若要将自定义指标提交到 Azure Monitor，提交指标的实体需在请求的 Bearer 标头中提供有效的 Microsoft Entra 令牌。获取有效持有者令牌的支持方法包括：

Azure 资源的托管标识可使用托管标识授予资源执行某些操作的权限。例如，允许资源发出有关其自身的指标。可为某个资源或其托管标识授予针对另一资源的“监视指标发布者”权限。获取此权限后，其托管标识也能发出其他资源的指标。
Microsoft Entra 服务主体。在此方案中，可向某个 Microsoft Entra 应用程序或服务分配发出有关 Azure 资源的指标的权限。为了对请求进行身份验证，Azure Monitor 将使用 Microsoft Entra 公钥来验证应用程序令牌。现有的“监视指标发布者”角色已拥有此权限。可在 Azure 门户中使用此权限。

可以根据服务主体要发出哪些资源的自定义指标，在所需的范围为该服务主体授予“监视指标发布者”角色。范围的示例包括订阅、资源组或特定资源。

提示

请求 Microsoft Entra 令牌以发出自定义指标时，请确保请求该令牌的受众或资源是 https://monitoring.azure.com/。请务必包含尾部斜线。

获取授权令牌

创建托管标识或服务主体并分配“监视指标发布者”权限后，可以获取授权令牌。请求令牌时，请指定 resource: https://monitoring.azure.com。

使用以下任一方法获取身份验证令牌：

CLI
REST API
SDK

在请求令牌时，必须提供 resource 参数。 resource 参数是你要访问的资源的 URL。

资源包括：

https://management.azure.com
https://api.loganalytics.io
https://monitoring.azure.com

使用 REST 请求获取令牌

使用以下 REST API 调用来获取令牌。此请求使用客户端 ID 和客户端密码对请求进行身份验证。客户端 ID 和客户端密码是在你向 Microsoft Entra ID 注册应用程序时获取的。有关详细信息，请参阅注册应用以请求授权令牌并使用 API

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

响应正文格式如下：

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

使用 Azure CLI 获取令牌

若要使用 CLI 获取令牌，可以使用以下命令

az account get-access-token

有关详细信息，请参阅 az account get-access-token

使用 SDK 获取令牌

以下代码示例演示了如何使用以下语言获取令牌：

C#
NodeJS
Python

C#

以下代码示例演示了如何使用 Azure 获取令牌。标识库它需要使用客户端 ID 和客户端密码对请求进行身份验证。

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

另外，你也可以使用 DefaultAzureCredential 类来获取令牌。此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

还可以如下所示指定托管标识或服务主体凭据：

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

有关详细信息，请参阅 DefaultAzureCredential 类

Node.js

有关使用 JavaScript 和 NodeJS 进行身份验证的信息，请参阅如何使用 Azure SDK for JavaScript 向 Azure 服务证明 JavaScript 应用的身份

以下示例演示了如何使用 DefaultAzureCredential 类获取令牌。此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

你还可以使用 InteractiveBrowserCredential 类来获取凭据。此方法提供了基于浏览器的身份验证体验供用户用来向 Azure 服务进行身份验证。

有关详细信息，请参阅 DefaultAzureCredential 类和 InteractiveBrowserCredential 类

另外，你也可以使用 ClientSecretCredential 类来获取令牌。此方法需要使用客户端 ID 和客户端密码对请求进行身份验证。

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

有关详细信息，请参阅 ClientSecretCredential 类

Python

以下示例演示了如何使用 DefaultAzureCredential 类获取令牌。此方法使用默认 Azure 凭据对请求进行身份验证，不需要客户端 ID 或客户端密码。

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

你还可以使用 InteractiveBrowserCredential 类来获取凭据。此方法提供了基于浏览器的身份验证体验供用户用来向 Azure 服务进行身份验证。

有关详细信息，请参阅 DefaultAzureCredential 类和 InteractiveBrowserCredential 类

另外，你也可以使用 ClientSecretCredential 类来获取令牌。此方法需要使用客户端 ID 和客户端密码对请求进行身份验证。

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

有关详细信息，请参阅 ClientSecretCredential 类

保存响应中的访问令牌，以便在以下 HTTP 请求中使用。

使用者

使用者属性捕获为其报告自定义指标的 Azure 资源 ID。此信息将在 API 调用的 URL 中进行编码。每个 API 只能提交一个 Azure 资源的指标值。

注意

无法针对资源组或订阅的资源 ID 发出自定义指标。

区域

区域属性捕获针对其发出指标的资源所部署到的 Azure 区域。必须将指标发出到与资源部署区域所在的同一 Azure Monitor 区域终结点。例如，部署在美国西部的 VM 的自定义指标必须发送到美国西部区域 Azure Monitor 终结点。区域信息也在 API 调用的 URL 中编码。

时间戳

发送到 Azure Monitor 的每个数据点必须带有时间戳标记。此时间戳捕获测量或收集指标值的日期和时间。 Azure Monitor 接受带有过去最多 20 分钟和将来最多 5 分钟时间戳的指标数据。时间戳必须采用 ISO 8601 格式。

命名空间

命名空间可将类似的指标分类或分组到一起。使用命名空间能够在可收集不同见解或性能指标的指标组之间实现隔离。例如，可以使用名为 contosomemorymetrics 的命名空间来跟踪用于分析应用的内存用量指标，并使用名为 contosoapptransaction 的另一个命名空间来跟踪有关应用程序中用户事务的所有指标。

名称

名称属性是要报告的指标名称。通常，该名称具有足够的自述性，可帮助识别所要测量的指标。以测量 VM 上所用内存字节数的指标为例。该指标可以使用类似于“已使用内存字节数”的名称。

维度键

维度是一个键/值对，帮助描述有关收集的指标的其他特征。使用其他特征可以收集用于提供更深入见解的指标的详细信息。

例如，“已使用内存字节数”指标可以包含名为“进程”的维度键，用于捕获 VM 上的每个进程消耗的内存字节数。使用此键可以筛选指标，以查看特定的进程使用了多少内存，或者识别内存用量最高的 5 个进程。

维度是可选的，并不是所有指标都具有维度。一个自定义指标最多可以包含 10 个维度。

维度值

报告指标数据点时，所报告的指标的每个维度键都有一个对应的维度值。例如，可以报告 VM 上 ContosoApp 使用的内存：

指标名称是“已使用内存字节数”。
维度键是“进程”。
维度值是“ContosoApp.exe”。

发布指标值时，只能为每个维度键指定一个维度值。如果收集 VM 上多个进程的相同“内存使用率”指标，则可以报告该时间戳的多个指标值。每个指标值将为“进程”维度键指定不同的维度值。

虽然维度是可选的，但如果一个指标的发布定义了维度键，则相应的维度值是必需的。

指标值

Azure Monitor 以 1 分钟的粒度间隔存储所有指标。在给定的分钟内，一个指标可能需要采样多次。例如 CPU 利用率。或者，可能需要为许多离散事件（例如登录事务延迟）测量一个指标。

若要在 Azure Monitor 中限制发出和支付的原始值数目，可在本地预先聚合并发出聚合值：

最小值：在给定的分钟内从所有样本和测量值中观测到的最小值。
最大值：在给定的分钟内从所有样本和测量值中观测到的最大值。
总和：在给定的分钟内从所有样本和测量值中观测到的所有值的总和。
计数：在给定的分钟内创建的样本和测量值数目。

注意

Azure Monitor 不支持为自定义指标定义单位。

例如，如果应用在一分钟内有四次登录事务，则每个事务测量到的延迟可能为：

事务 1	事务 2	事务 3	事务 4
7 毫秒	4 毫秒	13 毫秒	16 毫秒

那么发布到 Azure Monitor 的最终指标将是：

最小值：4
最大值：16
总和：40
计数：4

如果应用程序无法在本地预先聚合，并需要在收集时立即发出每个离散样本或事件，则你可以发出原始测量值。例如，每当应用中出现登录事务时，就可以向 Azure Monitor 发布包含单个测量值的指标。因此，对于花费了 12 毫秒的登录事务，指标发布内容为：

最小值：12
最大值：12
总和：12
计数：1

使用此过程可在给定分钟内发出相同指标/维度的组合的多个值。然后，Azure Monitor 将会提取给定分钟内发出的所有原始值，并将其聚合。

样本自定义指标发布

以下示例在虚拟机的“内存分析”指标命名空间下创建名为“已使用内存字节数”的自定义指标。该指标包含名为“进程”的单个维度。对于时间戳，发出两个进程的指标值。

将以下 JSON 存储到本地计算机上名为 custommetric.json 的文件中。更新时间参数，使其范围在过去 20 分钟内。无法将已过去了 20 分钟的指标放入到存储中。

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

使用以下变量提交以下 HTTP POST 请求：

location：要为其发布指标的资源的部署区域。
resourceId：你要跟踪其指标的 Azure 资源的资源 ID。

accessToken：从“获取授权令牌”步骤中获取的授权令牌。

curl -X POST 'https://<location>.monitoring.azure.com/<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

查看指标

登录到 Azure 门户。
在左侧菜单中选择“监视”。
在“监视”页上选择“指标” 。
将聚合时限更改为“过去 1 小时”。
在“范围”下拉列表中，选择为其发送指标的资源。
在“指标命名空间”下拉列表中，选择“内存分析”。
在“指标”下拉列表中，选择“已使用内存字节数”。

疑难解答

如果在过程的某个部分中收到错误消息，请考虑使用以下故障排除信息：

如果无法针对订阅或资源组或者资源发布指标，请检查是否在访问控制 (IAM) 中向应用程序或服务主体分配了“监视指标发布者”角色。
检查维度名称的数量是否与值的数量匹配。
检查是否向正确的 Azure Monitor 区域终结点发布指标。例如，如果资源部署在美国西部，则必须向美国西部区域终结点发布指标。
检查时间戳是否是在过去 20 分钟内。
检查时间戳是否采用 ISO 8601 格式。
检查指标名称是否有效。例如，它不能包含空格。

后续步骤

详细了解自定义指标。

通过