Delen via

Toegang tot de Azure Monitor Log Analytics-API

U kunt een query indienen in 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.

Opmerking

Het api.loganalytics.io endpoint wordt vervangen door api.loganalytics.azure.com. Het api.loganalytics.io eindpunt wordt nog steeds ondersteund voor de nabije toekomst.

Verifieer met een demo API-sleutel

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

Gebruik DEMO_WORKSPACE als de {workspace-id} en voer de API-sleutel DEMO_KEY in om authenticatie uit te voeren en queries op de voorbeeldwerkruimte uit te voeren.

Als ofwel de Applicatie-ID of de API-sleutel onjuist is, retourneert de API-service een 403 (Verboden) foutmelding.

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

  • Aangepaste header: Geef de API-sleutel op in de aangepaste headerX-Api-Key.
  • Queryparameter: Voer de API-sleutel in de URL-parameter api_key.
  • Basic authentication: Geef de API-sleutel op als gebruikersnaam of wachtwoord. Als u beide verstrekt, moet de API-sleutel in de gebruikersnaam staan.

Dit voorbeeld gebruikt het werkruimte-ID en de API-sleutel in de header.

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

Openbare API-eindpunt

Het openbare API-eindpunt is:

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

Waar:

  • api-version: De API-versie. De huidige versie is v1.
  • workspaceId: uw werkruimte-id.

Opmerking

De beta API-versie is afgeschaft. Voor meer informatie, zie Migrate from using batch and beta query APIs.

De query wordt in de aanvraagtekst geplaatst.

Voorbeeld:

https://api.loganalytics.azure.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1

Body:
{
    "query": "Usage"
}

Authenticatie instellen

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

  1. Register van een app in Microsoft Entra ID.

  2. Op de overzichtspagina van de app selecteer je API-machtigingen.

  3. Selecteer Een toestemming toevoegen.

  4. Zoek op het tabblad APIs die mijn organisatie gebruikt naar Log Analytics en selecteer Log Analytics API in de lijst.

    Een schermafbeelding die de pagina Verzoek API-machtigingen toont.

  5. Selecteer Gedelegeerde machtigingen.

  6. Selecteer het selectievakje Data.Read.

  7. Selecteer Machtigingen toevoegen.

    Een schermafbeelding die de voortzetting van de pagina Aanvraag API-machtigingen toont.

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

  1. Vanaf de overzichtspagina van uw Log Analytics werkruimte selecteert u Access control (IAM).

  2. Selecteer Roltoewijzing toevoegen.

    A schermopname van de pagina Toegangsbeheer voor een Log Analytics workspace.

  3. Selecteer de lezer rol en selecteer vervolgens leden.

    Een schermopname met de pagina Roltoewijzing toevoegen voor een Log Analytics-werkruimte.

  4. Op het tabblad Leden kies je Leden selecteren.

  5. Voer de naam van uw app in in het Select-veld.

  6. Selecteer je app en kies Selecteren.

  7. Selecteer Beoordelen en toewijzen.

    A schermopname van het deelvenster Leden selecteren op de pagina Roltoewijzing toevoegen voor een Log Analytics workspace.

  8. Nadat u klaar bent met het instellen van de Active Directory en werkruimtemachtigingen, vraagt u een autorisatietoken aan.

Opmerking

Voor dit voorbeeld hebben we de rol Lezer toegepast. Deze rol is een van de vele ingebouwde rollen en kan meer toestemmingen bevatten dan u nodig heeft. Meer granulairdere rollen en machtigingen kunnen worden gecreëerd. Zie Toegang tot Log Analytics werkruimten voor meer informatie.

Vraag een autorisatietoken aan

Voordat u begint, zorg ervoor dat u alle waarden hebt die nodig zijn om het verzoek succesvol te maken. Alle verzoeken vereisen:

  • 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 Microsoft Entra ID OAuth2 stromen:

  • Klantinloggegevens
  • Autorisatiecode
  • Impliciet

Client-referentieproces

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 registert in Microsoft Entra ID.

Gebruik resource=https://api.loganalytics.azure.com.

Verkrijg een authenticatietoken met behulp van een van de volgende methoden:

  • CLI (Command Line Interface)
  • REST-API
  • SDK

Verkrijg een token met behulp van een REST-aanroep

Gebruik de volgende REST API-aanroep om een token te verkrijgen. Dit verzoek gebruikt een client-ID en een client-geheim om het verzoek te authenticeren. De client-id en het clientgeheim worden verkregen wanneer u uw toepassing registreert bij Microsoft Entra ID. Voor meer informatie, zie Een app registreren om autorisatietokens aan te vragen en met API's te werken.

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={resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}'

De antwoordtekst verschijnt in het volgende formaat:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "{resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

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

Voorbeeldantwoord:

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

Autorisatiecode-stroom

De belangrijkste ondersteunde OAuth2-stroom is via authorization codes. 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 verzoek. Hun formaten worden in de volgende secties beschreven.

Autorisatiecode URL (GET request)

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 er een aanvraag wordt ingediend bij de autorisatie-URL, is de client_id de toepassings-id uit 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 punt heeft u een autorisatiecode verkregen, die u nu nodig heeft om een toegangstoken aan te vragen.

URL voor autorisatiecode-token (POST-verzoek)

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 het vorige verzoek hebt ontvangen na een succesvolle 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 op het tabblad Toetsen van het menu Microsoft Entra app. De reactie is een JSON-string die de token bevat volgens het volgende schema. Typen worden aangegeven voor de tokenwaarden.

Voorbeeldantwoord:

{
    "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 header Authorization: Bearer. Je kunt het vernieuwings-token in de toekomst ook gebruiken om een nieuwe toegangstoken en vernieuwings-token te verkrijgen wanneer de jouwe zijn verlopen. Voor dit verzoek zijn het formaat 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>

Voorbeeldantwoord:

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

Client-referentieproces

De Log Analytics-API ondersteunt de OAuth2 clientreferenties stroom. Deze stroom is geschikt voor service-naar-service-aanroepen waarbij geen tussenkomst van de gebruiker is vereist.

Tokenaanvraag voor clientcredentials

POST https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<app-client-id>
&scope=https://api.loganalytics.io/.default
&client_secret=<app-client-secret>
&grant_type=client_credentials

Voorbeeldantwoord:

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax"
}

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

Meer informatie

U vindt hier documentatie over OAuth2 met Microsoft Entra:

Volgende stappen

  • Last updated on