Zugriff auf die Azure Monitor Log Analytics API

Artikel
11/05/2024

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

Rufen Sie mit einer der folgenden Methoden ein Authentifizierungstoken ab:

BEFEHLSZEILENSCHNITTSTELLE (CLI)
REST-API
SDK

Beim Anfordern eines Tokens müssen Sie einen resource-Parameter angeben. Der resource-Parameter ist die URL der Ressource, auf die Sie zugreifen möchten.

Zu den Ressourcen gehören:

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

Abrufen eines Tokens mithilfe einer REST-Anforderung

Verwenden Sie den folgenden REST-API-Aufruf, um ein Token abzurufen. Diese Anforderung verwendet eine Client-ID und einen geheimen Clientschlüssel, um die Anforderung zu authentifizieren. Die Client-ID und der geheime Clientschlüssel werden abgerufen, wenn Sie Ihre Anwendung bei Microsoft Entra ID registrieren. Weitere Informationen finden Sie unter Registrieren einer App zum Anfordern von Autorisierungstoken und Arbeiten mit APIs

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'

Der Antwortkörper hat das folgende Format:

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

Abrufen eines Tokens über die Azure CLI

Um ein Token mit der CLI abzurufen, können Sie den folgenden Befehl verwenden:

az account get-access-token

Weitere Informationen finden Sie unter az account get-access-token.

Abrufen eines Tokens mithilfe der SDKs

Die folgenden Codebeispiele zeigen, wie Sie ein Token mithilfe von Folgenden abrufen:

C#
NodeJS
Python

C#

Der folgende Code zeigt, wie Sie ein Token mithilfe der Azure-Identitätsbibliothek abrufen.Diese erfordert eine Client-ID und einen geheimen Clientschlüssel, um die Anforderung zu authentifizieren.

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;

Alternativ können Sie die DefaultAzureCredential-Klasse verwenden, um ein Token abzurufen. Diese Methode verwendet die Azure-Standardanmeldeinformationen, um die Anforderung zu authentifizieren und erfordert keine Client-ID bzw. keinen geheimen Clientschlüssel.

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

Sie können Ihre verwalteten Identitäts- oder Dienstprinzipalanmeldeinformationen auch wie folgt angeben:

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

Weitere Informationen hierzu finden Sie in der Dokumentation unter DefaultAzureCredential-Klasse.

Node.js

Informationen zur Authentifizierungsverwendung mit JavaScript und NodeJS finden Sie unter AAuthentifizieren von JavaScript-Apps für Azure-Dienste mithilfe des Azure SDK für JavaScript.

Der folgende Code zeigt, wie Sie ein Token mithilfe der DefaultAzureCredential-Klasse abrufen. Diese Methode verwendet die Azure-Standardanmeldeinformationen, um die Anforderung zu authentifizieren und erfordert keine Client-ID bzw. keinen geheimen Clientschlüssel.

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

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

Sie können auch die InteractiveBrowserCredential-Klasse verwenden, um die Anmeldeinformationen abzurufen. Diese Methode bietet eine browserbasierte Authentifizierungsumgebung, mit der Benutzer sich bei Azure-Diensten authentifizieren können.

Weitere Informationen finden Sie unter DefaultAzureCredential-Klasse und InteractiveBrowserCredential-Klasse.

Alternativ können Sie die ClientSecretCredential-Klasse verwenden, um ein Token abzurufen. Diese Methode erfordert eine Client-ID und einen geheimen Clientschlüssel, um die Anforderung zu authentifizieren.

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

Weitere Informationen finden Sie unter ClientSecretCredential-Klasse.

Python

from azure.identity import DefaultAzureCredential

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

Weitere Informationen finden Sie unter DefaultAzureCredential-Klasse und InteractiveBrowserCredential-Klasse.

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)

Weitere Informationen finden Sie unter ClientSecretCredential-Klasse.

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:

Freigeben über

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

Abrufen eines Tokens mithilfe einer REST-Anforderung

Abrufen eines Tokens über die Azure CLI

Abrufen eines Tokens mithilfe der SDKs

C#

Node.js

Python

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

Feedback

Zusätzliche Ressourcen