> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/de/uberwachung-and-protokolle/log-ingestion-api-migration.md).

# 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 2026**ein. Ihr Nachfolger ist die **Logs Ingestion API** (genannt *Log Ingestion API* im RealmJoin-Portal), das auf [Data Collection Rules (DCRs)](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview) und Microsoft Entra ID-Authentifizierung statt eines gemeinsamen Schlüssels basiert. RealmJoin unterstützt sie, und die Umstellung erfolgt mit dem [RealmJoin PowerShell-Modul](/de/bereitstellung/onboarding-realmjoin-portal/advanced-setup.md).

{% hint style="info" %}
Diese Seite gilt nur, wenn [Log Analytics](/de/uberwachung-and-protokolle/log-analytics.md) 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.
{% endhint %}

### 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

{% columns %}
{% column %}

#### 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
  {% endcolumn %}

{% column %}

#### 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
  {% endcolumn %}
  {% endcolumns %}

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](/de/administration-and-einstellungen/permission/custom-roles/available-permissions.md)). 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](https://www.powershellgallery.com/packages/RealmJoin) 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.

{% hint style="info" %}
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.
{% endhint %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

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

## Migration

{% stepper %}
{% step %}

#### Ö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.
{% endstep %}

{% step %}

#### Überprüfen Sie den kopierten Befehl

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

```powershell
$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJLogAnalyticsWorkspace -ResourceGroupName "<ResourceGroupName>" -WorkspaceName "<WorkspaceName>" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
Grant-RJUpdateComplianceWorkspaceAccess -WorkspaceId "<WorkspaceId>" 6>&1
```

* 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](/de/uberwachung-and-protokolle/log-analytics.md#windows-update-for-business-reports). 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.

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

#### 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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### Bestätigen Sie, dass Protokolle eingehen

Öffnen Sie [Audit Log](/de/uberwachung-and-protokolle/audit-log.md), die [Runbook Logs](/de/automatisierung/runbooks/runbook-logs.md) oder die Betriebsprotokolle und bestätigen Sie, dass neue Einträge erscheinen. Auch vorhandene Einträge von vor der Migration bleiben sichtbar.

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}
{% endstepper %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

Sobald die alten Daten aus Ihrer [Workspace-Aufbewahrungsdauer](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2)abgelaufen 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

<details>

<summary>"RealmJoin-Modul ist veraltet - Ausführung kann nicht fortgesetzt werden"</summary>

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:

```powershell
Install-Module -Name RealmJoin -Force -Scope CurrentUser
```

</details>

<details>

<summary>Es wird ein Versionskonflikt eines Moduls gemeldet</summary>

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.

</details>

<details>

<summary>"Administratorzustimmung erforderlich" oder ein Zustimmungsfehler während der Anmeldung</summary>

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.

</details>

<details>

<summary>Die Bereitstellung schlägt beim Erstellen von Rollenzuweisungen fehl</summary>

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.

</details>

<details>

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

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.

</details>

<details>

<summary>Das Token wird nicht mehr akzeptiert</summary>

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.

</details>

<details>

<summary>Der Update Compliance workspace befindet sich in einer anderen Subscription</summary>

`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:

```powershell
Grant-RJUpdateComplianceWorkspaceAccess -WorkspaceId "<WorkspaceId>" -SubscriptionId "<SubscriptionId>" 6>&1
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/de/uberwachung-and-protokolle/log-ingestion-api-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.