# Interaktion mit Runbooks

## Übersicht

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

Die API von RealmJoin ermöglicht es Ihnen, Runbooks aus Ihrer Anwendung heraus zu starten, um die erfolgreiche Ausführung zuvor ausgelöster Läufe abzufragen. Siehe [die Swagger-Beschreibung von RealmJoin](https://customer-api.realmjoin.com/swagger/index.html) 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 davon ausgegangen, dass Sie bereits [ein Azure Automation-Konto verbunden haben](https://docs.realmjoin.com/de/automatisierung/connecting-azure-automation) mit dem RealmJoin Portal. Stellen Sie außerdem sicher, dass Sie [authentifizieren ](https://docs.realmjoin.com/de/dev-reference/realmjoin-api/authentication)jede Anfrage an die API von RealmJoin mithilfe eines geeigneten HTTP-Authorization-Headers.

## Wie behandelt Azure Automation Runbooks?

Azure Automation verfolgt bei Runbooks einen Batch-Verarbeitungsansatz. 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.

Im Allgemeinen wird ein Runbook also nicht sofort gestartet. Außerdem können mehrere Jobs für dasselbe Runbook gleichzeitig in unterschiedlichen Ausführungszuständen existieren.

Jeder Job verfügt über eine Reihe von Parametern (Eingaben), die an das Runbook-Skript übergeben werden. Dies können z. B. zwei Variablen wie `$username` und `$newEmailAddress` sein, wenn das Runbook einem Postfach eines Benutzers einen E-Mail-Alias 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 in diesem Dokument auf `Queued`, `Running`, `Completed` und `Failed` . Beachten Sie, dass dies eine Vereinfachung zum Zweck des leichteren Verständnisses ist.

## Starten eines Runbook-Jobs

Die RealmJoin API 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 oder fehlgeschlagen ist. Dieser Endpunkt gibt direkt den Erfolgsstatus und die Ausgabe des zugehörigen Runbook-Jobs zurück.

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

### Runbook-Benennung

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

### Beispiel

Nehmen wir die folgende Situation an:

* Sie haben Ihre RealmJoin-API-Anmeldedaten und diese 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 sperren
* Die Parameter für das Runbook (PowerShell) sind:
  * `$UserName = "someone@contoso.com"`
  * `$Revoke = $true`

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

Lassen Sie uns die **Anfrage**:

Header erstellen:

```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 Ihrer HTTP-Clients entsprechend anpassen. Versuchen Sie andernfalls, den `start` Endpunkt zu verwenden, der sofort zurückgibt.

Die Antwort enthält den `jobID`ist der `Status` (`Failed` oder `Completed`) und alle Ausgabestreams des Runbooks.

**Antwort**:

HTTP-Status: `200` (OK)

Body (in JSON-Notation):

```json
{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Läuft in einem Azure Automation-Konto",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Abrufen der Automatisierungsverbindung 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Verbindung mit AzureAD-Modul wird hergestellt: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## Der Benutzerzugriff für someone@contoso.com wurde widerrufen.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}
```

Die Ausgabestreams sind in verschiedene Kanäle unterteilt (`streamTypes`): `Ausgabe`, `Verbose`, `Error`. Dies ermöglicht das Filtern nach Fehlern oder das Reduzieren der Ausgabe auf relevante Informationen, indem nur `Ausgabe`.

Sie können diese Streams nach Abschluss eines Runbooks über den `/runbook/jobs/{jobID}/output/streams` Endpunkt abrufen. (siehe unten)

## Abfrage des Status und der Ausgabe eines Jobs

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

### Abfrage des Job-Status

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

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

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

**`Anfrage`**

Header erstellen:

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

```
Completed
```

Weitere mögliche Zustände sind `New`, `Failed`, `Running`. Siehe [mögliche Runbook-Zustände](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### Lesen der Job-Ausgabe

Verwenden Sie `/runbook/jobs/{jobID}/output/text` um eine einfache Klartextdarstellung der Ausgabe eines Runbooks zu erhalten. Dies enthält nicht den `Verbose` und `Error` 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)Wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

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

**Anfrage**

Header erstellen:

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

### Lesen spezifischer Streams

Verwenden Sie `/runbook/jobs/{jobID}/output/streams` um eine umfassende JSON-Darstellung der Ausgabe eines Runbooks zu erhalten. Auf diese Weise können Sie auf den `Ausgabe`, `Verbose` und `Error` Stream zugreifen. [Ausnahmen](#reading-exceptions) werden separat behandelt.

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

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

**Anfrage (alle Streams)**

Header erstellen:

```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": "Modul wird aus dem Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' geladen.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Modul wird aus dem Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' geladen.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Läuft in einem Azure Automation-Konto",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Reguläre Ausgabe",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose- oder Debug-Nachricht",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Nicht unterbrechende Fehlermeldung",
        "streamType": "Error",
        "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`hinzufügen. Sie können auch filtern nach `Ausgabe` und `Error`.

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

Header erstellen:

```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": "Modul wird aus dem Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' geladen.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Modul wird aus dem Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' geladen.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Läuft in einem Azure Automation-Konto",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose- oder Debug-Nachricht",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]
```

### Ausnahmen lesen

Verwenden Sie `/runbook/jobs/{jobID}/exception/text` um eine einfache Klartextdarstellung der Ausnahmemeldung eines Runbooks zu erhalten (falls vorhanden). Dies enthält nicht die `Ausgabe`, `Verbose` und `Error` Streams. Siehe [Streams lesen](#reading-specific-streams) um andere Streams zu lesen.

Ausnahmen werden geschrieben, wenn bei der Ausführung des dem Runbook zugeordneten PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Klartextnachricht 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)Wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

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

**Anfrage**

Header erstellen:

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

```
Ausnahme (Exception)
```