Tutorial: Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API (Resource Manager-Vorlagen)
Über die Protokollerfassungs-API in Azure Monitor können Sie benutzerdefinierte Daten an einen Log Analytics-Arbeitsbereich senden. In diesem Tutorial werden Azure Resource Manager-Vorlagen (ARM-Vorlagen) verwendet, um die Konfiguration der Komponenten zu erläutern, die zur Unterstützung der API erforderlich sind. Außerdem enthält es eine Beispielanwendung, die sowohl die REST-API als auch Clientbibliotheken für .NET, Go, Java, JavaScript und Python verwendet.
Hinweis
In diesem Tutorial werden ARM-Vorlagen verwendet, um die Komponenten zu konfigurieren, die zur Unterstützung der Protokollerfassungs-API erforderlich sind. Unter Tutorial: Senden von Daten an Azure Monitor-Protokolle über die Protokollerfassungs-API (Azure-Portal) finden Sie ein ähnliches Tutorial, in dem diese Komponenten auf der Benutzeroberfläche des Azure-Portals konfiguriert werden.
Zur Konfiguration der Protokollerfassungs-API sind die folgenden Schritte erforderlich:
- Erstellen einer Microsoft Entra-Anwendung zur Authentifizierung bei der API.
- Erstellen Sie einen Datensammlungsendpunkt (Data Collection Endpoint, DCE), um Daten zu empfangen.
- Erstellen Sie eine benutzerdefinierte Tabelle in einem Log Analytics-Arbeitsbereich. Dies ist die Tabelle, an die Sie Daten senden.
- Erstellen Sie eine Datensammlungsregel (Data Collection Rule, DCR), um die Daten an die Zieltabelle zu leiten.
- Gewähren Sie der Microsoft Entra-Anwendung Zugriff auf die DCR.
- Unter Beispielcode zum Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API finden Sie Beispielcode, der Daten über die Protokollerfassungs-API sendet.
Voraussetzungen
Für dieses Tutorial benötigen Sie Folgendes:
- Einen Log Analytics-Arbeitsbereich, in dem Sie mindestens über Berechtigungen als Mitwirkender verfügen.
- Berechtigungen zum Erstellen von Objekten für Datensammlungsregeln im Arbeitsbereich
Erfassen von Arbeitsbereichsdetails
Beginnen Sie mit dem Erfassen von Informationen, die Sie aus Ihrem Arbeitsbereich benötigen.
Wechseln Sie im Azure-Portal im Menü Log Analytics-Arbeitsbereiche zu Ihrem Arbeitsbereich. Kopieren Sie auf der Seite Eigenschaften die Ressourcen-ID, und speichern Sie sie zur späteren Verwendung.
Erstellen einer Microsoft Entra-Anwendung
Registrieren Sie zunächst eine Microsoft Entra-Anwendung, um sich bei der API zu authentifizieren. Es werden alle Resource Manager-Authentifizierungsschemas unterstützt. In diesem Tutorial verwenden Sie jedoch das Schema für den Flow zum Gewähren von Clientanmeldeinformationen.
Wählen Sie im Azure-Portal im Menü Microsoft Entra ID die Option App-Registrierungen>Neue Registrierung aus.
Benennen Sie die Anwendung, und ändern Sie den Mandantenbereich, wenn die Standardeinstellung für Ihre Umgebung ungeeignet ist. Ein Umleitungs-URI ist nicht erforderlich.
Nach der Registrierung können Sie die Details der Anwendung anzeigen. Notieren Sie sich die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Sie benötigen diese Werte später in diesem Tutorial.
Generieren Sie einen geheimen Anwendungsclientschlüssel. Dieser Vorgang ähnelt der Erstellung eines Kennworts, das mit einem Benutzernamen verwendet werden soll. Wählen Sie Zertifikate und Geheimnisse>Neuer geheimer Clientschlüssel aus. Geben Sie dem Geheimnis einen Namen, der seinen Zweck angibt, und wählen Sie ein Ablaufdatum aus. Hier ist die Option 12 Monate ausgewählt. Bei einer Implementierung in der Produktion würden Sie jedoch die bewährten Methoden für Geheimnisrotationen befolgen oder einen sichereren Authentifizierungsmodus verwenden, z. B. ein Zertifikat.
Wählen Sie Hinzufügen aus, um das Geheimnis zu speichern, und notieren Sie sich dann den Wert. Sie sollten sich diesen Wert notieren, da Sie ihn nicht wiederherstellen können, nachdem Sie diese Seite verlassen haben. Verwenden Sie dieselben Sicherheitsmaßnahmen wie bei der Aufbewahrung eines Kennworts, da es sich hierbei um die funktionale Entsprechung handelt.
Erstellen eines Datensammlungsendpunkts
Ein DCE (Data Collection Endpoint, Datensammlungsendpunkt) ist erforderlich, um die Daten zu akzeptieren, die an Azure Monitor gesendet werden. Nachdem Sie den DCE konfiguriert und mit einer DCR (Data Collection Rule, Datensammlungsregel) verknüpft haben, können Sie Daten von Ihrer Anwendung über HTTP senden. Der DCE muss sich in derselben Region wie die DCR und der Log Analytics-Arbeitsbereich befinden, an den die Daten gesendet werden.
Geben Sie im Suchfeld des Azure-Portals Vorlage ein, und wählen Sie dann Benutzerdefinierte Vorlage bereitstellen aus.
Wählen Sie Eigene Vorlage im Editor erstellen.
Fügen Sie die folgende ARM-Vorlage im Editor ein, und wählen Sie dann Speichern aus. Sie müssen diese Vorlage nicht ändern, da Sie Werte für ihre Parameter angeben.
{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "dataCollectionEndpointName": { "type": "string", "metadata": { "description": "Specifies the name of the Data Collection Endpoint to create." } }, "location": { "type": "string", "defaultValue": "westus2", "metadata": { "description": "Specifies the location for the Data Collection Endpoint." } } }, "resources": [ { "type": "Microsoft.Insights/dataCollectionEndpoints", "name": "[parameters('dataCollectionEndpointName')]", "location": "[parameters('location')]", "apiVersion": "2021-04-01", "properties": { "networkAcls": { "publicNetworkAccess": "Enabled" } } } ], "outputs": { "dataCollectionEndpointId": { "type": "string", "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]" } } }Geben Sie im Bildschirm Benutzerdefinierte Bereitstellung ein Abonnement und eine Ressourcengruppe an, um die DCR zu speichern, und geben Sie dann Werte wie den Namen für den DCE an. Der Speicherort sollte mit dem Speicherort des Arbeitsbereichs identisch sein. Die Region ist bereits angegeben und wird für den Standort des DCE verwendet.
Wählen Sie Überprüfen und erstellen und dann Erstellen aus, nachdem Sie die Details überprüft haben.
Wählen Sie JSON-Ansicht aus, um weitere Details zum DCE anzuzeigen. Kopieren Sie die Ressourcen-ID und den logsIngestion-Endpunkt. Sie benötigen die Werte in einem späteren Schritt.
Erstellen einer neuen Tabelle im Log Analytics-Arbeitsbereich
Die benutzerdefinierte Tabelle muss erstellt werden, bevor Sie Daten an sie senden können. Die Tabelle für dieses Tutorial enthält fünf Spalten, wie im Schema unten gezeigt. Die Eigenschaften name, type und description sind für jede Spalte obligatorisch. Die Eigenschaften isHidden und isDefaultDisplay sind beide standardmäßig auf false festgelegt, wenn nichts anderes explizit angegeben wird. Mögliche Datentypen sind string, int, long, real, boolean, dateTime, guid und dynamic.
Hinweis
In diesem Tutorial wird PowerShell von Azure Cloud Shell verwendet, um REST-API-Aufrufe über die Azure Monitor-Tabellen-API zu senden. Sie können auch eine andere gültige Methode verwenden, um diese Aufrufe zu senden.
Wichtig
Benutzerdefinierte Tabellen müssen das Suffix _CL verwenden.
Wählen Sie im Azure-Portal die Schaltfläche Cloud Shell aus, und achten Sie darauf, dass die Umgebung auf PowerShell festgelegt ist.
Kopieren Sie den folgenden PowerShell-Code, und ersetzen Sie die Variablen im Path-Parameter durch geeignete Werte für Ihren Arbeitsbereich im Befehl
Invoke-AzRestMethod. Fügen Sie den Code in die Cloud Shell-Eingabeaufforderung ein, um ihn auszuführen.$tableParams = @' { "properties": { "schema": { "name": "MyTable_CL", "columns": [ { "name": "TimeGenerated", "type": "datetime", "description": "The time at which the data was generated" }, { "name": "Computer", "type": "string", "description": "The computer that generated the data" }, { "name": "AdditionalContext", "type": "dynamic", "description": "Additional message properties" }, { "name": "CounterName", "type": "string", "description": "Name of the counter" }, { "name": "CounterValue", "type": "real", "description": "Value collected for the counter" } ] } } } '@ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams
Erstellen einer Datensammlungsregel
Die DCR definiert, wie die Daten nach dem Empfang verarbeitet werden. Dies schließt Folgendes ein:
- Schema der an den Endpunkt gesendeten Daten
- Transformation, die auf die Daten angewendet wird, bevor diese an den Arbeitsbereich gesendet werden
- Zielarbeitsbereich und -tabelle, an den/die die transformierten Daten gesendet werden
Geben Sie im Suchfeld des Azure-Portals Vorlage ein, und wählen Sie dann Benutzerdefinierte Vorlage bereitstellen aus.
Wählen Sie Eigene Vorlage im Editor erstellen.
Fügen Sie die folgende ARM-Vorlage im Editor ein, und wählen Sie dann Speichern aus.
Beachten Sie die folgenden Details in der in dieser Vorlage definierten DCR:
dataCollectionEndpointId: Ressourcen-ID des Datensammlungsendpunkts.streamDeclarations: Spaltendefinitionen der eingehenden Daten.destinations: Zielarbeitsbereich.dataFlows: Gleicht den Datenstrom mit dem Zielarbeitsbereich ab und gibt die Transformationsabfrage sowie die Zieltabelle an. Die Ausgabe der Zielabfrage wird an die Zieltabelle gesendet.
{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "dataCollectionRuleName": { "type": "string", "metadata": { "description": "Specifies the name of the Data Collection Rule to create." } }, "location": { "type": "string", "metadata": { "description": "Specifies the location in which to create the Data Collection Rule." } }, "workspaceResourceId": { "type": "string", "metadata": { "description": "Specifies the Azure resource ID of the Log Analytics workspace to use." } }, "endpointResourceId": { "type": "string", "metadata": { "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use." } } }, "resources": [ { "type": "Microsoft.Insights/dataCollectionRules", "name": "[parameters('dataCollectionRuleName')]", "location": "[parameters('location')]", "apiVersion": "2021-09-01-preview", "properties": { "dataCollectionEndpointId": "[parameters('endpointResourceId')]", "streamDeclarations": { "Custom-MyTableRawData": { "columns": [ { "name": "Time", "type": "datetime" }, { "name": "Computer", "type": "string" }, { "name": "AdditionalContext", "type": "string" }, { "name": "CounterName", "type": "string" }, { "name": "CounterValue", "type": "real" } ] } }, "destinations": { "logAnalytics": [ { "workspaceResourceId": "[parameters('workspaceResourceId')]", "name": "myworkspace" } ] }, "dataFlows": [ { "streams": [ "Custom-MyTableRawData" ], "destinations": [ "myworkspace" ], "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)", "outputStream": "Custom-MyTable_CL" } ] } } ], "outputs": { "dataCollectionRuleId": { "type": "string", "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]" } } }Geben Sie im Bildschirm Benutzerdefinierte Bereitstellung ein Abonnement und eine Ressourcengruppe an, um die DCR zu speichern. Geben Sie dann die in der Vorlage definierten Werte an. Zu den Werten gehören ein Name für die DCR und die Arbeitsbereichsressourcen-ID, die Sie in einem vorherigen Schritt erfasst haben. Der Speicherort sollte mit dem Speicherort des Arbeitsbereichs identisch sein. Die Region ist bereits angegeben und wird für den Standort der DCR verwendet.
Wählen Sie Überprüfen und erstellen und dann Erstellen aus, nachdem Sie die Details überprüft haben.
Erweitern Sie nach Abschluss der Bereitstellung das Feld Bereitstellungsdetails, und wählen Sie Ihre DCR aus, um die zugehörigen Details anzuzeigen. Wählen Sie JSON-Ansicht aus.
Kopieren Sie die unveränderliche ID für die DCR. Sie verwenden sie in einem späteren Schritt, wenn Sie Beispieldaten mithilfe der API senden.
Hinweis
Möglicherweise werden nicht alle Eigenschaften der DCR (z. B. die Transformation) im Azure-Portal angezeigt, obwohl die DCR erfolgreich mit diesen Eigenschaften erstellt wurde.
Zuweisen von Berechtigungen zu einer DCR
Nachdem die DCR erstellt wurde, muss der Anwendung eine Berechtigung erteilt werden, um darauf zuzugreifen. Durch die Berechtigung kann jede Anwendung, die die richtige Anwendungs-ID und den richtigen Anwendungsschlüssel verwendet, Daten an den neuen DCE und die neue DCR senden.
Wählen Sie in der DCR im Azure-Portal Zugriffssteuerung (IAM)>Rollenzuweisung hinzufügen aus.
Wählen Sie Herausgeber von Überwachungsmetriken und dann Weiter aus. Stattdessen können Sie auch eine benutzerdefinierte Aktion mit der
Microsoft.Insights/Telemetry/Write-Datenaktion erstellen.
Wählen Sie Benutzer, Gruppe oder Dienstprinzipal für Zugriff zuweisen zu und dann Mitglieder auswählen aus. Wählen Sie die erstellte Anwendung und Auswählen aus.
Wählen Sie Überprüfen und zuweisen aus, und überprüfen Sie die Details, bevor Sie Ihre Rollenzuweisung speichern.
Beispielcode
Unter Beispielcode zum Senden von Daten an Azure Monitor mithilfe der Protokollerfassungs-API finden Sie Beispielcode, der die in diesem Tutorial erstellten Komponenten verwendet.