Zugriff auf die Azure Monitor Log Analytics API

Artikel
10/25/2023

Sie können eine Abfrageanforderung an einen Arbeitsbereich senden, indem Sie den Azure Monitor Log Analytics-Endpunkt https://api.loganalytics.azure.com verwenden. Um auf den Endpunkt zuzugreifen, müssen Sie sich über Microsoft Entra ID authentifizieren.

Hinweis

Der Endpunkt api.loganalytics.io wird durch api.loganalytics.azure.com ersetzt. Der Endpunkt api.loganalytics.io wird auf absehbare Zukunft weiterhin unterstützt.

Authentifizieren mit einem Demo-API-Schlüssel

Verwenden Sie den Demonstrationsarbeitsbereich mit Beispieldaten, der die Authentifizierung des API-Schlüssels unterstützt, um sich mit der API ohne Microsoft Entra-Authentifizierung schnell vertraut zu machen.

Verwenden Sie zum Authentifizieren und Ausführen von Abfragen für den Beispielarbeitsbereich die Arbeitsbereichs-ID DEMO_WORKSPACE, und übergeben Sie den API-Schlüssel DEMO_KEY.

Im Falle einer falschen Anwendungs-ID oder eines falschen API-Schlüssels wird der Fehler 403 (Unzulässig) zurückgegeben.

Der API-Schlüssel DEMO_KEY kann auf drei Arten übergeben werden – je nachdem, ob Sie einen Header, die URL oder die Standardauthentifizierung verwenden möchten:

Benutzerdefinierter Header: Geben Sie den API-Schlüssel im benutzerdefinierten Header X-Api-Key an.
Abfrageparameter: Geben Sie den API-Schlüssel im URL-Parameter api_key an.
Standardauthentifizierung: Geben Sie den API-Schlüssel als Benutzername oder Kennwort an. Wenn Sie beides angeben, muss der API-Schlüssel im Benutzernamen enthalten sein.

In diesem Beispiel werden die Arbeitsbereichs-ID und der API-Schlüssel im Header verwendet:

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

Öffentlicher API-Endpunkt

Der öffentliche API-Endpunkt ist:

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

Dabei gilt Folgendes:

api-version: Die API-Version. Die aktuelle Version ist „v1“.
workspaceId: Ihre Arbeitsbereichs-ID.

Die Abfrage wird im Anforderungstext übergeben.

Beispiel:

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

Einrichten der Authentifizierung

Sie registrieren eine Client-App bei Microsoft Entra ID und fordern ein Token an, um auf die API zuzugreifen.

Registrieren Sie eine App bei Microsoft Entra ID.
Wählen Sie auf der Übersichtsseite der App API-Berechtigungen aus.
Wählen Sie Berechtigung hinzufügen aus.
Suchen Sie auf der Registerkarte Von meiner Organisation verwendete APIs nach Log Analytics, und wählen Sie Log Analytics-API aus der Liste aus.
Wählen Sie Delegierte Berechtigungen aus.
Aktivieren Sie das Kontrollkästchen Data.Read.
Wählen Sie Berechtigungen hinzufügen aus.

Nachdem Ihre App registriert ist und über Berechtigungen zur Verwendung der API verfügt, gewähren Sie Ihrer App Zugriff auf Ihren Log Analytics-Arbeitsbereich.

Wählen Sie auf der Übersichtsseite Ihres Log Analytics-ArbeitsbereichsZugriffssteuerung (IAM) aus.
Wählen Sie Rollenzuweisung hinzufügen aus.
Wählen Sie die Rolle Leser und dann Mitglieder aus.
Wählen Sie auf der Registerkarte Mitglieder die Option Mitglieder auswählen aus.
Geben Sie den Namen Ihrer App in das Feld Auswählen ein.
Wählen Sie zunächst Ihre App und dann Auswählen aus.
Wählen Sie Überprüfen und zuweisen aus.
Nachdem Sie die Active Directory-Einrichtung und die Arbeitsbereichsberechtigungen abgeschlossen haben, fordern Sie ein Autorisierungs-Token an.

Hinweis

In diesem Beispiel haben wir die Rolle „Leser“ angewendet. Diese Rolle ist eine von vielen integrierten Rollen und enthält möglicherweise mehr Berechtigungen als benötigt. Sie können auch differenziertere Rollen und Berechtigungen erstellen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf Log Analytics-Arbeitsbereiche.

Anfordern eines Autorisierungstokens

Stellen Sie vor Beginn sicher, dass Sie über alle Werte verfügen, die für die erfolgreiche Anforderung erforderlich sind. Für alle Anforderungen wird Folgendes benötigt:

Ihre Microsoft Entra-Mandanten-ID
Ihre Arbeitsbereichs-ID.
Ihre Microsoft Entra-Client-ID für die App
Einen geheimen Microsoft Entra-Clientschlüssel für die App

Die Log Analytics-API unterstützt die Microsoft Entra-Authentifizierung mit drei verschiedenen Flows von Microsoft Entra ID OAuth2:

Client credentials (Clientanmeldeinformationen)
Authorization code (Autorisierungscode)
Implizit

Clientanmeldeinformations-Flow

Im Flow für Client-Anmeldeinformationen wird das Token mit dem Log Analytics-Endpunkt verwendet. Es wird eine einzelne Anforderung zum Empfangen eines Tokens mithilfe der Anmeldeinformationen gestellt, die für Ihre App im vorherigen Schritt Registrieren einer App in Microsoft Entra ID angegeben wurden.

Verwenden Sie den Endpunkt https://api.loganalytics.azure.com.

URL für Client-Anmeldeinformations-Token (POST-Anforderung)

    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>

Bei einer erfolgreichen Anforderung empfangen Sie ein Zugriffstoken in der Antwort:

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

Verwenden Sie das Token in Anforderungen an den Log Analytics-Endpunkt:

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

Beispielantwort:

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

Autorisierungscodeflow

Der unterstützte OAuth2-Hauptflow basiert auf Autorisierungscodes. Diese Methode erfordert zwei HTTP-Anforderungen, um ein Token zum Aufrufen der Azure Monitor Log Analytics-API zu erhalten. Es gibt zwei URLs, mit einem Endpunkt pro Anforderung. Ihre Formate werden in den folgenden Abschnitten beschrieben.

Autorisierungscode-URL (GET-Anforderung)

    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

Wenn eine Anforderung an die Autorisierungs-URL übermittelt wird, ist der Wert für „client_id“ die aus dem Eigenschaftenmenü Ihrer Microsoft Entra-App kopierte Anwendungs-ID. Der Wert für „redirect_uri“ ist die Homepage bzw. die Anmelde-URL der gleichen Microsoft Entra-App. Ist die Anforderung erfolgreich, werden Sie von diesem Endpunkt zu der Anmeldeseite umgeleitet, die Sie bei der Registrierung angegeben haben, und der Autorisierungscode wird an die URL angefügt. Sehen Sie sich folgendes Beispiel an:

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

Sie haben nun einen Autorisierungscode erhalten, den Sie benötigen, um ein Zugriffs-Token anzufordern.

URL für Autorisierungscode-Token (POST-Anforderung)

    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>

Die Werte sind die gleichen wie zuvor, aber mit einigen Ergänzungen. Der Autorisierungscode ist der Code, den Sie in der vorherigen Anforderung nach erfolgreicher Umleitung erhalten haben. Der Code wird mit dem Schlüssel kombiniert, der von der Microsoft Entra-App abgerufen wurde. Wenn Sie den Schlüssel nicht gespeichert haben, können Sie diesen löschen und auf der Registerkarte „Schlüssel“ im Menü der Microsoft Entra-App einen neuen Schlüssel erstellen. Die Antwort ist eine JSON-Zeichenfolge, die das Token mit dem folgenden Schema enthält. Für die Tokenwerte sind Typen angegeben.

Beispielantwort:

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

Der Zugriffstokenteil dieser Antwort muss der Log Analytics-API im Header Authorization: Bearer präsentiert werden. Anschließend kann auch das Aktualisierungs-Token verwendet werden, um ein neues Zugriffs-Token (access_token) und ein Aktualisierungs-Token (refresh_token) zu erhalten, wenn Ihre Token veraltet sind. Für diese Anforderung werden das folgende Format und der folgende Endpunkt verwendet:

    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>

Beispielantwort:

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

Impliziter Code-Flow

Die Log Analytics-API unterstützt den impliziten Flow für OAuth2. Bei diesem Flow ist nur eine einzelne Anforderung erforderlich, es kann jedoch kein Aktualisierungs-Token bezogen werden.

URL für implizite Codeautorisierung

    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

Eine erfolgreiche Anforderung hat eine Umleitung zu Ihrem Umleitungs-URI zur Folge, und das Token wird in die URL integriert:

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

Dieses Zugriffs-Token kann bei der Übergabe an die Log Analytics-API als Header-Wert Authorization: Bearer verwendet werden, um Anforderungen zu autorisieren.

Weitere Informationen

Die Dokumentation zu OAuth2 mit Microsoft Entra finden Sie hier:

Zugriff auf die Azure Monitor Log Analytics API

Authentifizieren mit einem Demo-API-Schlüssel

Öffentlicher API-Endpunkt

Einrichten der Authentifizierung

Anfordern eines Autorisierungstokens

Clientanmeldeinformations-Flow

URL für Client-Anmeldeinformations-Token (POST-Anforderung)

Autorisierungscodeflow

Autorisierungscode-URL (GET-Anforderung)

URL für Autorisierungscode-Token (POST-Anforderung)

Impliziter Code-Flow

URL für implizite Codeautorisierung

Weitere Informationen

Nächste Schritte

Zusätzliche Ressourcen