Übersicht über Azure Monitor Protokollabfrage-API

Fragen Sie den vollständigen Satz von Daten ab, die von Azure Monitor Protokollen mit der Protokollabfrage-API gesammelt werden. Diese REST-API verwendet dieselbe Abfragesprache, die im gesamten Dienst zum Abrufen von Daten, zum Erstellen neuer Visualisierungen Ihrer Daten und zum Erweitern der Funktionen von Log Analytics verwendet wird. Die umfassendere Azure Monitor-API-Oberfläche finden Sie im Abschnitt "Protokollabfrage" des Azure Monitor REST-API-Index.

Abfrageendpunkt

Alle Abfragen zielen auf einen Log Analytics Arbeitsbereich über den öffentlichen REST-Endpunkt ab:

POST https://api.loganalytics.azure.com/v1/workspaces/{workspaceId}/query
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "query": "AzureActivity | summarize count() by Category",
  "timespan": "PT12H"
}

Ersetzen Sie {workspaceId} durch die GUID Ihres Log Analytics workspace und {accessToken} durch ein Microsoft Entra-Bearer-Token.

Die API gibt eine JSON-Antwort zurück, die ein tables Array enthält. Jede Tabelle enthält columns (das Schema) und rows (die Daten):

{
  "tables": [
    {
      "name": "PrimaryResult",
      "columns": [
        { "name": "Category", "type": "string" },
        { "name": "count_", "type": "long" }
      ],
      "rows": [
        ["Administrative", 20839],
        ["Recommendation", 122],
        ["Alert", 64],
        ["ServiceHealth", 11]
      ]
    }
  ]
}

Die vollständige Referenz für Anforderungsparameter (einschließlich timespan und arbeitsbereichsübergreifender Optionen) finden Sie unter Anforderungsformat. Ausführliche Antwortstruktur und Fehlerbehandlung finden Sie im Antwortformat.

Protokollabfrage-API-Authentifizierung

Ihre Anwendung muss sich authentifizieren, um auf die Protokollabfrage-API zuzugreifen:

  • Um Ihre Arbeitsbereiche abzufragen, müssen Sie die Microsoft Entra-Authentifizierung verwenden.
  • Um die API schnell zu erkunden, ohne Microsoft Entra Authentifizierung zu verwenden, verwenden Sie den Demo-API-Schlüssel, um Beispieldaten in einer Nichtproduktionstestumgebung abzufragen.

Microsoft Entra-Authentifizierung für Arbeitsbereichsdaten

Die Protokollabfrage-API unterstützt Microsoft Entra Authentifizierung mit Microsoft Entra ID OAuth2. Wählen Sie den Fluss aus, der zu Ihrer Anwendung passt:

  • Autorisierungscode (mit PKCE, empfohlen für interaktive Apps)
  • Clientanmeldeinformationen (für nicht interaktiven Zugriff von Dienst zu Dienst)

Der implizite Berechtigungsablauf wird aus Gründen der Abwärtskompatibilität unterstützt, wird jedoch nicht mehr empfohlen. Verwenden Sie für neue Anwendungen den Autorisierungscodefluss mit PKCE oder dem Clientanmeldeinformationsfluss.

Der Autorisierungscodefluss erfordert mindestens eine interaktive Anmeldung eines Benutzers bei Ihrer Anwendung. Wenn Sie einen nicht interaktiven Flow benötigen, verwenden Sie den Flow mit Clientanmeldeinformationen.

Nachdem Sie ein Token erhalten haben, ist der Prozess zum Aufrufen der Protokollabfrage-API für alle Flüsse identisch. Für Anfragen ist die Kopfzeile Authorization: Bearer erforderlich, die mit dem vom OAuth2-Fluss erhaltenen Token gefüllt ist.

Hinweis

Wenn Sie Microsoft Entra Authentifizierung verwenden, kann es mehrere Minuten dauern, bis die Protokollabfrage-API neue rollenbasierte Zugriffssteuerungsberechtigungen erkennt. Während Berechtigungen weitergegeben werden, können REST-API-Aufrufe mit Fehlercode 403 fehlschlagen.

API-Schlüssel-Authentifizierung für Beispieldaten

Um die API schnell zu erkunden, ohne Microsoft Entra Authentifizierung zu verwenden, stellt Microsoft einen Demoarbeitsbereich mit Beispieldaten bereit. Authentifizieren Sie sich mithilfe eines API-Schlüssels.

API-Grenzwerte für Protokollabfragen

Die API erzwingt Grenzwerte für Parallelität, Ergebnisgröße, Abfragedauer und Drosselungsrate. Diese Grenzwerte gelten pro Arbeitsbereich und variieren je nach Abfragequelle. Die vollständige Liste der Schwellenwerte finden Sie unter Abfrage-API-Grenzwerte.

Clientbibliotheken und Befehlszeilentools

Azure Monitor unterstützt Clientbibliotheken für verschiedene Programmiersprachen. Anstatt die REST-API direkt aufzurufen, bieten diese Bibliotheken einen Wrapper zum Aufrufen der Protokollabfrage-API, die auch die Authentifizierung, Wiederholungen und Antwortanalyse für Sie verarbeitet. Clientbibliotheken stehen zur Verfügung für:

Verwenden Sie Azure CLI oder Azure PowerShell auf ähnliche Weise, um eine Abfrage über die Befehlszeile auszuführen:

Verwenden Sie az monitor log-analytics query, um eine KQL-Abfrage für einen Arbeitsbereich auszuführen.

az monitor log-analytics query \
  --workspace "myWorkspaceId" \
  --analytics-query "AzureActivity | summarize count() by Category" \
  --timespan "PT12H"

Testen der API

Um die API zu erkunden, ohne Code zu schreiben, verwenden Sie einen API-Client wie Bruno oder Schlaflosigkeit , um Abfragen mit einer visuellen Schnittstelle zu erstellen. Sie können cURL auch über die Befehlszeile verwenden und die Ausgabe in jsonlint für lesbaren JSON-Code pipen.

Verwandte Inhalte

  • Last updated on