Dieser Artikel wurde automatisch übersetzt. Die Übersetzung kann Ungenauigkeiten enthalten.
Zur englischen Originalversion wechseln.
Ctrlk
linkedinx-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migration zur Log Ingestion API

Microsoft stellt die Log Analytics HTTP Data Collector API ein. Migrieren Sie RealmJoin mit dem RealmJoin-PowerShell-Modul zur DCR-basierten Logs Ingestion API.

Überblick

RealmJoin schreibt seine Audit-, Betriebs- und Runbook-Protokolle in Ihr eigenes Log Analytics Workspace. Bisher geschah dies über Azure Monitor HTTP Data Collector API, das sich mit dem gemeinsamen Schlüssel des Workspaces authentifiziert.

Microsoft stellt den Support für diese API am 14. September 2026ein. Ihr Nachfolger ist die Logs Ingestion API (genannt Log Ingestion API im RealmJoin-Portal), das auf Data Collection Rules (DCRs) und Microsoft Entra ID-Authentifizierung statt eines gemeinsamen Schlüssels basiert. RealmJoin unterstützt sie, und die Umstellung erfolgt mit dem RealmJoin PowerShell-Modul.

Diese Seite gilt nur, wenn Log Analytics bereits für Ihren Tenant konfiguriert ist. Wenn nicht, gibt es nichts zu migrieren — dieselbe Einstellungsseite bietet einen Befehl, der sofort ein Workspace auf der Log Ingestion API einrichtet. Wir empfehlen dennoch die Einrichtung, damit Ihre Audit-, Betriebs- und Runbook-Protokolle in Ihrem eigenen Tenant gespeichert werden.

Wird am Abschaltdatum etwas kaputtgehen?

Sehr wahrscheinlich nichts. Die aktuelle Dokumentation von Microsoft beschreibt eine weiche Abkündigung: Die alten Endpunkte werden ab diesem Datum nicht mehr unterstützt, aber sie nehmen weiterhin Daten an, und die Aufnahme funktioniert weiter, solange Clients TLS 1.2 oder neuer verwenden. Die strengere Formulierung aus der ursprünglichen Ankündigung von 2023 — dass die Endpunkte einfach nicht mehr verfügbar sein würden — ist überholt.

Die Migration wird dennoch empfohlen: Der alte Pfad wird nicht unterstützt, hängt von einem gemeinsamen Schlüssel ab und erhält keine weiteren Fehlerbehebungen.

Was sich ändert

Vorher — Data Collector API

  • Authentifizierung mit dem Workspace gemeinsamem Schlüssel ("Customer Workspace Key")

  • Ein kundeneigene Entra ID-App-Registrierung mit einem Clientgeheimnis

  • Tabellen AuditLogs_CL, OperationalLogs_CL, RunbookLogs_CL

  • Manuell im Portal konfiguriert

Nachher — Log Ingestion API

  • Authentifizierung mit Microsoft Entra ID, kein gemeinsamer Schlüssel

  • Die RealmJoin Azure Resources Service Principal, auf den Workspace und seine Regeln beschränkt

  • Tabellen RJAuditLogs_CL, RJOperationalLogs_CL, RJRunbookLogs_CL

  • Bereitgestellt und verwaltet durch das RealmJoin PowerShell-Modul

Die Migration verwendet Ihren bestehenden Workspace, sodass Ihre vorhandenen Protokolle dort bleiben, wo sie sind. RealmJoin fragt die alten und die neuen Tabellen nebeneinander ab, wodurch historische Daten nach der Migration im Portal sichtbar bleiben.

Was die Migration bereitstellt

Das Ausführen des Migrationsbefehls in Ihrer Subscription erstellt:

  • Die RealmJoin Azure Resources Service Principal in Ihrem Entra ID-Tenant (falls er noch nicht existiert)

  • Drei benutzerdefinierte Tabellen in Ihrem bestehenden Workspace: RJAuditLogs_CL, RJOperationalLogs_CL, RJRunbookLogs_CL

  • Eine Data Collection Rule pro Tabelle (dcr-rj-aud-logs-*, dcr-rj-op-logs-*, dcr-rj-rb-logs-*), jeweils mit eigenem direkten Ingestion-Endpunkt

  • Genau zwei Arten von Rollenzuweisungen für RealmJoin, und nichts darüber hinaus:

    • Log Analytics Reader auf dem Workspace, damit das Portal Ihre Protokolle abfragen kann

    • Monitoring Metrics Publisher auf jeder der drei Data Collection Rules, damit RealmJoin darauf schreiben kann

RealmJoin erhält keine weiteren Berechtigungen in Ihrer Subscription. Die Bereitstellung ist idempotent — das erneute Ausführen desselben Befehls ist sicher und wendet nur das an, was fehlt.

Voraussetzungen

Im RealmJoin-Portal

  • Eine Rolle, die Zugriff auf den Bereich „Einstellungen“ gewährt (CanReadSettingsDetails, siehe Verfügbare Berechtigungen). Die Einstellungsseite erzeugt den Migrationsbefehl einschließlich eines kurzlebigen Onboarding-Tokens.

Auf dem Rechner, auf dem PowerShell ausgeführt wird

  • PowerShell 7 oder neuer

  • Zugriff auf die PowerShell Gallery um das RealmJoin-Modul zu installieren

  • Die Az.Accounts, Az.Resources und Az.Automation -Module — das RealmJoin-Modul installiert sie automatisch in den fest vorgegebenen Versionen für den aktuellen Benutzer

Berechtigungen des Kontos, mit dem Sie sich anmelden

  • Microsoft Entra ID: Berechtigung zum Erstellen von Service Principals, zum Beispiel Application Administrator, Cloud Application Administrator oder Global Administrator. Nur beim ersten Mal erforderlich, wenn der RealmJoin Azure Resources Service Principal noch nicht existiert.

  • Azure Subscription: Berechtigung zur Bereitstellung in die Ressourcengruppe des Workspaces und um dort Rollenzuweisungen zu erstellen — zum Beispiel Owner, oder Contributor kombiniert mit User Access Administrator / Role Based Access Control Administrator.

  • Die Anmeldung erfolgt über Connect-AzAccount, das die Azure PowerShell Erstanbieteranwendung verwendet. Tenants, die die Benutzerzustimmung einschränken, müssen dieser Anwendung möglicherweise zuerst die Administratorzustimmung erteilen.

Die Ressourcengruppe und der Log Analytics Workspace sind in Ihrem Fall bereits vorhanden — die Migration erstellt sie nicht. Die Befehle aus dem Portal sind bereits mit Ihrer aktuellen Subscription, Ressourcengruppe und Workspace-Namen vorausgefüllt.

Wo die Befehle auszuführen sind

Führen Sie die Befehle in einer lokalen PowerShell-Sitzung auf einer administrativen Arbeitsstation aus — genauso, wie Sie das RealmJoin-Onboarding-Skript ausführen würden.

Verwenden Sie eine frisch geöffnete PowerShell-Sitzung und vermeiden Sie Azure Cloud Shell. Das RealmJoin-Modul erfordert exakte Versionen der Az.* -Module. Wenn bereits eine andere Version eines Az -Moduls in der Sitzung geladen ist — was in Cloud Shell typischerweise der Fall ist — kann das Modul sich nicht erholen und beendet sich mit einer Meldung über einen Versionskonflikt. Das Schließen der Sitzung und das Öffnen einer neuen behebt dies.

Eine erhöhte Sitzung („Als Administrator ausführen“) ist nicht erforderlich: Module werden mit -Scope CurrentUser.

Migration

1

Öffnen Sie die Log-Analytics-Einstellungen im Portal

Navigieren Sie zu Einstellungen → Log Analytics (https://portal.realmjoin.com/settings/log-analytics-configuration).

Solange Ihr Tenant noch die Data Collector API verwendet, zeigt die Seite den Hinweis "Zu Log Ingestion API migrieren (empfohlen)" zusammen mit einem sofort kopierbaren Befehlsblock. Verwenden Sie die Kopieren -Schaltfläche, um ihn zu kopieren.

2

Überprüfen Sie den kopierten Befehl

Der Befehl sieht folgendermaßen aus, wobei Ihre eigenen Werte eingetragen sind:

  • Die ersten Zeilen installieren oder aktualisieren das RealmJoin-Modul und importieren es.

  • Set-RJLogAnalyticsWorkspace führt die eigentliche Migration durch und registriert das Ergebnis bei RealmJoin mithilfe des -Token.

  • Grant-RJUpdateComplianceWorkspaceAccess erscheint nur, wenn Sie einen Update Compliance workspace. Es gewährt RealmJoin Log Analytics Reader auf diesem Workspace, damit Windows Update-Daten weiterhin funktionieren, ohne dass Sie eine eigene App-Registrierung benötigen.

Stellen Sie sicher, dass -ResourceGroupName, -WorkspaceName und -SubscriptionId vorhanden sind und auf Ihren bestehenden Workspace verweisen. Wenn -WorkspaceName fehlt, erstellt das Modul einen neuen Workspace anstelle des bestehenden zu migrieren, und Ihre alten und neuen Protokolle landen an unterschiedlichen Orten. Fügen Sie den fehlenden Parameter bei Bedarf manuell hinzu.

Zu 6>&1: Diese Befehle melden ihren Fortschritt im Informationsstream von PowerShell. Die 6>&1 Umleitung zeigt diese Ausgabe in der Konsole an — ohne sie sehen Sie keine Fortschrittsmeldungen.

3

Führen Sie den Befehl aus

Fügen Sie den Block in eine neue PowerShell-Sitzung ein und führen Sie ihn aus. Das Token ist ungefähr eine Stunde lang gültig — wenn es abgelaufen ist, laden Sie die Einstellungsseite neu und kopieren Sie den Befehl erneut.

Sie werden aufgefordert, sich anzumelden mit Connect-AzAccount. Wenn Ihr Konto Zugriff auf mehrere Tenants oder Subscriptions hat, fordert das Modul Sie zur Auswahl auf.

Die Bereitstellung meldet dann jede Ressource, sobald sie erstellt wird: den Service Principal, die benutzerdefinierten Tabellen, die Data Collection Rules und die Rollenzuweisungen. Ein einzelner Durchlauf dauert in der Regel einige Minuten.

Möchten Sie zuerst sehen, was passieren würde? Hängen Sie -WhatIf an Set-RJLogAnalyticsWorkspace für eine Azure Resource Manager What-If-Vorschau an. Beachten Sie, dass die Anmeldung und das Installieren der Az Module trotzdem stattfinden, da die Vorschau beides benötigt.

Danach abmelden: Die Azure-Anmeldung bleibt nach Abschluss des Befehls aktiv. Wenn Sie fertig sind, führen Sie Disconnect-AzAccount aus, um sich von der bestehenden Sitzung abzumelden.

4

Im Portal überprüfen

Kehren Sie zu Einstellungen → Log Analytics und wählen Sie Aktualisieren.

Die Seite zeigt nun die Konfiguration der Log Ingestion API — Subscription, Ressourcengruppe, Workspace-Name, Kunden-Workspace-ID und Tenant-ID — als schreibgeschützte Felder an, da diese Einstellungen von nun an vom PowerShell-Modul verwaltet werden. Unter Erweitert können Sie die Endpunkte, Regellnamen und Streamnamen der drei Data Collection Rules überprüfen.

Wählen Sie Auf Konfigurationsprobleme prüfen um zu überprüfen, dass alle erforderlichen Azure-Berechtigungen auf dem Workspace und auf jeder Data Collection Rule vorhanden sind.

5

Bestätigen Sie, dass Protokolle eingehen

Öffnen Sie Audit Log, die Runbook Logs oder die Betriebsprotokolle und bestätigen Sie, dass neue Einträge erscheinen. Auch vorhandene Einträge von vor der Migration bleiben sichtbar.

Azure benötigt einige Minuten, um eine neu erstellte benutzerdefinierte Tabelle und ihre Regel verfügbar zu machen. Wenn nicht sofort etwas ankommt, warten Sie kurz und aktualisieren Sie.

Nach der Migration

Behalten Sie die alte App-Registrierung vorerst bei

Die historischen Einträge in AuditLogs_CL, OperationalLogs_CL und RunbookLogs_CL werden weiterhin mit Ihrer bestehenden App-Registrierung und Ihrem Clientgeheimnis. Das Portal fragt die alten und die neuen Tabellen parallel ab.

Löschen Sie die App-Registrierung nicht und erneuern Sie ihr Clientgeheimnis weiter, solange Sie noch Protokolldaten von vor der Migration sehen möchten. Nur der gemeinsam genutzte Workspace-Schlüssel wird von RealmJoin nicht mehr benötigt — er wird nicht mehr zum Schreiben verwendet.

Sobald die alten Daten aus Ihrer Workspace-Aufbewahrungsdauerabgelaufen sind, können Sie die App-Registrierung entfernen.

Das Schema aktuell halten

Wenn RealmJoin das Protokollschema in einer zukünftigen Version erweitert, zeigt die Einstellungsseite einen Hinweis an, dass das bereitgestellte Log Analytics-Schema veraltet ist, zusammen mit dem Befehl zur Aktualisierung. Das ist der gleiche Set-RJLogAnalyticsWorkspace Befehl — führen Sie ihn erneut aus, und die Tabellen und Regeln werden direkt aktualisiert.

Fehlerbehebung

"RealmJoin-Modul ist veraltet - Ausführung kann nicht fortgesetzt werden"

Jedes Cmdlet überprüft einmal pro Sitzung, ob Sie die aktuell veröffentlichte Version des Moduls verwenden. Installieren Sie die aktuelle Version und schließen Sie dann die Sitzung und öffnen Sie eine neue:

Es wird ein Versionskonflikt eines Moduls gemeldet

Ein Az.* Modul in einer anderen Version als der vom RealmJoin-Modul festgelegten ist bereits in der Sitzung geladen. Das lässt sich in der laufenden Sitzung nicht beheben — schließen Sie PowerShell, öffnen Sie eine neue Sitzung und führen Sie den Befehl erneut aus. Das ist auch der Grund, Azure Cloud Shell nicht zu verwenden.

"Administratorzustimmung erforderlich" oder ein Zustimmungsfehler während der Anmeldung

Für die Anmeldung wird die Azure PowerShell Erstanbieteranwendung verwendet. Wenn Ihr Tenant die Benutzerzustimmung einschränkt, muss ein Administrator dieser Anwendung einmalig die Administratorzustimmung erteilen.

Die Bereitstellung schlägt beim Erstellen von Rollenzuweisungen fehl

Das Erstellen der Log Analytics Reader und Monitoring Metrics Publisher Zuweisungen erfordert eine Rolle, die Zugriff verwalten kann — zum Beispiel Owner, User Access Administrator oder Role Based Access Control Administrator in der Ressourcengruppe oder Subscription. Contributor allein reicht nicht aus.

Bereits vorhandene Rollenzuweisungen werden erkannt und übersprungen, daher ist das erneute Ausführen des Befehls nach Behebung der Berechtigungen sicher.

Die Bereitstellung schlägt mit einem Fehler bezüglich der Workspace-Region fehl

Die Bereitstellung zielt auf die Region der Ressourcengruppe ab. Wenn sich Ihr bestehender Workspace in einer anderen Region als seine Ressourcengruppe befindet, lehnt Azure die Änderung ab, da der Speicherort eines vorhandenen Workspaces nicht geändert werden kann. Bitte wenden Sie sich in diesem Fall an den RealmJoin-Support.

Das Token wird nicht mehr akzeptiert

Das Onboarding-Token im generierten Befehl ist kurzlebig (etwa eine Stunde). Laden Sie Einstellungen → Log Analytics im Portal neu, kopieren Sie den Befehl erneut und führen Sie ihn erneut aus. Die Azure-Bereitstellung selbst ist idempotent, daher schadet ein zweiter Lauf nicht.

Der Update Compliance workspace befindet sich in einer anderen Subscription

Grant-RJUpdateComplianceWorkspaceAccess sucht den Workspace in der derzeit ausgewählten Subscription. Wenn sich der Update Compliance workspace anderswo befindet, geben Sie die Subscription explizit an:

Zuletzt aktualisiert

War das hilfreich?