> 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/dev-reference/interacting-with-runbooks.md).

# Interaktion mit Runbooks

Führen Sie Runbooks aus und fragen Sie ihren Status über die API von RealmJoin ab

## Übersicht

RealmJoin ermöglicht es Ihnen, Azure Automation Runbooks zu verwenden, um alltägliche Vorgänge in Ihrer Umgebung zu automatisieren. Siehe [Runbooks](https://docs.realmjoin.com/de/automatisierung/runbooks.md) für weitere Informationen.

Die API von RealmJoin ermöglicht es Ihnen, Runbooks aus Ihrer Anwendung zu starten und die erfolgreiche Ausführung zuvor ausgelöster Läufe abzufragen. Siehe [RealmJoin API-Referenz](https://customer-api.realmjoin.com/scalar/v1) um zu sehen, welche Vorgänge derzeit unterstützt werden.

Die folgenden Abschnitte erläutern, wie Sie die API von RealmJoin verwenden, um Runbook-Jobs zu starten und nachzuverfolgen. Es wird vorausgesetzt, dass Sie bereits [ein Azure Automation-Konto verbunden haben](https://docs.realmjoin.com/de/automatisierung/connecting-azure-automation.md) mit dem RealmJoin Portal verbunden. Stellen Sie außerdem sicher, dass Sie [authentifizieren ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md)jede Anfrage an die API von RealmJoin mit einem geeigneten HTTP Authorization-Header zu authentifizieren.

## Wie behandelt Azure Automation Runbooks?

Azure Automation verwendet für Runbooks einen Batchverarbeitungsansatz. Wenn Sie die Ausführung eines Runbooks auslösen, wird für dieses Runbook ein Job erstellt und zur Ausführung in die Warteschlange gestellt.

Ein Runbook startet daher im Allgemeinen nicht sofort. Außerdem können für dasselbe Runbook mehrere Jobs gleichzeitig in unterschiedlichen Ausführungszuständen existieren.

Jeder Job hat eine Reihe von Parametern (Eingaben), die an das Runbook-Skript übergeben werden. Das können z. B. zwei Variablen sein wie `$username` und `$newEmailAddress` wenn das Runbook einen E-Mail-Alias zu dem Postfach eines Benutzers hinzufügen soll.

Jeder Job hat einen Status, der seinen aktuellen Ausführungszustand darstellt, siehe [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). Wir konzentrieren uns auf `In Warteschlange`, `Wird ausgeführt`, `Abgeschlossen` und `Fehlgeschlagen` in diesem Dokument. Beachten Sie, dass dies eine Vereinfachung zum besseren Verständnis ist.

## Einen Runbook-Job starten

Die API von RealmJoin bietet zwei Endpunkte zum Auslösen von Runbooks.

`run` führt ein Runbook synchron aus und gibt erst zurück/beendet sich, wenn das Runbook tatsächlich abgeschlossen ist oder fehlgeschlagen ist. Dieser Endpunkt gibt direkt den Erfolgsstatus und die Ausgabe des zugehörigen Runbook-Jobs zurück.

`start` verwendet dieselben Parameter wie `run` arbeitet jedoch asynchron. Es gibt eine Antwort zurück, sobald ein Runbook-Job in die Warteschlange gestellt wurde. Es gibt die `jobID` zur einfachen Nachverfolgung des neuen Jobs zurück.

### Benennung von Runbooks

Runbooks werden in Azure Automation über ihren Namen angesprochen. Kurz gesagt:

* Wird es aus dem GitHub-Repo von RealmJoin synchronisiert? Fügen Sie `rjgit-`als Präfix hinzu
* Entweder `org_`, `device_`, `group_`, `user_` als Bereich (genau einer davon)
* Eine Kategorie, wie `general_`oder `security_`
* Der Name des Runbooks, getrennt durch `_` wie `add-xyz-exception`

Das Ergebnis wäre in diesem Fall: `rjgit-org_security_add-xyz-exception`

Siehe [Benennungskonventionen](https://docs.realmjoin.com/de/automatisierung/runbooks/naming-conventions.md) für weitere Details.

### Beispiel

Nehmen wir die folgende Situation an:

* Sie haben Ihre RealmJoin API-Anmeldeinformationen und sie kodiert zu `dC0xMjM0MTIzNDpteVMzY3JldCE=` (Base64)
* Sie möchten das Runbook starten `rjgit-user_security_revoke-or-restore-access` um die Anmeldung für einen bestimmten Benutzer zu blockieren
* Die Parameter für das Runbook (PowerShell) sind:
  * `$UserName = "someone@contoso.com"`
  * `$Revoke = $true`

Wir verwenden den `run` Endpunkt, um sofort zu erfahren, ob der Job erfolgreich war.

Erstellen wir die **anfordern**:

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```http
POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run
```

Body (in JSON-Notation):

```json
{ 
   "UserName": "someone@contoso.com", 
   "Revoke": true 
}
```

Die Anfrage wird eine Weile dauern, da sie auf die Ausführung des Jobs wartet. Bitte stellen Sie sicher, dass Sie das Timeout Ihres HTTP-Clients entsprechend anpassen. Andernfalls versuchen Sie, den `start` Endpunkt zu verwenden, der sofort zurückkehrt.

Die Antwort wird den `jobID`, die `Status` (`Fehlgeschlagen` oder `Abgeschlossen`) und alle Ausgabestreams des Runbooks.

**Antwort**:

HTTP-Status: `200` (OK)

Body (in JSON-Notation):

```json
{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Abgeschlossen",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Wird in einem Azure Automation-Konto ausgeführt",
            "streamType": "Ausführlich",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Hole die Automatisierungsverbindung 'AzureRunAsConnection'",
            "streamType": "Ausführlich",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Verbinde mit dem AzureAD-Modul: ...",
            "streamType": "Ausführlich",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## Der Benutzerzugriff für someone@contoso.com wurde widerrufen.",
            "streamType": "Ausgabe",
            "streamText": null,
            "value": null
        }
    ]
}
```

Die Ausgabestreams sind in verschiedene Kanäle unterteilt (`Streamtypen`): `Ausgabe`, `Ausführlich`, `Fehler`). Dadurch können Fehler gefiltert oder die Ausgabe auf relevante Informationen reduziert werden, indem nur `Ausgabe`.

Diese Streams können Sie abrufen, nachdem ein Runbook abgeschlossen ist, indem Sie den `/runbook/jobs/{jobID}/output/streams` Endpunkt verwenden. (siehe unten)

## Status und Ausgabe eines Jobs abfragen

Wenn ein Job bereits erstellt wurde, können Sie die API von RealmJoin verwenden, um seinen Status und seine Ausgabe abzufragen.

### Job-Status abfragen

Verwende `/runbook/jobs/{jobID}/status` um den aktuellen Status abzufragen.

Siehe [Authentifizierung ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen wir an, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345`

**`Anfrage`**

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status
```

Diese Anfrage hat keinen Body.

**Antwort**

HTTP-Status 200 (OK)

Body (Klartext)

```
Abgeschlossen
```

Zu den anderen möglichen Zuständen gehören `Neu`, `Fehlgeschlagen`, `Wird ausgeführt`. Siehe [mögliche Runbook-Zustände](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### Job-Ausgabe lesen

Verwende `/runbook/jobs/{jobID}/output/text` um eine einfache Klartextdarstellung der Ausgabe eines Runbooks zu erhalten. Diese enthält nicht den `Ausführlich` und `Fehler` Stream. Siehe [Streams lesen](#reading-specific-streams) um andere Streams zu lesen. [Ausnahmen](#reading-exceptions) werden separat behandelt.

Siehe [Authentifizierung ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen wir an, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345`

**Anfrage**

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text
```

Diese Anfrage hat keinen Body.

**Antwort**

HTTP-Status 200 (OK)

Body (Klartext)

```
## Die Verteilergruppe 'Sales Team' wurde erstellt.
```

### Bestimmte Streams lesen

Verwende `/runbook/jobs/{jobID}/output/streams` um eine vollständige JSON-Darstellung der Ausgabe eines Runbooks zu erhalten. Auf diese Weise können Sie auf den `Ausgabe`, `Ausführlich` und `Fehler` Stream zugreifen. [Ausnahmen](#reading-exceptions) werden separat behandelt.

Siehe [Authentifizierung ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen wir an, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345`

**Anfrage (alle Streams)**

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams
```

Diese Anfrage hat keinen Body.

**Antwort**

HTTP-Status 200 (OK)

Body (JSON, Array von Nachrichten)

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Wird in einem Azure Automation-Konto ausgeführt",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Normale Ausgabe",
        "streamType": "Ausgabe",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Ausführliche oder Debug-Nachricht",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Nicht unterbrechende Fehlermeldung",
        "streamType": "Fehler",
        "streamText": null,
        "value": null
    }
]
```

Siehe unten, um unterbrechende Fehlermeldungen und [Ausnahmen](#reading-exceptions)

Um nur einen einzelnen Stream zu erhalten, zum Beispiel Verbose, können Sie der Anfrage einen Filter hinzufügen, indem Sie `?streamTypes=Verbose`. Sie können auch filtern nach `Ausgabe` und `Fehler`.

**Anfrage (Filter für einen einzelnen Stream)**

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose
```

Diese Anfrage hat keinen Body.

**Antwort**

HTTP-Status 200 (OK)

Body (JSON, Array von Nachrichten)

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Wird in einem Azure Automation-Konto ausgeführt",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Ausführliche oder Debug-Nachricht",
        "streamType": "Ausführlich",
        "streamText": null,
        "value": null
    }
]
```

### Ausnahmen lesen

Verwende `/runbook/jobs/{jobID}/exception/text` um eine einfache Klartextdarstellung der Ausnahmemeldung eines Runbooks zu erhalten (falls vorhanden). Dies enthält nicht den `Ausgabe`, `Ausführlich` und `Fehler` Stream. Siehe [Streams lesen](#reading-specific-streams) um andere Streams zu lesen.

Ausnahmen werden geschrieben, wenn während der Ausführung des mit dem Runbook verknüpften PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Klartextmeldung und enthält keine technischen Details, etwa an welcher Codezeile das Skript angehalten hat.

In unserem Beispiel wurde ein unterbrechender Fehler verursacht durch `throw "Exception"`.

Siehe [Authentifizierung ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen wir an, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345`

**Anfrage**

Header:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

Anfrage / URI:

```html
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text
```

Diese Anfrage hat keinen Body.

**Antwort**

HTTP-Status 200 (OK)

Body (Klartext)

```
Exception (Exception)
```


---

# 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/dev-reference/interacting-with-runbooks.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.
