Protokollerfassungs-API in Azure Monitor

  • Artikel

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. Die Anwendung sendet Daten an einen Datensammlungsendpunkt (Data Collection Endpoint, DCE), der ein eindeutiger Verbindungspunkt für Ihr Azure-Abonnement ist. 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.

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.

Abbildung: Übersicht über die Protokollerfassungs-API

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.

Hinweis

Ein PowerShell-Skript, das die Konfiguration dieser Komponenten automatisiert, finden Sie unter Beispielcode zum Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API.

Komponente Funktion
App-Registrierung und geheimer Schlüssel Die Anwendungsregistrierung wird verwendet, um den API-Aufruf zu authentifizieren. Der unten beschriebenen DCR muss die Berechtigung erteilt werden. Der API-Aufruf enthält die Anwendungs-ID (Client-ID) und Verzeichnis-ID (Mandanten-ID) der Anwendung und den Wert eines geheimen Anwendungsschlüssels.

Siehe Erstellen einer Microsoft Entra-Anwendung und eines Dienstprinzipals mit Zugriff auf Ressourcen und Erstellen eines neuen Anwendungsgeheimnisses.
Datensammlungsendpunkt (Data Collection Endpoint, DCE) Der DCE stellt einen Endpunkt für die Anwendung bereit, an die gesendet werden soll. Ein einzelner DCE kann mehrere DCRs unterstützen, sodass Sie einen vorhandenen DCE verwenden können, wenn Sie bereits über einen DCE in derselben Region wie der Ihres Log Analytics-Arbeitsbereichs verfügen.

Siehe Erstellen eines Datensammlungsendpunkts.
Tabelle im Log Analytics-Arbeitsbereich Die Tabelle im Log Analytics-Arbeitsbereich muss vorhanden sein, bevor Sie Daten an diese senden können. Sie können eine der unterstützten Azure-Tabellen verwenden oder eine benutzerdefinierte Tabelle mit einer der verfügbaren Methoden erstellen. Wenn Sie das Azure-Portal zum Erstellen der Tabelle verwenden, wird die DCR für Sie erstellt, einschließlich einer Transformation, falls erforderlich. Bei jeder anderen Methode müssen Sie die DCR manuell erstellen, wie im nächsten Abschnitt beschrieben.

Siehe Erstellen einer benutzerdefinierten Tabelle.
Datensammlungsregel (Data Collection Rule, DCR) Azure Monitor verwendet die Datensammlungsregel (Data Collection Rule, DCR), um die Struktur der eingehenden Daten zu verstehen und zu entscheiden, was mit ihnen geschehen soll. Wenn die Struktur der Tabelle und die eingehenden Daten nicht übereinstimmen, kann die DCR eine Transformation durchführen, um die Quelldaten in Übereinstimmung mit der Zieltabelle zu konvertieren. Sie können mithilfe der Transformation auch Quelldaten filtern und andere Berechnungen oder Konvertierungen durchführen.

Wenn Sie eine benutzerdefinierte Tabelle mithilfe des Azure-Portals erstellen, werden DCR und die Transformation basierend auf den von Ihnen bereitgestellten Beispieldaten erstellt. Wenn Sie eine vorhandene Tabelle verwenden oder eine benutzerdefinierte Tabelle mit einer anderen Methode erstellen, müssen Sie die DCR manuell mithilfe von Details im folgenden Abschnitt erstellen.

Sobald Ihre DCR erstellt ist, müssen Sie der Anwendung, die Sie im ersten Schritt erstellt haben, Zugriff darauf gewähren. Wählen Sie im Azure-Portal im Menü Überwachen die Option Datensammlungsregeln aus und dann die von Ihnen erstellte DCR aus. Wählen Sie Zugriffssteuerung (IAM) für die Datensammlungsregel und dann Rollenzuweisung hinzufügen aus, um die Rolle Monitoring Metrics Publisher hinzuzufügen.

Manuelles Erstellen der DCR

Wenn Sie Daten an eine Tabelle senden, die bereits vorhanden ist, müssen Sie die DCR manuell erstellen. Beginnen Sie mit der Beispiel-DCR für die Protokollerfassungs-API und ändern Sie die folgenden Parameter in der Vorlage. Verwenden Sie dann eine der in Erstellen und Bearbeiten von Datensammlungsregeln (DCRs) in Azure Monitor beschriebenen Methoden, um die DCR zu erstellen.

Parameter Beschreibung
region Region zum Erstellen der DCR. Sie muss mit der Region der DCR und des Log Analytics-Arbeitsbereichs übereinstimmen.
dataCollectionEndpointId Ressourcen-ID Ihres DCE.
streamDeclarations Ändern Sie die Spaltenliste auf die Spalten in Ihren eingehenden Daten. Sie müssen den Namen des Datenstroms nicht ändern, da dies nur mit dem streams-Namen in dataFlows übereinstimmen muss.
workspaceResourceId Ressourcen-ID Ihres Log Analytics-Arbeitsbereichs. Sie müssen den Namen nicht ändern, da dies nur mit dem destinations-Namen in dataFlows übereinstimmen muss.
transformKql KQL-Abfrage, die auf die eingehenden Daten angewendet werden soll. Wenn das Schema der eingehenden Daten mit dem Schema der Tabelle übereinstimmt, können Sie source für die Transformation verwenden, die die eingehenden Daten unverändert übergibt. Verwenden Sie andernfalls eine Abfrage, die die Daten so transformiert, dass sie mit dem Tabellenschema übereinstimmen.
outputStream Name der Tabelle zum Senden der Daten. Fügen Sie für eine benutzerdefinierte Tabelle das Präfix Benutzerdefiniert/e/r<Tabellenname> hinzu. Fügen Sie für eine integrierte Tabelle das Präfix Microsoft-<Tabellenname> hinzu.

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.

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.

Endpunkt-URI

Der Endpunkt-URI verwendet das folgenden Format, wobei Data Collection Endpoint und DCR Immutable ID für den DCE und die DCR stehen. Die unveränderliche ID wird für die DCR bei ihrer Erstellung generiert. Sie können sie aus der JSON-Ansicht der DCR im Azure-Portal abrufen. Stream Name verweist auf den Stream Name in der DCR, der die benutzerdefinierten Daten verarbeiten soll.

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

Beispiel:

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

Kopfzeilen

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

Header Erforderlich? Beschreibung
Authorization Ja Bearertoken, das über den Flow für Clientanmeldeinformationen abgerufen wurde. Verwenden Sie den Tokengruppenwert für Ihre Cloud:

Öffentliche Azure-Cloud - https://monitor.azure.com
Microsoft Azure operated by 21Vianet Cloud - https://monitor.azure.cn
Azure US Government Cloud - https://monitor.azure.us
Content-Type Ja application/json
Content-Encoding Nein gzip
x-ms-client-request-id Nein GUID im Zeichenfolgenformat. Dies ist eine Anforderungs-ID, die von Microsoft zur Problembehandlung verwendet werden kann.

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:

Tabellen BESCHREIBUNG
Benutzerdefinierte Tabellen Jede von Ihnen erstellte benutzerdefinierte Tabelle in Ihrem Log Analytics-Arbeitsbereich. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Benutzerdefinierte Tabellen müssen das Suffix _CL aufweisen.
Azure-Tabellen Die folgenden Azure-Tabellen werden derzeit unterstützt. Weitere Tabellen können dieser Liste hinzugefügt werden, sobald die Unterstützung für sie implementiert ist.

Hinweis

Spaltennamen müssen mit einem Buchstaben beginnen und können aus bis zu 45 alphanumerischen Zeichen und Unterstrichen (_) bestehen. _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId und Title sind reservierte Spaltennamen. Benutzerdefinierte Spalten, die Sie einer Azure-Tabelle hinzufügen, müssen das Suffix _CFaufweisen.

Einschränkungen

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

Nächste Schritte