使用 REST API 內嵌 Azure 資源的自訂計量

發行項
11/05/2024

本文將說明如何透過 REST API 將 Azure 資源的自訂計量傳送至 Azure 監視器計量存放區。在計量位於 Azure 監視器時，您可以執行您使用標準計量執行的所有作業。例如，您可以產生圖表和警示，並將計量路由至其他外部工具。

注意

REST API 僅允許傳送 Azure 資源的自訂計量。若要在其他環境或內部部署中傳送資源的計量，您可以使用 Application Insights。

傳送 REST 要求以擷取自訂計量

當您將自訂計量傳送至 Azure 監視器時，計量中所報告的每個資料點或值都必須包含下列資訊。

驗證權杖
主體
區域
Timestamp
Namespace
名稱
維度索引鍵
維度值
計量值

驗證

若要將自訂計量提交至 Azure 監視器，提交計量的實體在要求的 Bearer 標頭中需要有效的 Microsoft Entra 權杖。支援的有效持有人權杖取得方式包括：

Azure 資源的受控識別。您可以使用受控識別來提供資源執行特定作業的權限。例如，允許資源發出本身相關的計量。您也可以將其他資源的監視計量發行者權限提供給資源 (或其受控識別)。透過此權限，受控識別也可以發出其他資源的計量。
Microsoft Entra 服務主體。在此案例中，可以將權限指派給 Microsoft Entra 應用程式或服務，以發出 Azure 資源的相關計量。若要驗證要求，Azure 監視器會使用 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 呼叫來取得權杖。此要求會使用用戶端識別碼和用戶端密碼來驗證要求。當您向 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 取得權杖。身分識別程式庫需要用戶端識別碼和用戶端密碼才能驗證要求。

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 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

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 的相關資訊，請參閱如何使用適用於 JavaScript 的 Azure SDK 向 Azure 服務驗證 JavaScript 應用程式

下列程式碼示範如何使用 DefaultAzureCredential 類別來取得權杖。此方法會使用預設的 Azure 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

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

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

您也可以使用 InteractiveBrowserCredential 類別來取得認證。此方法提供瀏覽器型驗證體驗，讓使用者能夠向 Azure 服務進行驗證。

如需詳細資訊，請參閱 DefaultAzureCredential 類別和 InteractiveBrowserCredential 類別

或者，您可以使用 ClientSecretCredential 類別來取得權杖。此方法需要用戶端識別碼和用戶端密碼才能驗證要求。

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 認證來驗證要求，而且不需要用戶端識別碼或用戶端密碼。

from azure.identity import DefaultAzureCredential

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

您也可以使用 InteractiveBrowserCredential 類別來取得認證。此方法提供瀏覽器型驗證體驗，讓使用者能夠向 Azure 服務進行驗證。

如需詳細資訊，請參閱 DefaultAzureCredential 類別和 InteractiveBrowserCredential 類別

或者，您可以使用 ClientSecretCredential 類別來取得權杖。此方法需要用戶端識別碼和用戶端密碼才能驗證要求。

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 資源識別碼。此資訊會在 API 呼叫的 URL 中進行編碼。每個 API 只能為單一的 Azure 資源提交計量值。

注意

您無法針對資源群組或訂用帳戶的資源識別碼發出自訂計量。

區域

當您為資源發出計量時，區域屬性會擷取該資源部署所在的 Azure 區域。發出計量的目標 Azure 監視器端點所在區域，必須和資源的部署區域相同。例如，部署在美國西部的 VM，其自訂計量必須傳送至美國西部的區域 Azure 監視器端點。區域資訊也是編碼在 API 呼叫的 URL 中。

時間戳記

傳送至 Azure 監視器每個資料點都必須以時間戳記標記。此時間戳記會擷取該計量值的測量或收集日期與時間。 Azure 監視器接受時間戳記為過去 20 分鐘內和未來 5 分鐘內的計量資料。時間戳記必須是 ISO 8601 格式。

Namespace

命名空間是將類似計量分類或分組的方法。您可以使用命名空間，將收集不同見解或效能指標的計量群組隔離。比方說，您可能有一個命名空間，名稱為 contosomemorymetrics，其可追蹤記憶體使用計量以分析應用程式。另一個命名空間，名稱為 contosoapptransaction，其可追蹤應用程式中使用者交易的所有相關計量。

名稱

名稱屬性是計量報告的名稱。通常名稱的描述就足以協助識別所測量的項目。舉例來說，若是可測量 VM 上所用記憶體位元組數目的計量，其計量名稱可能為「使用中的記憶體位元組」。

維度索引鍵

維度是索引鍵/值組，可協助描述所收集計量的其他相關特性。您可以使用其他特性，收集更多關於計量的資訊，以取得更深入的見解。

例如，「使用中的記憶體位元組」計量的維度索引鍵可能稱為「處理序」，可擷取 VM 上每個處理序使用的記憶體位元組數目。您可以使用此索引鍵來篩選計量，以查看使用多少個記憶體特定處理序，或識別記憶體使用量的前 5 名處理序。

維度是選用的，並非所有計量都有維度。自訂計量最多可以有 10 個維度。

維度值

當您報告計量資料點時，報告計量上的每個維度索引鍵都會有一個對應的維度值。例如，您可能想要報告 VM 上的 ContosoApp 記憶體使用量：

計量名稱會是「使用中的記憶體位元組」。
維度索引鍵會是「處理序」。
維度值會是 ContosoApp.exe。

當發佈計量值時，每個維度索引鍵只能指定單一維度值。如果您會對 VM 上的多個處理序收集同一個記憶體使用量，您可以報告該時間戳記的多個計量值。每個計量值都會為處理序維度索引鍵指定不同的維度值。

雖然維度是選擇性的，但如果計量張貼有定義維度索引鍵，則相對應的維度值屬於必要項目。

計量值

Azure 監視器會儲存 1 分鐘資料粒度間隔內的所有計量。在指定的分鐘內，計量可能需要取樣數次。例如根據 CPU 使用率。或者，有些計量可能需要針對許多不連續事件進行測量，例如登入交易延遲。

若要限制您在 Azure 監視器中必須發出及支付的原始值數目，請在本機預先彙總，然後再將彙總的值發出：

最小值︰在該分鐘期間的所有樣本及測量中觀察到的最小值。
最大值︰在該分鐘期間的所有樣本及測量中觀察到的最大值。
總和︰在該分鐘期間的所有樣本及測量中所有觀察值的總和。
計數：在該分鐘期間的樣本及測量數目。

注意

Azure 監視器不支援定義自訂計量的「單位」。

例如，如果在一分鐘時段內，您的應用程式有四個登入交易，每個交易所產生的測量延遲分別為：

交易 1	交易 2	交易 3	交易 4
7 毫秒	4 毫秒	13 毫秒	16 毫秒

對 Azure 監視器產生的計量發行集如下：

最小值：4
最大值：16
總和：40
計數：4

如果您的應用程式無法在本機預先彙總，而必須在收集後立即發出每個離散樣本或事件，您可以發出原始測量值。例如，應用程式上每次發生登入交易時，您發佈到 Azure 監視器的計量只有單一測量結果。因此，對於花費 12 毫秒的登入交易，其計量發行集為：

最小值：12
最大值：12
總和：12
計數：1

透過此處理序，您可以在指定的分鐘時段內，為相同的計量/維度組合發出多個值。然後，Azure 監視器會接收指定分鐘時段內發出的所有原始值，並將其彙總在一起。

範例自訂計量發行集

在下列範例中，會在虛擬機器的計量命名空間「記憶體設定檔」下，建立稱為「使用中的記憶體位元組」的自訂計量。計量有一個稱為「處理序」的維度。針對時間戳記，系統會針對兩個處理序發出計量值。

在您的本機電腦上將下列 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 資源的資源識別碼。

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 監視器區域端點發出計量。例如，如果您的資源部署在美國西部，您必須向美國西部區域端點發出計量。
檢查時間戳記是否在過去 20 分鐘內。
檢查時間戳記是否為 ISO 8601 格式。
檢查計量名稱是否有效。例如，其不能包含空格。

下一步

深入了解自訂計量。

共用方式為