Protokollerfassungs-API in Azure Monitor

Mit der Protokollerfassungs-API in Azure Monitor können Sie Daten entweder mit einem REST-API-Aufruf oder den Clientbibliotheken an einen Log Analytics-Arbeitsbereich senden. Mit der API können Sie Daten an unterstützte Azure-Tabellen oder an von Ihnen erstellte benutzerdefinierte Tabellen senden. Sie können auch das Schema von Azure-Tabellen mit benutzerdefinierten Spalten erweitern, um zusätzliche Daten zu akzeptieren.

Grundlegender Vorgang

Daten können von jeder Anwendung, die einen REST-API-Aufruf ausführen kann, an die Protokollerfassungs-API gesendet werden. Dabei kann es sich um eine von Ihnen erstellte benutzerdefinierte Anwendung oder um eine Anwendung oder einen Agenten handeln, der weiß, wie man Daten an die API sendet. Sie gibt eine Datensammlungsregel (Data Collection Rule, DCR) an, die die Zieltabelle und den Arbeitsbereich und die Anmeldeinformationen einer App-Registrierung mit Zugriff auf die angegebene DCR enthält. Sie sendet die Daten an einen von der DCR angegebenen Endpunkt oder an einen Datensammlungsendpunkt (Data Collection Endpoint, DCE),, wenn Sie eine private Verbindung verwenden.

Die von Ihrer Anwendung an die API gesendeten Daten müssen in JSON formatiert sein und der von der DCR erwarteten Struktur entsprechen. Sie müssen nicht unbedingt mit der Struktur der Zieltabelle übereinstimmen, da die DCR eine Transformation durchführen kann, um die Daten so umzuwandeln, dass sie mit der Struktur der Tabelle kompatibel sind. Sie können die Zieltabelle und den Arbeitsbereich ändern, indem Sie die DCR bearbeiten, ohne eine Änderung am API-Aufruf oder an den Quelldaten vorzunehmen.

Konfiguration

In der folgenden Tabelle werden die einzelnen Komponenten in Azure beschrieben, die Sie konfigurieren müssen, bevor Sie die Protokollerfassungs-API verwenden können.

Endpunkt

Der REST-API-Endpunkt für die Protokollerfassungs-API kann entweder ein Datensammlungsendpunkt (DCE) oder der DCR-Protokollerfassungsendpunkt sein.

Der DCR-Protokollerfassungsendpunkt wird generiert, wenn Sie eine DCR für die direkte Erfassung erstellen. Um diesen Endpunkt abzurufen, öffnen Sie die DCR in der JSON-Ansicht im Azure-Portal. Möglicherweise müssen Sie die API-Version in die aktuelle Version ändern, damit die Endpunkte angezeigt werden.

Ein DCE ist nur erforderlich, wenn Sie eine private Verbindung mit einem Log Analytics-Arbeitsbereich herstellen oder wenn die DCR den Protokollerfassungsendpunkt nicht enthält. Dies kann der Fall sein, wenn Sie eine ältere DCR verwenden oder die DCR ohne den Parameter "kind": "Direct" erstellt haben. Ausführlichere Informationen finden Sie weiter unten unter Datensammlungsregel (Data Collection Rule, DCR).

Datensammlungsregel (Data Collection Rule, DCR)

Wenn Sie über das Azure-Portal in einem Log Analytics-Arbeitsbereich eine benutzerdefinierte Tabelle erstellen, wird eine DCR erstellt, die mit der Protokollerfassungs-API verwendet werden kann. Wenn Sie Daten an eine Tabelle senden, die bereits vorhanden ist, müssen Sie die DCR manuell erstellen. Beginnen Sie mit der Beispiel-DCR unten, und ersetzen Sie die Werte für die folgenden Parameter in der Vorlage. Verwenden Sie eine der unter Erstellen und Bearbeiten von Datensammlungsregeln (DCRs) in Azure Monitor beschriebenen Methoden, um die DCR zu erstellen.

{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

Clientbibliotheken

Zusätzlich zu einem REST-API-Aufruf können Sie die folgenden Clientbibliotheken verwenden, um Daten an die Protokollerfassungs-API zu senden. Für die Bibliotheken sind dieselben Komponenten erforderlich, die in der Konfiguration beschrieben sind. Beispiele für die Verwendung dieser Bibliotheken finden Sie im Beispielcode zum Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API.

• .NET
• Go
• Java
• JavaScript
• Python

REST-API-Aufruf

Um Daten mit einem REST API-Aufruf an Azure Monitor zu senden, führen Sie einen POST-Aufruf über HTTP durch. Details, die für diesen Aufruf erforderlich sind, werden in diesem Abschnitt beschrieben.

URI

Der URI enthält die Region, den DCE- oder DCR-Erfassungsendpunkt, die DCR-ID und den Datenstromnamen. Außerdem gibt er die API-Version an.

Der URI verwendet das folgende Format:

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Zum Beispiel:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

DCR Immutable ID wird für die DCR bei ihrer Erstellung generiert. Sie können sie aus der Übersichtsseite für die DCR im Azure-Portal abrufen.

Stream Name verweist auf den Stream Name in der DCR, der die benutzerdefinierten Daten verarbeiten soll.

Headers

Die folgende Tabelle beschreibt die Kopfzeilen für Ihren API-Aufruf.

Body

Der Text des Aufrufs enthält die benutzerdefinierten Daten, die an Azure Monitor gesendet werden sollen. Die Daten müssen in Form eines JSON-Arrays mit einer Elementstruktur vorliegen, die mit dem vom Stream in der DCR erwarteten Format kompatibel ist. Wenn ein einzelnes Element innerhalb des API-Aufrufs gesendet werden muss, sollten die Daten als Einelementarray gesendet werden.

Beispiel:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Stellen Sie sicher, dass der Anforderungstext ordnungsgemäß in UTF-8 codiert ist, um Probleme mit der Datenübertragung zu vermeiden.

Beispiel

Ein Beispiel für den API-Aufruf mit PowerShell finden Sie unter Beispielcode zum Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API.

Unterstützte Tabellen

Daten, die an die Erfassungs-API gesendet werden, können an die folgenden Tabellen gesendet werden:

• ADAssessmentRecommendation
  
• ADSecurityAssessmentRecommendation
  
• Anomalien
  
• ASimAuditEventLogs
  
• ASimAuthenticationEventLogs
  
• ASimDhcpEventLogs
  
• ASimDnsActivityLogs
  
• ASimDnsAuditLogs
  
• ASimFileEventLogs
  
• ASimNetworkSessionLogs
  
• ASimProcessEventLogs
  
• ASimRegistryEventLogs
  
• ASimUserManagementActivityLogs
  
• ASimWebSessionLogs
  
• AWSCloudTrail
  
• AWSCloudWatch
  
• AWSGuardDuty
  
• AWSVPCFlow
  
• AzureAssessmentRecommendation
  
• CommonSecurityLog
  
• DeviceTvmSecureConfigurationAssessmentKB
  
• DeviceTvmSoftwareVulnerabilitiesKB
  
• ExchangeAssessmentRecommendation
  
• ExchangeOnlineAssessmentRecommendation
  
• GCPAuditLogs
  
• GoogleCloudSCC
  
• SCCMAssessmentRecommendation
  
• SCOMAssessmentRecommendation
  
• SecurityEvent
  
• SfBAssessmentRecommendation
  
• SfBOnlineAssessmentRecommendation
  
• SharePointOnlineAssessmentRecommendation
  
• SPAssessmentRecommendation
  
• SQLAssessmentRecommendation
  
• StorageInsightsAccountPropertiesDaily
  
• StorageInsightsDailyMetrics
  
• StorageInsightsHourlyMetrics
  
• StorageInsightsMonthlyMetrics
  
• StorageInsightsWeeklyMetrics
  
• Syslog
  
• UCClient
  
• UCClientReadinessStatus
  
• UCClientUpdateStatus
  
• UCDeviceAlert
  
• UCDOAggregatedStatus
  
• UCDOStatus
  
• UCServiceUpdateStatus
  
• UCUpdateAlert
  
• WindowsClientAssessmentRecommendation
  
• WindowsEvent
  
• WindowsServerAssessmentRecommendation
  

Einschränkungen

Informationen zu Einschränkungen der Protokollerfassungs-API finden Sie unter Azure Monitor-Diensteinschränkungen.

Nächste Schritte

• Einführung in ein Tutorial zum Senden von Daten an Azure Monitor-Protokolle mit der Protokollerfassungs-API auf dem Azure-Portal
• Arbeiten Sie das Tutorial zum Senden benutzerdefinierter Protokolle mithilfe von Resource Manager-Vorlagen und der REST-API durch.
• Hier erhalten Sie Anleitungen zu den Clientbibliotheken für die Protokollerfassungs-API für .NET, Java, JavaScript oder Python.