> 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**, das sich mit dem gemeinsamen Schlüssel des Workspaces authentifiziert.

Microsoft beendet den Support für diese API am **14. September 2026**. Sein 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 dies, und die Umstellung erfolgt mit dem [RealmJoin PowerShell-Modul](https://docs.realmjoin.com/de/bereitstellung/onboarding-realmjoin-portal/advanced-setup.md).

{% hint style="info" %}
Diese Seite gilt nur, wenn [Log Analytics](https://docs.realmjoin.com/de/uberwachung-and-protokolle/log-analytics.md) für Ihren Tenant bereits konfiguriert ist. Falls nicht, gibt es nichts zu migrieren — dieselbe Einstellungsseite bietet einen Befehl an, der sofort einen Workspace auf 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 Abschaltdatum irgendetwas kaputtgehen?

Sehr wahrscheinlich nichts. Die aktuelle Microsoft-Dokumentation beschreibt eine *schrittweise* Abkündigung: Die alten Endpunkte werden ab diesem Datum nicht mehr unterstützt, nehmen aber 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 wären — ist veraltet.

Eine 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 **gemeinsamen Schlüssel** ("Customer Workspace Key")
* Eine **kundeneigene Entra ID-Anwendungsregistrierung** mit einem Clientgeheimnis
* Tabellen `AuditLogs_CL`, `OperationalLogs_CL`, `RunbookLogs_CL`
* Im Portal manuell 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 gewartet durch das RealmJoin PowerShell-Modul
  {% endcolumn %}
  {% endcolumns %}

Die Migration verwendet Ihren **vorhandenen** Workspace wieder, 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

Wenn Sie den Migrationsbefehl in Ihrer Subscription ausführen, wird Folgendes erstellt:

* Die **RealmJoin Azure Resources** Service Principal in Ihrem Entra ID-Tenant (falls er noch nicht existiert)
* Drei benutzerdefinierte Tabellen in Ihrem vorhandenen Workspace: `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Je 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 Rollenzuweisung 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 in Ihrer Subscription keine weiteren Berechtigungen. 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](https://docs.realmjoin.com/de/administration-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 läuft

* **PowerShell 7** oder höher
* Zugriff auf die [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) zum Installieren des RealmJoin-Moduls
* 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 Service Principal RealmJoin Azure Resources noch nicht existiert.
* **Azure-Abonnement:** Berechtigung, in der Ressourcengruppe des Workspaces Bereitstellungen durchzuführen **und** um darin Rollenzuweisungen zu erstellen — zum Beispiel *Owner*, oder *Contributor* in Kombination mit *User Access Administrator* / *Role Based Access Control Administrator*.
* Die Anmeldung erfolgt über `Connect-AzAccount`, das die **Azure PowerShell** First-Party-Anwendung verwendet. Mandanten, die die Benutzerzustimmung einschränken, müssen dieser Anwendung möglicherweise zunächst die Administratorzustimmung 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 bereits mit Ihrer aktuellen Subscription, Ressourcengruppe und Ihrem 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 in der Sitzung bereits eine andere Version eines `Az` Moduls geladen ist — was in Cloud Shell typischerweise der Fall ist — kann sich das Modul nicht erholen und beendet sich mit einer Meldung über Versionskonflikte. Das Schließen der Sitzung und das Öffnen einer neuen behebt dies.
{% endhint %}

Eine erhöhte ("Als Administrator ausführen")-Sitzung 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 %}

#### Prüfen Sie den kopierten Befehl

Der Befehl sieht so aus, wobei Ihre eigenen Werte eingefügt 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
```

* 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 von `-Token`.

{% hint style="warning" %}
Stellen Sie sicher, `-ResourceGroupName`, `-WorkspaceName` und `-SubscriptionId` vorhanden sind und auf Ihren **vorhandenen** Workspace verweisen. Wenn `-WorkspaceName` fehlt, erstellt das Modul einen **neuen** Workspace statt 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" %}
**Über `6>&1`:** diese Befehle melden ihren Fortschritt über den 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 gültig — wenn es abgelaufen ist, laden Sie die Einstellungsseite neu und kopieren Sie den Befehl erneut.

Sie werden aufgefordert, sich mit `Connect-AzAccount`. Wenn Ihr Konto Zugriff auf mehrere Tenants oder Subscriptions hat, fordert das Modul Sie auf, eine auszuwählen.

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 die Installation der `Az` Module trotzdem stattfinden, da die Vorschau beides benötigt.
{% endhint %}

{% hint style="info" %}
**Abmelden danach:** 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

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

Auf der Seite werden jetzt die Log Ingestion API-Konfiguration — Subscription, Ressourcengruppe, Workspace-Name, Kunden-Workspace-ID und Tenant-ID — als schreibgeschützte Felder angezeigt, da diese Einstellungen ab jetzt vom PowerShell-Modul verwaltet werden. Unter **Erweitert** können Sie die Endpunkte, Reglernamen und Stream-Namen der drei Data Collection Rules überprüfen.

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

{% step %}

#### Bestätigen, dass Protokolle ankommen

Öffnen Sie [Audit-Protokoll](https://docs.realmjoin.com/de/uberwachung-and-protokolle/audit-log.md), die [Runbook-Protokolle](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-logs.md) oder die Betriebsprotokolle und bestätigen Sie, dass neue Einträge erscheinen. 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 bereitzustellen. Wenn nicht sofort etwas ankommt, warten Sie kurz und aktualisieren Sie dann.
{% endhint %}
{% endstep %}
{% endstepper %}

## Nach der Migration

### Die alte App-Registrierung vorerst behalten

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 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 **gemeinsame Workspace-Schlüssel** wird von RealmJoin nicht mehr benötigt — er wird nicht mehr zum Schreiben verwendet.
{% endhint %}

Sobald die alten Daten in Ihrer [Aufbewahrungsdauer des Workspaces](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 in einer zukünftigen Version das Protokollschema erweitert, zeigt die Einstellungsseite einen Hinweis an, dass das bereitgestellte Log Analytics-Schema veraltet ist, zusammen mit dem Befehl zum Aktualisieren. Das ist der **gleiche** `Set-RJLogAnalyticsWorkspace` Befehl — führen Sie ihn erneut aus, und die Tabellen und Regeln werden vor Ort aktualisiert.

## Fehlerbehebung

<details>

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

Jedes Cmdlet prüft einmal per Sitzung, ob Sie die neueste 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 Versionskonflikt eines Moduls wird gemeldet</summary>

Ein `Az.*` Modul in einer anderen Version als der, die das RealmJoin-Modul fest vorgibt, ist bereits in der Sitzung geladen. Das lässt sich innerhalb 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>"Adminfreigabe erforderlich" oder ein Zustimmungsfehler während der Anmeldung</summary>

Die Anmeldung verwendet die **Azure PowerShell** First-Party-Anwendung. Wenn Ihr Tenant die Benutzerzustimmung einschränkt, muss ein Administrator dieser Anwendung einmal 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 Zugriffe verwalten kann — zum Beispiel *Owner*, *User Access Administrator* oder *Role Based Access Control Administrator* auf der Ressourcengruppe oder Subscription. *Contributor* allein reicht nicht aus.

Rollenzuweisungen, die bereits existieren, werden erkannt und übersprungen, sodass das erneute Ausführen des Befehls nach Behebung der Berechtigungen sicher ist.

</details>

<details>

<summary>Die Bereitstellung schlägt mit einem Fehler zur Workspace-Region fehl</summary>

Die Bereitstellung zielt auf die Region der Ressourcengruppe ab. Wenn sich Ihr vorhandener 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 wieder aus. Die Azure-Bereitstellung selbst ist idempotent, sodass ein zweiter Durchlauf keinen Schaden anrichtet.

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