Toegang tot de Azure Monitor Log Analytics-API

Artikel
11/05/2024

U kunt een queryaanvraag verzenden naar een werkruimte met behulp van het Azure Monitor Log Analytics-eindpunt https://api.loganalytics.azure.com. Voor toegang tot het eindpunt moet u zich verifiëren via Microsoft Entra-id.

Notitie

Het api.loganalytics.io eindpunt wordt vervangen door api.loganalytics.azure.com. Het api.loganalytics.io eindpunt wordt nog steeds ondersteund voor de toekomst die u kunt zien.

Verifiëren met een demo-API-sleutel

Als u snel de API wilt verkennen zonder Microsoft Entra-verificatie, gebruikt u de demonstratiewerkruimte met voorbeeldgegevens, die ondersteuning biedt voor API-sleutelverificatie.

Als u query's wilt verifiëren en uitvoeren voor de voorbeeldwerkruimte, gebruikt DEMO_WORKSPACE u deze als {workspace-id} en geeft u de API-sleutel DEMO_KEYdoor.

Als de toepassings-id of de API-sleutel onjuist is, retourneert de API-service een fout 403 (Verboden).

De API-sleutel DEMO_KEY kan op drie verschillende manieren worden doorgegeven, afhankelijk van of u een header, de URL of basisverificatie wilt gebruiken:

Aangepaste header: Geef de API-sleutel op in de aangepaste header X-Api-Key.
Queryparameter: Geef de API-sleutel op in de URL-parameter api_key.
Basisverificatie: geef de API-sleutel op als gebruikersnaam of wachtwoord. Als u beide opgeeft, moet de API-sleutel zich in de gebruikersnaam bevinden.

In dit voorbeeld worden de werkruimte-id en API-sleutel in de header gebruikt:

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

Openbaar API-eindpunt

Het openbare API-eindpunt is:

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

waarbij geldt:

api-versie: de API-versie. De huidige versie is 'v1'.
workspaceId: uw werkruimte-id.

De query wordt doorgegeven in de aanvraagbody.

Voorbeeld:

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

Verificatie instellen

Voor toegang tot de API registreert u een client-app bij Microsoft Entra-id en vraagt u een token aan.

Registreer een app in Microsoft Entra-id.
Selecteer API-machtigingen op de overzichtspagina van de app.
Selecteer Een machtiging toevoegen.
Zoek op het tabblad API's die mijn organisatie gebruikt naar Log Analytics en selecteer Log Analytics-API in de lijst.
Selecteer Gedelegeerde machtigingen.
Schakel het selectievakje Data.Read in.
Selecteer Machtigingen toevoegen.

Nu uw app is geregistreerd en machtigingen heeft om de API te gebruiken, verleent u uw app toegang tot uw Log Analytics-werkruimte.

Selecteer op de overzichtspagina van uw Log Analytics-werkruimte de optie Toegangsbeheer (IAM).
Selecteer Roltoewijzing toevoegen.
Selecteer de rol Lezer en selecteer vervolgens Leden.
Kies Leden selecteren op het tabblad Leden.
Voer de naam van uw app in het vak Selecteren in.
Selecteer uw app en kies Selecteren.
Selecteer Controleren + toewijzen.
Nadat u de Active Directory-instellingen en werkruimtemachtigingen hebt voltooid, vraagt u een autorisatietoken aan.

Notitie

In dit voorbeeld hebben we de rol Lezer toegepast. Deze rol is een van de vele ingebouwde rollen en kan meer machtigingen bevatten dan u nodig hebt. Er kunnen meer gedetailleerde rollen en machtigingen worden gemaakt. Zie Toegang tot Log Analytics-werkruimten beheren voor meer informatie.

Een autorisatietoken aanvragen

Voordat u begint, moet u ervoor zorgen dat u alle waarden hebt die nodig zijn om de aanvraag te maken. Voor alle aanvragen is het volgende vereist:

Uw Microsoft Entra-tenant-id.
Uw werkruimte-id.
Uw Microsoft Entra-client-id voor de app.
Een Microsoft Entra-clientgeheim voor de app.

De Log Analytics-API ondersteunt Microsoft Entra-verificatie met drie verschillende OAuth2-stromen voor Microsoft Entra-id:

Clientreferenties
Autorisatiecode
Impliciet

Stroom voor clientreferenties

In de clientreferentiestroom wordt het token gebruikt met het Log Analytics-eindpunt. Er wordt één aanvraag gedaan om een token te ontvangen met behulp van de referenties die zijn opgegeven voor uw app in de vorige stap wanneer u een app registreert in Microsoft Entra ID.

Gebruik resource=https://api.loganalytics.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

Gebruik het token in aanvragen voor het Log Analytics-eindpunt:

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

Voorbeeld van een reactie:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

Stroom voor autorisatiecode

De belangrijkste OAuth2-stroom die wordt ondersteund, is via autorisatiecodes. Voor deze methode zijn twee HTTP-aanvragen vereist om een token te verkrijgen waarmee de Azure Monitor Log Analytics-API moet worden aangeroepen. Er zijn twee URL's, met één eindpunt per aanvraag. De indelingen worden beschreven in de volgende secties.

URL voor autorisatiecode (GET-aanvraag)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Wanneer een aanvraag wordt ingediend bij de autorisatie-URL, is de client_id de toepassings-id van uw Microsoft Entra-app, gekopieerd uit het eigenschappenmenu van de app. De redirect_uri is de startpagina/aanmeldings-URL van dezelfde Microsoft Entra-app. Wanneer een aanvraag is geslaagd, wordt u met dit eindpunt omgeleid naar de aanmeldingspagina die u bij de registratie hebt opgegeven, met de autorisatiecode die is toegevoegd aan de URL. Zie het volgende voorbeeld:

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

Op dit moment hebt u een autorisatiecode verkregen die u nu nodig hebt om een toegangstoken aan te vragen.

URL van autorisatiecodetoken (POST-aanvraag)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Alle waarden zijn hetzelfde als voorheen, met enkele toevoegingen. De autorisatiecode is dezelfde code die u in de vorige aanvraag hebt ontvangen na een geslaagde omleiding. De code wordt gecombineerd met de sleutel die is verkregen uit de Microsoft Entra-app. Als u de sleutel niet hebt opgeslagen, kunt u deze verwijderen en een nieuwe maken via het toetsentabblad van het app-menu Microsoft Entra. Het antwoord is een JSON-tekenreeks die het token bevat met het volgende schema. Typen worden aangegeven voor de tokenwaarden.

Voorbeeldrespons:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

Het toegangstokengedeelte van dit antwoord is wat u presenteert aan de Log Analytics-API in de Authorization: Bearer header. U kunt het vernieuwingstoken ook in de toekomst gebruiken om een nieuwe access_token en refresh_token te verkrijgen wanneer uw gegevens verlopen zijn. Voor deze aanvraag zijn de indeling en het eindpunt:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Voorbeeldrespons:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

Impliciete codestroom

De Log Analytics-API ondersteunt de impliciete OAuth2-stroom. Voor deze stroom is slechts één aanvraag vereist, maar er kan geen vernieuwingstoken worden verkregen.

Impliciete code autoriseren URL

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

Een geslaagde aanvraag produceert een omleiding naar uw omleidings-URI met het token in de URL:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

Deze access_token kan worden gebruikt als de Authorization: Bearer headerwaarde wanneer deze wordt doorgegeven aan de Log Analytics-API om aanvragen te autoriseren.

Meer informatie

U vindt hier documentatie over OAuth2 met Microsoft Entra:

Delen via