Toegang tot de Azure Monitor Log Analytics-API

Artikel
10/18/2023

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.

Bijvoorbeeld:

   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 het https://api.loganalytics.azure.com eindpunt.

Token-URL van clientreferenties (POST-aanvraag)

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

Een geslaagde aanvraag ontvangt een toegangstoken in het antwoord:

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

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: