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

## Übersicht

RealmJoin schreibt seine Audit-, Betriebs- und Runbook-Protokolle in Ihren eigenen Log Analytics Workspace. Bisher geschah dies über die Azure Monitor **HTTP Data Collector API**, die sich mit dem gemeinsamen Schlüssel des Arbeitsbereichs authentifiziert.

Microsoft beendet die Unterstützung für diese API am **14. September 2026**. Ihr Nachfolger ist die **Logs Ingestion API** (im *Log Ingestion API* im RealmJoin Portal genannt), die 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. Falls nicht, gibt es nichts zu migrieren – dieselbe Einstellungsseite bietet einen Befehl, der sofort einen Arbeitsbereich mit der Log Ingestion API einrichtet. Wir empfehlen dennoch, ihn einzurichten, damit Ihre Audit-, Betriebs- und Runbook-Protokolle in Ihrem eigenen Tenant gespeichert werden.
{% endhint %}

### Wird am Einstellungsdatum etwas nicht mehr funktionieren?

Wahrscheinlich nicht. Die aktuelle Dokumentation von Microsoft beschreibt eine *sanfte* Einstellung: Die alten Endpunkte werden ab diesem Datum nicht mehr unterstützt, nehmen jedoch weiterhin Daten an, und die Erfassung 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 wären – ist überholt.

Eine Migration wird dennoch empfohlen: Der alte Weg wird nicht unterstützt, ist von einem gemeinsamen Schlüssel abhängig und erhält keine weiteren Fehlerbehebungen.

### Was sich ändert

{% columns %}
{% column %}

#### Vorher – Data Collector API

* Authentifizierung mit dem Arbeitsbereichs- **gemeinsamen Schlüssel** ("Customer Workspace Key")
* Eine **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**, ohne gemeinsamen Schlüssel
* Der **RealmJoin Azure Resources** Service Principal, auf den Arbeitsbereich und seine Regeln beschränkt
* Tabellen `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Bereitgestellt und gewartet durch das RealmJoin PowerShell-Modul
  {% endcolumn %}
  {% endcolumns %}

Die Migration verwendet Ihren **vorhandenen** Arbeitsbereich weiter, sodass Ihre vorhandenen Protokolle dort bleiben, wo sie sind. RealmJoin fragt die alten und neuen Tabellen parallel ab, sodass historische Daten nach der Migration weiterhin im Portal sichtbar bleiben.

### Was die Migration bereitstellt

Durch Ausführen des Migrationsbefehls in Ihrem Abonnement werden erstellt:

* Der **RealmJoin Azure Resources** Service Principal in Ihrem Entra ID-Tenant (falls noch nicht vorhanden)
* Drei benutzerdefinierte Tabellen in Ihrem vorhandenen Arbeitsbereich: `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 Endpunkt für die direkte Datenerfassung
* Genau zwei Arten von Rollenzuweisungen für RealmJoin und keine weiteren:
  * **Log Analytics Reader** für den Arbeitsbereich, damit das Portal Ihre Protokolle abfragen kann
  * **Monitoring Metrics Publisher** für jede der drei Data Collection Rules, damit RealmJoin in sie schreiben kann

RealmJoin erhält keine weiteren Berechtigungen in Ihrem Abonnement. Die Bereitstellung ist idempotent – das erneute Ausführen desselben Befehls ist sicher und wendet nur Fehlendes an.

## Voraussetzungen

### Im RealmJoin Portal

* Eine Rolle, die Zugriff auf den Bereich Einstellungen gewährt (`CanReadSettingsDetails`, siehe [Verfügbare Berechtigungen](/de/verwaltung-and-einstellungen/permission/custom-roles/available-permissions.md)). Die Einstellungsseite generiert den Migrationsbefehl einschließlich eines kurzlebigen Onboarding-Tokens.

### Auf dem Computer, auf dem PowerShell ausgeführt wird

* **PowerShell 7** oder höher
* Zugriff auf die [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) zur Installation des RealmJoin-Moduls
* Der `Az.Accounts`, `Az.Resources` und `Az.Automation` Module – das RealmJoin-Modul installiert sie für den aktuellen Benutzer automatisch in den festgelegten Versionen

### Berechtigungen des Kontos, mit dem Sie sich anmelden

* **Microsoft Entra ID:** Berechtigung zum Erstellen von Service Principals, beispielsweise *Application Administrator*, *Cloud Application Administrator* oder *Global Administrator*. Nur beim ersten Mal erforderlich, wenn der Service Principal RealmJoin Azure Resources noch nicht vorhanden ist.
* **Azure-Abonnement:** Berechtigung zur Bereitstellung in der Ressourcengruppe des Arbeitsbereichs **und** zum Erstellen von Rollenzuweisungen darauf – beispielsweise *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 Benutzereinwilligung einschränken, müssen dieser Anwendung möglicherweise zuerst die Administratoreinwilligung erteilen.

{% hint style="info" %}
Die Ressourcengruppe und der Log Analytics Workspace existieren in Ihrem Fall bereits – die Migration erstellt sie nicht. Die Befehle aus dem Portal sind mit Ihrem aktuellen Abonnement, der Ressourcengruppe und dem Namen des Arbeitsbereichs vorausgefüllt.
{% endhint %}

## Wo die Befehle ausgeführt werden

Führen Sie die Befehle in einer **lokalen PowerShell-Sitzung** auf einer administrativen Arbeitsstation aus – genauso, wie Sie das RealmJoin-Onboardingskript 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 normalerweise in Cloud Shell der Fall ist –, kann das Modul dies nicht beheben und wird mit einer Meldung zu einem Versionskonflikt beendet. Das Schließen der Sitzung und Öffnen einer neuen löst dieses Problem.
{% 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 sich Ihr Tenant noch auf der Data Collector API befindet, zeigt die Seite den Hinweis **„Zur Log Ingestion API migrieren (empfohlen)“** zusammen mit einem kopierfertigen Befehlsblock. Verwenden Sie die Schaltfläche **Kopieren** zum Kopieren.
{% endstep %}

{% step %}

#### Kopierten Befehl überprüfen

Der Befehl sieht mit Ihren eigenen eingetragenen Werten wie folgt aus:

```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 mithilfe von `-Token`.
* `Grant-RJUpdateComplianceWorkspaceAccess` wird nur angezeigt, wenn Sie einen [Update Compliance-Arbeitsbereich](/de/uberwachung-and-protokolle/log-analytics.md#windows-update-for-business-reports)konfiguriert haben. Es gewährt RealmJoin *Log Analytics Reader* für diesen Arbeitsbereich, damit Windows Update-Daten ohne Ihre eigene App-Registrierung weiterhin funktionieren.

{% hint style="warning" %}
Stellen Sie sicher, dass `-ResourceGroupName`, `-WorkspaceName` und `-SubscriptionId` vorhanden sind und auf Ihren **vorhandenen** Arbeitsbereich verweisen. Falls `-WorkspaceName` fehlt, erstellt das Modul einen **neuen** Arbeitsbereich, anstatt den vorhandenen 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" %}
**Informationen zu `6>&1`:** diesen Befehlen: Sie 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 %}

#### Befehl ausführen

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

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

Die Bereitstellung meldet anschließend jede Ressource bei ihrer Erstellung: den Service Principal, die benutzerdefinierten Tabellen, die Data Collection Rules und die Rollenzuweisungen. Ein einzelner Durchlauf dauert normalerweise einige Minuten.

{% hint style="info" %}
Möchten Sie zuerst sehen, was passieren würde? Hängen Sie `-WhatIf` an `Set-RJLogAnalyticsWorkspace` an, um eine Azure Resource Manager What-If-Vorschau zu erhalten. Beachten Sie, dass die Anmeldung und Installation der `Az` Module dennoch erfolgen, da die Vorschau beides benötigt.
{% endhint %}
{% endstep %}

{% step %}

#### Im Portal überprüfen

Kehren Sie zurück zu **Einstellungen → Log Analytics** und wählen Sie **Aktualisieren**.

Die Seite zeigt nun die Konfiguration der Log Ingestion API – Abonnement, Ressourcengruppe, Name des Arbeitsbereichs, Kundenarbeitsbereichs-ID und Tenant-ID – als schreibgeschützte Felder an, da diese Einstellungen ab jetzt vom PowerShell-Modul verwaltet werden. Unter **Erweitert** können Sie die Endpunkte, Regelnamen und Streamnamen der drei Data Collection Rules überprüfen.

Wählen Sie **Auf Konfigurationsprobleme prüfen** aus, um zu überprüfen, dass alle erforderlichen Azure-Berechtigungen für den Arbeitsbereich und jede Data Collection Rule vorhanden sind.
{% endstep %}

{% step %}

#### Bestätigen, dass Protokolle eintreffen

Öffnen Sie [Auditprotokoll](/de/uberwachung-and-protokolle/audit-log.md), die [Runbook-Protokolle](/de/automatisierung/runbooks/runbook-logs.md) oder die Betriebsprotokolle und bestätigen Sie, dass neue Einträge angezeigt werden. Vor der Migration vorhandene Einträge bleiben ebenfalls 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 eintrifft, warten Sie etwas und aktualisieren Sie die Seite.
{% 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 **vorhandenen App-Registrierung und Ihrem Clientgeheimnis**gelesen. Das Portal fragt die alten und neuen Tabellen parallel ab.

{% hint style="warning" %}
Löschen Sie die App-Registrierung nicht und erneuern Sie weiterhin ihr Clientgeheimnis, solange Sie noch Protokolldaten von vor der Migration sehen möchten. Nur der **gemeinsame Schlüssel des Arbeitsbereichs** wird von RealmJoin nicht mehr benötigt – er wird nicht mehr zum Schreiben verwendet.
{% endhint %}

Sobald die alten Daten aus Ihrer [Aufbewahrungsdauer des Arbeitsbereichs](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2)herausgefallen sind, können Sie die App-Registrierung entfernen.

### 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 zu dessen Aktualisierung. Das ist derselbe **gleiche** `Set-RJLogAnalyticsWorkspace` Befehl – führen Sie ihn erneut aus, und die Tabellen und Regeln werden direkt aktualisiert.

## Problembehandlung

<details>

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

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

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

</details>

<details>

<summary>Ein Modulversionskonflikt wird gemeldet</summary>

Ein `Az.*` Modul in einer anderen Version als derjenigen, die das RealmJoin-Modul festlegt, ist bereits in der Sitzung geladen. Dies kann innerhalb der laufenden Sitzung nicht behoben werden – schließen Sie PowerShell, öffnen Sie eine neue Sitzung und führen Sie den Befehl erneut aus. Dies ist auch der Grund, Azure Cloud Shell nicht zu verwenden.

</details>

<details>

<summary>„Administratorgenehmigung erforderlich“ oder ein Einwilligungsfehler bei der Anmeldung</summary>

Die Anmeldung verwendet die **Azure PowerShell** Erstanbieteranwendung. Wenn Ihr Tenant die Benutzereinwilligung einschränkt, muss ein Administrator dieser Anwendung einmalig die Administratoreinwilligung 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 Zugriffe verwalten kann – beispielsweise *Owner*, *User Access Administrator* oder *Role Based Access Control Administrator* für die Ressourcengruppe oder das Abonnement. *Contributor* allein reicht nicht aus.

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

</details>

<details>

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

Die Bereitstellung zielt auf die Region der Ressourcengruppe ab. Wenn Ihr vorhandener Arbeitsbereich in einer anderen Region als seine Ressourcengruppe liegt, lehnt Azure die Änderung ab, da der Speicherort eines vorhandenen Arbeitsbereichs nicht geändert werden kann. Wenden Sie sich in diesem Fall bitte 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, sodass ein zweiter Durchlauf keinen Schaden verursacht.

</details>

<details>

<summary>Der Update Compliance-Arbeitsbereich befindet sich in einem anderen Abonnement</summary>

`Grant-RJUpdateComplianceWorkspaceAccess` sucht den Arbeitsbereich im aktuell ausgewählten Abonnement. Wenn sich der Update Compliance-Arbeitsbereich an anderer Stelle befindet, geben Sie das Abonnement 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.