# Arbeiten mit Runbooks ## Übersicht RealmJoin ermöglicht es Ihnen, Azure Automation Runbooks zu verwenden, um tägliche Abläufe in Ihrer Umgebung zu automatisieren. Siehe [Runbooks](/de/automatisierung/runbooks.md) 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 Operationen derzeit unterstützt werden. Die folgenden Abschnitte erläutern, wie Sie die API von RealmJoin verwenden, um Runbook-Jobs zu starten und zu verfolgen. Es wird davon ausgegangen, dass Sie bereits [ein Azure Automation-Konto verbunden](/de/automatisierung/connecting-azure-automation.md) mit dem RealmJoin Portal haben. Stellen Sie außerdem sicher, [authentifizieren ](/de/dev-reference/realmjoin-api/authentication.md)jede Anfrage an die API von RealmJoin mit einem geeigneten HTTP-Authorization-Header. ## 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. Daher wird ein Runbook im Allgemeinen nicht sofort starten. Außerdem können mehrere Jobs für dasselbe Runbook gleichzeitig in unterschiedlichen Ausführungszuständen existieren. Jeder Job hat eine Reihe von Parametern (Eingaben), die an das Runbook-Skript übergeben werden. Dies können z. B. zwei Variablen sein wie `$username` und `$newEmailAddress` 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 zur leichteren Verständlichkeit eine Vereinfachung ist. ## Starten eines Runbook-Jobs Die RealmJoin API bietet zwei Endpunkte, um Runbooks auszulösen. `run` führt ein Runbook synchron aus und gibt/beendet erst dann, 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` verwendet dieselben Parameter wie `run` 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 [Namenskonventionen](/de/automatisierung/runbooks/naming-conventions.md) . ### Beispiel Nehmen wir die folgende Situation an: * Sie haben Ihre RealmJoin-API-Anmeldedaten 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 werden den `run` Endpunkt verwenden, um sofort zu wissen, ob der Job erfolgreich war. Lassen Sie uns den **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 Ihres HTTP-Clients entsprechend anpassen. Versuchen Sie andernfalls, den `start` Endpunkt zu verwenden, der sofort zurückgibt. Die Antwort enthält den `jobID`wird 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 im Azure Automation-Konto", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:27.96063+00:00", "summary": "getAutomationConnectionOrFromLocalCertificate: Abrufen der Automation-Verbindung 'AzureRunAsConnection'", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:31.560861+00:00", "summary": "Connect-RjRbAzureAD: Verbinden mit AzureAD-Modul: ...", "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 aufgeteilt (`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) ## Abfragen des Status und der Ausgabe eines Jobs Wenn ein Job bereits erstellt wurde, können Sie die RealmJoin API verwenden, um seinen Status und seine Ausgabe abzufragen. ### Abfragen des Job-Status Verwenden Sie `/runbook/jobs/{jobID}/status` um den aktuellen Status abzufragen. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Nehmen Sie an, die `jobID` soll `1234545e-7a24-436a-90c9-6056b512345` **`Anforderung`** 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 unter anderem `New`, `Failed`, `Running`. Siehe [mögliche Runbook-Zustände](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). ### Job-Ausgabe lesen 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 ](/de/dev-reference/realmjoin-api/authentication.md)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Nehmen Sie an, die `jobID` soll `1234545e-7a24-436a-90c9-6056b512345` **Anforderung** 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. ``` ### Spezifische Streams lesen 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 ](/de/dev-reference/realmjoin-api/authentication.md)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Nehmen Sie an, die `jobID` soll `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 von 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 von 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 im Azure Automation-Konto", "streamType": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.3122219+00:00", "summary": "Normale 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`. Sie können auch 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 von 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 von 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 im 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 während der Ausführung des dem Runbook zugeordneten PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Klartextmeldung und enthält keine technischen Details, wie etwa in welcher Codezeile das Skript angehalten wurde. In unserem Beispiel wurde ein unterbrechender Fehler verursacht durch `throw "Exception"`. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Nehmen Sie an, die `jobID` soll `1234545e-7a24-436a-90c9-6056b512345` **Anforderung** 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) ``` Exception (Exception) ``` --- # Agent Instructions: 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: ``` GET https://docs.realmjoin.com/de/dev-reference/interacting-with-runbooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.