Aangepaste metrische gegevens opnemen voor een Azure-resource met behulp van de REST API

Artikel
11/05/2024

In dit artikel leest u hoe u aangepaste metrische gegevens voor Azure-resources verzendt naar het metrische azure Monitor-archief via de REST API. Wanneer de metrische gegevens zich in Azure Monitor bevinden, kunt u alle dingen doen die u doet met standaardgegevens. U kunt bijvoorbeeld grafieken en waarschuwingen genereren en de metrische gegevens doorsturen naar andere externe hulpprogramma's.

Notitie

Met de REST API kunnen alleen aangepaste metrische gegevens voor Azure-resources worden verzonden. Gebruik Application Insights om metrische gegevens te verzenden voor resources in andere omgevingen of on-premises.

REST-aanvragen verzenden om aangepaste metrische gegevens op te nemen

Wanneer u aangepaste metrische gegevens naar Azure Monitor verzendt, moet elk gegevenspunt of elke waarde die in de metrische gegevens wordt gerapporteerd, de volgende informatie bevatten.

Verificatietoken
Onderwerp
Regio
Tijdstempel
Naamruimte
Naam
Dimensiesleutels
Dimensiewaarden
Metrische waarden

Verificatie

Voor het verzenden van aangepaste metrische gegevens naar Azure Monitor heeft de entiteit die de metrische gegevens verzendt een geldig Microsoft Entra-token nodig in de Bearer-header van de aanvraag. Ondersteunde manieren om een geldig Bearer-token te verkrijgen:

Beheerde identiteiten voor Azure-resources. U kunt een beheerde identiteit gebruiken om resources machtigingen te geven om bepaalde bewerkingen uit te voeren. Een voorbeeld is dat een resource metrische gegevens over zichzelf kan verzenden. Aan een resource, of de beheerde identiteit, kunnen machtigingen voor de uitgever van metrische gegevens voor metrische gegevens worden verleend voor een andere resource. Met deze machtiging kan de beheerde identiteit ook metrische gegevens voor andere resources verzenden.
Microsoft Entra-service-principal. In dit scenario kunnen aan een Microsoft Entra-toepassing of -service machtigingen worden toegewezen om metrische gegevens over een Azure-resource te verzenden. Om de aanvraag te verifiëren, valideert Azure Monitor het toepassingstoken met behulp van openbare Microsoft Entra-sleutels. De bestaande rol Monitoring Metrics Publisher heeft deze machtiging al. Deze is beschikbaar in Azure Portal.

De service-principal kan, afhankelijk van de resources waarvoor aangepaste metrische gegevens worden verzonden, de rol Monitoring Metrics Publisher krijgen op het vereiste bereik. Voorbeelden zijn een abonnement, resourcegroep of specifieke resource.

Tip

Wanneer u een Microsoft Entra-token aanvraagt om aangepaste metrische gegevens te verzenden, moet u ervoor zorgen dat de doelgroep of resource waarvoor het token wordt aangevraagd, is https://monitoring.azure.com/. Zorg ervoor dat u de afsluitende slash opneemt.

Een autorisatietoken ophalen

Zodra u uw beheerde identiteit of service-principal hebt gemaakt en de machtigingen van De uitgever van metrische bewakingsgegevens hebt toegewezen, kunt u een autorisatietoken ophalen. Bij het aanvragen van een token opgeven resource: https://monitoring.azure.com.

Haal een verificatietoken op met een van de volgende methoden:

CLI
REST-API
SDK

Wanneer u een token aanvraagt, moet u een resource parameter opgeven. De resource parameter is de URL van de resource die u wilt openen.

Resources zijn onder meer:

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

Een token ophalen met behulp van een REST-aanvraag

Gebruik de volgende REST API-aanroep om een token op te halen. Deze aanvraag maakt gebruik van een client-id en clientgeheim om de aanvraag te verifiëren. De client-id en het clientgeheim worden verkregen wanneer u uw toepassing registreert bij Microsoft Entra-id. Zie Een app registreren om autorisatietokens aan te vragen en met API's te werken voor meer informatie

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'

De hoofdtekst van het antwoord wordt weergegeven in de volgende indeling:

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

Een token ophalen met behulp van Azure CLI

Als u een token wilt ophalen met behulp van CLI, kunt u de volgende opdracht gebruiken

az account get-access-token

Zie az account get-access-token voor meer informatie

Een token ophalen met behulp van de SDK's

In de volgende codevoorbeelden ziet u hoe u een token opvragen met behulp van:

C#
NodeJS
Python

C#

De volgende code laat zien hoe u een token opvragen met behulp van Azure. Identiteitsbibliotheek Vereist een client-id en clientgeheim om de aanvraag te verifiëren.

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;

U kunt ook de klasse DefaultAzureCredential gebruiken om een token op te halen. Deze methode gebruikt de standaardReferenties van Azure om de aanvraag te verifiëren en vereist geen client-id of clientgeheim.

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

U kunt ook de referenties van uw beheerde identiteit of service-principal als volgt opgeven:

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" }));

Zie De standaardklasseAzureCredential voor meer informatie

Node.js

Zie JavaScript- en NodeJS-apps verifiëren voor Azure-services met behulp van de Azure SDK voor JavaScript voor JavaScript voor informatie over verificatie

De volgende code laat zien hoe u een token opvragen met behulp van de klasse DefaultAzureCredential. Deze methode gebruikt de standaardReferenties van Azure om de aanvraag te verifiëren en vereist geen client-id of clientgeheim.

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

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

U kunt de InteractiveBrowserCredential klasse ook gebruiken om de referenties op te halen. Deze methode biedt een browsergebaseerde verificatieervaring waarmee gebruikers zich kunnen verifiëren met Azure-services.

Zie DefaultAzureCredential Class en InteractiveBrowserCredential Class voor meer informatie

U kunt ook de klasse ClientSecretCredential gebruiken om een token op te halen. Voor deze methode zijn een client-id en clientgeheim vereist om de aanvraag te verifiëren.

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

Zie ClientSecretCredential Class voor meer informatie

Python

from azure.identity import DefaultAzureCredential

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

Zie DefaultAzureCredential Class en InteractiveBrowserCredential Class voor meer informatie

U kunt ook de klasse ClientSecretCredential gebruiken om een token op te halen. Voor deze methode zijn een client-id en clientgeheim vereist om de aanvraag te verifiëren.

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)

Zie ClientSecretCredential Class voor meer informatie

Sla het toegangstoken op uit het antwoord voor gebruik in de volgende HTTP-aanvragen.

Onderwerp

De onderwerpeigenschap legt vast voor welke Azure-resource-id de aangepaste metriek wordt gerapporteerd. Deze informatie wordt gecodeerd in de URL van de API-aanroep. Elke API kan metrische waarden verzenden voor slechts één Azure-resource.

Notitie

U kunt geen aangepaste metrische gegevens verzenden op basis van de resource-id van een resourcegroep of abonnement.

Regio

De regio-eigenschap legt de Azure-regio vast waarvoor de resource waarvoor u metrische gegevens verzendt, wordt geïmplementeerd. Metrische gegevens moeten worden verzonden naar hetzelfde regionale Azure Monitor-eindpunt als de regio waarin de resource wordt geïmplementeerd. Aangepaste metrische gegevens voor een vm die in VS - west is geïmplementeerd, moeten bijvoorbeeld worden verzonden naar het regionale Azure Monitor-eindpunt westUS. De regiogegevens worden ook gecodeerd in de URL van de API-aanroep.

Tijdstempel

Elk gegevenspunt dat naar Azure Monitor wordt verzonden, moet worden gemarkeerd met een tijdstempel. Met deze tijdstempel worden de datum en tijd vastgelegd waarop de metrische waarde wordt gemeten of verzameld. Azure Monitor accepteert metrische gegevens met tijdstempels tot 20 minuten in het verleden en 5 minuten in de toekomst. De tijdstempel moet de ISO 8601-indeling hebben.

Naamruimte

Naamruimten zijn een manier om vergelijkbare metrische gegevens te categoriseren of te groeperen. Met behulp van naamruimten kunt u isolatie bereiken tussen groepen met metrische gegevens die verschillende inzichten of prestatie-indicatoren kunnen verzamelen. U hebt bijvoorbeeld een naamruimte met de naam contosomemorymetrics waarmee metrische gegevens over geheugengebruik worden bijgehouden die uw app profileert. Een andere naamruimte met de naam contosoapptransaction kan alle metrische gegevens over gebruikerstransacties in uw toepassing bijhouden.

Naam

De naameigenschap is de naam van de metrische waarde die wordt gerapporteerd. Meestal is de naam beschrijvend genoeg om te bepalen wat er wordt gemeten. Een voorbeeld is een metrische waarde die het aantal geheugenbytes meet dat op een VIRTUELE machine wordt gebruikt. Het kan een metrische naam hebben, zoals geheugenbytes in gebruik.

Dimensiesleutels

Een dimensie is een sleutel-waardepaar waarmee andere kenmerken worden beschreven over de metrische gegevens die worden verzameld. Met behulp van de andere kenmerken kunt u meer informatie verzamelen over de metrische gegevens, zodat u meer inzicht krijgt.

De metrische waarde Geheugenbytes in gebruik kan bijvoorbeeld een dimensiesleutel hebben met de naam Proces waarmee wordt vastgelegd hoeveel bytes geheugen elk proces op een VIRTUELE machine verbruikt. Met deze sleutel kunt u de metrische waarde filteren om te zien hoeveel geheugenspecifieke processen worden gebruikt of om de vijf belangrijkste processen te identificeren op basis van geheugengebruik.

Dimensies zijn optioneel en niet alle metrische gegevens hebben dimensies. Een aangepaste metriek kan maximaal 10 dimensies hebben.

Dimensiewaarden

Wanneer u een metrische gegevenspunt rapporteert, is er voor elke dimensiesleutel voor de gerapporteerde metriek een bijbehorende dimensiewaarde. U kunt bijvoorbeeld het geheugen rapporteren dat ContosoApp op uw VIRTUELE machine gebruikt:

De metrische naam is geheugenbytes in gebruik.
De dimensiesleutel zou Proces zijn.
De dimensiewaarde wordt ContosoApp.exe.

Wanneer u een metrische waarde publiceert, kunt u slechts één dimensiewaarde per dimensiesleutel opgeven. Als u hetzelfde geheugengebruik voor meerdere processen op de VIRTUELE machine verzamelt, kunt u meerdere metrische waarden voor die tijdstempel rapporteren. Elke metrische waarde zou een andere dimensiewaarde opgeven voor de dimensiesleutel Proces .

Hoewel dimensies optioneel zijn, zijn de bijbehorende dimensiewaarden verplicht als een metrische post dimensiesleutels definieert.

Metrische waarden

Azure Monitor slaat alle metrische gegevens op met een granulariteitsinterval van 1 minuut. Gedurende een bepaalde minuut moet een metrische waarde mogelijk meerdere keren worden genomen. Een voorbeeld is CPU-gebruik. Of een metrische waarde moet mogelijk worden gemeten voor veel discrete gebeurtenissen, zoals latenties voor aanmeldingstransacties.

Als u het aantal onbewerkte waarden wilt beperken waarvoor u moet verzenden en betalen in Azure Monitor, moet u de geaggregeerde waarden lokaal vooraf aggregeren en verzenden:

Min: De minimaal waargenomen waarde van alle monsters en metingen gedurende de minuut.
Max: De maximaal waargenomen waarde van alle monsters en metingen gedurende de minuut.
Som: De som van alle waargenomen waarden uit alle monsters en metingen gedurende de minuut.
Aantal: Het aantal monsters en metingen dat in de minuut is genomen.

Notitie

Azure Monitor biedt geen ondersteuning voor het definiëren van eenheden voor een aangepaste metrische waarde.

Als er bijvoorbeeld gedurende een minuut vier aanmeldingstransacties voor uw app waren, kunnen de resulterende gemeten latenties voor elk van deze transacties het volgende zijn:

Transactie 1	Transactie 2	Transactie 3	Transactie 4
7 ms	4 ms	13 ms	16 ms

Vervolgens is de resulterende publicatie van metrische gegevens naar Azure Monitor:

Min. 4
Max: 16
Som: 40
Aantal: 4

Als uw toepassing niet lokaal kan worden samengevoegd en elke afzonderlijke steekproef of gebeurtenis direct na de verzameling moet verzenden, kunt u de onbewerkte metingswaarden verzenden. Telkens wanneer een aanmeldingstransactie plaatsvindt in uw app, publiceert u bijvoorbeeld een metrische waarde naar Azure Monitor met slechts één meting. Voor een aanmeldingstransactie die 12 milliseconden duurde, zou de metrische publicatie dus zijn:

Min. 12
Max: 12
Som: 12
Aantal: 1

Met dit proces kunt u gedurende een bepaalde minuut meerdere waarden verzenden voor dezelfde combinatie van metrische gegevens/dimensies. Azure Monitor neemt vervolgens alle onbewerkte waarden die gedurende een bepaalde minuut worden verzonden en aggregeren ze.

Voorbeeld van aangepaste publicatie met metrische gegevens

Maak in het volgende voorbeeld een aangepaste metriek met de naam Geheugenbytes in Gebruik onder de metrische naamruimte Geheugenprofiel voor een virtuele machine. De metrische waarde heeft één dimensie met de naam Proces. Voor de tijdstempel worden metrische waarden verzonden voor twee processen.

Sla de volgende JSON op in een bestand met de naam custommetric.json op uw lokale computer. Werk de tijdparameter zo bij dat deze zich binnen de afgelopen 20 minuten bevindt. U kunt geen metrische gegevens in de winkel plaatsen die meer dan 20 minuten oud zijn.

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

Verzend de volgende HTTP POST-aanvraag met behulp van de volgende variabelen:

location: Implementatieregio van de resource waarvoor u metrische gegevens verzendt.
resourceId: Resource-id van de Azure-resource waarop u de metrische gegevens bijhoudt.

accessToken: Het autorisatietoken dat is verkregen uit de stap Een autorisatietoken ophalen .

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

Uw metrische gegevens weergeven

Meld u aan bij het Azure-portaal.
Selecteer Controleren in het menu aan de linkerkant.
Selecteer metrische gegevens op de pagina Monitor.
Wijzig de aggregatieperiode in Afgelopen uur.
Selecteer in de vervolgkeuzelijst Bereik de resource waarvoor u de metrische waarde verzendt.
Selecteer geheugenprofiel in de vervolgkeuzelijst Metrische naamruimte.
Selecteer in de vervolgkeuzelijst Metrische gegevens geheugenbytes in gebruik.

Probleemoplossing

Als u een foutbericht ontvangt met een deel van het proces, kunt u de volgende informatie over probleemoplossing overwegen:

Als u geen metrische gegevens kunt uitgeven voor een abonnement of resource, controleert u of aan uw toepassing of service-principal de rol Monitoring Metrics Publisher is toegewezen in Access Control (IAM).
Controleer of het aantal dimensienamen overeenkomt met het aantal waarden.
Controleer of u metrische gegevens verzendt naar het juiste regionale Azure Monitor-eindpunt. Als uw resource bijvoorbeeld is geïmplementeerd in VS - west, moet u metrische gegevens verzenden naar het regionale eindpunt VS - west.
Controleer of de tijdstempel binnen de afgelopen 20 minuten valt.
Controleer of de tijdstempel de ISO 8601-indeling heeft.
Controleer of de naam van de metrische waarde geldig is. Het mag bijvoorbeeld geen spaties bevatten.

Volgende stappen

Meer informatie over aangepaste metrische gegevens.

Delen via

Aangepaste metrische gegevens opnemen voor een Azure-resource met behulp van de REST API

REST-aanvragen verzenden om aangepaste metrische gegevens op te nemen

Verificatie

Een autorisatietoken ophalen

Een token ophalen met behulp van een REST-aanvraag

Een token ophalen met behulp van Azure CLI

Een token ophalen met behulp van de SDK's

C#

Node.js

Python

Onderwerp

Regio

Tijdstempel

Naamruimte

Naam

Dimensiesleutels

Dimensiewaarden

Metrische waarden

Voorbeeld van aangepaste publicatie met metrische gegevens

Uw metrische gegevens weergeven

Probleemoplossing

Volgende stappen

Feedback

Aanvullende resources