Migrieren von der HTTP-Data Collector-API zur Log Ingestion-API zum Senden von Daten an Azure Monitor-Protokolle
Die Azure Monitor Log Ingestion-API bietet mehr Verarbeitungsleistung und mehr Flexibilität beim Erfassen von Protokollen und verwalten von Tabellen als die Legacy-HTTP-Data Collector-API. Dieser Artikel beschreibt die Unterschiede zwischen der Data Collector-API sowie der Log Ingestion-API und enthält Anleitungen und bewährte Methoden für die Migration zur neuen Log Ingestion-API.
Hinweis
Als Microsoft MVP hat Morten Waltorp Knudsen zu diesem Artikel beigetragen und wichtiges Feedback zu diesem Artikel geliefert. Ein Beispiel für die Automatisierung der Einrichtung und der laufenden Verwendung der Log Ingestion-API finden Sie in Mortens öffentlich verfügbarem PowerShell-Modul „AzLogDcrIngestPS“.
Vorteile der Log Ingestion-API
Die Log Ingestion-API bietet die folgenden Vorteile gegenüber der Data Collector-API:
- Unterstützt Transformationen, mit denen Sie die Daten ändern können, bevor sie in die Zieltabelle aufgenommen werden, einschließlich Filterung und Datenbearbeitung.
- Ermöglicht das Senden von Daten an mehrere Ziele.
- Ermöglicht die Verwaltung des Zieltabellenschemas, einschließlich der Spaltennamen, und die Angabe, ob der Zieltabelle neue Spalten hinzugefügt werden sollen, wenn sich das Quelldatenschema ändert.
Voraussetzungen
Das in diesem Artikel beschriebene Migrationsverfahren setzt voraus, dass Sie über Folgendes verfügen:
- Einen Log Analytics-Arbeitsbereich, in dem Sie mindestens über Berechtigungen als Mitwirkender verfügen.
- Berechtigungen zum Erstellen von Datensammlungsregeln im Log Analytics-Arbeitsbereich.
- Eine Microsoft Entra-Anwendung zum Authentifizieren von API-Aufrufen oder anderen Resource Manager-Authentifizierungsschemas.
Erforderliche Berechtigungen
| Aktion | Erforderliche Berechtigungen |
|---|---|
| Erstelle einen Datensammlungsendpunkt. | Microsoft.Insights/dataCollectionEndpoints/write-Berechtigungen, wie sie z. B. von der integrierten Rolle „Überwachungsmitwirkender“ bereitgestellt werden. |
| Dient zum Erstellen oder Ändern einer Datensammlungsregel. | Microsoft.Insights/DataCollectionRules/Write-Berechtigungen, wie sie z. B. von der integrierten Rolle „Überwachungsmitwirkender“ bereitgestellt werden. |
| Konvertieren Sie eine Tabelle, welche die Datensammler-API verwendet, in Datensammlungsregeln und die Protokollerfassungs-API. | Microsoft.OperationalInsights/workspaces/tables/migrate/action-Berechtigungen, wie sie z. B. von der integrierten Rolle „Log Analytics-Mitwirkender“ bereitgestellt werden. |
| Erstellen Sie neue Tabellen oder ändern Sie Tabellenschemas. | microsoft.operationalinsights/workspaces/tables/write-Berechtigungen, wie sie z. B. von der integrierten Rolle „Log Analytics-Mitwirkender“ bereitgestellt werden. |
| Aufrufen der Protokollerfassungs-API. | Siehe Zuweisen von Berechtigungen zu einer DCR. |
Erstellen neuer Ressourcen, die für die Log Ingestion-API erforderlich sind
Die Log Ingestion-API erfordert, dass Sie zwei neue Ressourcentypen erstellen, die von der HTTP-Data Collector-API nicht benötigt werden:
- Datensammlungsendpunkte, von denen die gesammelten Daten zur Verarbeitung in die Pipeline aufgenommen werden.
- Datensammlungsregeln, die Datentransformationen und die Zieltabelle definieren, in der die Daten erfasst werden.
Migrieren vorhandener benutzerdefinierter Tabellen oder Erstellen neuer Tabellen
Wenn Sie über eine benutzerdefinierte Tabelle verfügen, an die Sie derzeit Daten mithilfe der Data Collector-API senden, haben Sie folgende Möglichkeiten:
Migrieren Sie die Tabelle, um mit der Erfassung von Daten in derselben Tabelle mithilfe der Log Ingestion-API fortzufahren.
Verwalten Sie die vorhandene Tabelle und die vorhandenen Daten, und richten Sie eine neue Tabelle ein, in der Sie Daten mithilfe der Log Ingestion-API erfassen. Sie können dann die alte Tabelle löschen, wenn Sie bereit sind.
Dies ist die bevorzugte Option, insbesondere wenn Sie Änderungen an der vorhandenen Tabelle vornehmen müssen. Änderungen an vorhandenen Datentypen und mehrere Schemaänderungen an vorhandenen benutzerdefinierten Data Collector-API-Tabellen können zu Fehlern führen.
Tipp
Um zu ermitteln, welche Tabellen die Datensammler-API verwenden, Tabelleneigenschaften anzeigen. Die Typ-Eigenschaft von Tabellen, die die Datensammler-API verwenden, ist auf benutzerdefinierte Tabelle (klassisch)festgelegt. Beachten Sie, dass Tabellen, die Daten mit dem älteren Log Analytics-Agent (MMA) aufnehmen, auch die Typ-Eigenschaft auf benutzerdefinierte Tabelle (klassisch) festgelegt. Stellen Sie sicher, dass Sie vom Log Analytics-Agent zu Azure Monitor Agent migrieren, bevor Sie MMA-Tabellen konvertieren. Andernfalls beenden Sie das Aufnehmen von Daten in benutzerdefinierte Felder in diesen Tabellen nach der Tabellenkonvertierung.
In dieser Tabelle sind die Überlegungen zusammengefasst, die sie für jede Option berücksichtigen sollten:
| Tabellenmigration | Parallele Implementierung | |
|---|---|---|
| Tabellen- und Spaltenbenennung | Verwenden Sie vorhandene Tabellennamen. Spaltenbenennungsoptionen: – Verwenden Sie neue Spaltennamen, und definieren Sie eine Transformation, um eingehende Daten an die neu benannte Spalte weiterzuleiten. – Verwenden Sie weiterhin die alten Namen. |
Legen Sie den Namen der neuen Tabelle frei fest. Sie müssen Integrationen, Dashboards und Warnungen anpassen, bevor Sie zur neuen Tabelle wechseln. |
| Migrationsverfahren | Einmalige Tabellenmigration. Ein Rollback für eine migrierte Tabelle ist nicht möglich. | Die Migration kann schrittweise pro Tabelle erfolgen. |
| Nach der Migration | Sie können weiterhin Daten mithilfe der HTTP-Data Collector-API mit vorhandenen Spalten erfassen, mit Ausnahme von benutzerdefinierten Spalten. Erfassen Sie Daten nur mithilfe der Log Ingestion-API in neuen Spalten. |
Daten in der alten Tabelle sind bis zum Ende des Aufbewahrungszeitraums verfügbar. Wenn Sie zum ersten Mal eine neue Tabelle einrichten oder Schemaänderungen vornehmen, kann es 10 bis 15 Minuten dauern, bis die Datenänderungen in der Zieltabelle angezeigt werden. |
Um eine Tabelle, die die Data Collector-API verwendet, in Datensammlungsregeln und die Log Ingestion-API zu konvertieren, führen Sie diesen API-Aufruf für die Tabelle aus:
POST https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/tables/{tableName}/migrate?api-version=2021-12-01-preview
Dieser Aufruf ist idempotent und hat somit keine Wirkung, wenn die Tabelle bereits migriert wurde.
Der API-Aufruf aktiviert alle DCR-basierten benutzerdefinierten Protokollfeatures in der Tabelle. Die Data Collector-API erfasst zwar weiterhin Daten in vorhandene Spalten, erstellt aber keine neuen Spalten. Alle zuvor definierten benutzerdefinierten Felder werden nicht mehr aufgefüllt. Eine weitere Möglichkeit, eine vorhandene Tabelle so zu migrieren, dass sie Datensammlungsregeln, aber nicht unbedingt die Log Ingestion-API verwendet, ist das Anwenden einer Arbeitsbereichstransformation auf die Tabelle.
Wichtig
- 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,UniqueIdundTitlesind reservierte Spaltennamen.- Benutzerdefinierte Spalten, die Sie einer Azure-Tabelle hinzufügen, müssen das Suffix
_CFaufweisen. - Wenn Sie das Tabellenschema in Ihrem Log Analytics-Arbeitsbereich aktualisieren, müssen Sie auch die Eingabedatenstromdefinition in der Datensammlungsregel aktualisieren, um Daten in neuen oder geänderten Spalten zu erfassen.
Aufrufen der Log Ingestion-API
Mit der Log Ingestion-API können Sie bis zu 1 MB komprimierter oder nicht komprimierter Daten pro Aufruf senden. Wenn Sie mehr als 1 MB Daten senden müssen, können Sie mehrere Anrufe parallel senden. Dies ist ein Unterschied zur Data Collector-API, mit der Sie bis zu 32 MB Daten pro Aufruf senden können.
Informationen zum Aufrufen der Log Ingestion-API finden Sie unter Log Ingestion-REST-API-Aufruf.
Ändern von Tabellenschemas und Datensammlungsregeln basierend auf Änderungen am Quelldatenobjekt
Während die Data Collector-API das Zieltabellenschema automatisch anpasst, wenn sich das Quelldatenobjektschema ändert, ist dies bei der Log Ingestion-API nicht der Fall. Dadurch wird sichergestellt, dass Sie keine neuen Daten in Spalten sammeln, die Sie nicht erstellen möchten.
Wenn sich das Quelldatenschema ändert, haben Sie folgende Möglichkeiten:
- Ändern Sie Zieltabellenschemas und Datensammlungsregeln, um sie entsprechend der Änderungen des Quelldatenschemas anzupassen.
- Definieren Sie eine Transformation in der Datensammlungsregel, um die neuen Daten in vorhandene Spalten in der Zieltabelle zu senden.
- Lassen Sie die Zieltabelle und die Datensammlungsregel unverändert. In diesem Fall erfassen Sie die neuen Daten nicht.
Hinweis
Sie können einen Spaltennamen nicht mit einem Datentyp, der sich vom ursprünglichen Datentyp unterscheidet, der für die Spalte definiert wurde, wiederverwenden.