> 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). # Mit Runbooks interagieren ## Ü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 zu starten und 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 zu verfolgen. Es wird vorausgesetzt, dass Sie bereits [ein Azure Automation-Konto verbunden haben](/de/automatisierung/connecting-azure-automation.md) mit dem RealmJoin Portal. Stellen Sie außerdem sicher, dass [sich zu authentifizieren ](/de/dev-reference/realmjoin-api/authentication.md)jede Anfrage an die API von RealmJoin über einen geeigneten http Authorization-Header zu authentifizieren. ## Wie behandelt Azure Automation Runbooks? Azure Automation verwendet bei 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. Im Allgemeinen wird ein Runbook also nicht sofort starten. Außerdem können mehrere Jobs für dasselbe Runbook gleichzeitig in unterschiedlichen Ausführungszuständen existieren. Jeder Job hat einen Satz von Parametern (Eingaben), die an das Runbook-Skript weitergegeben werden. Das können z. B. zwei Variablen sein wie `$username` und `$newEmailAddress` wenn das Runbook einen E-Mail-Alias zum 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. Bitte beachten Sie, dass dies zur leichteren Verständlichkeit eine Vereinfachung ist. ## Einen Runbook-Job starten Die RealmJoin API bietet zwei Endpunkte, um Runbooks auszulösen. `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` 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. ### Benennung von Runbooks Runbooks werden in Azure Automation über ihren Namen angesprochen. Kurz gesagt: * Wird es aus dem GitHub-Repository von RealmJoin synchronisiert? Fügen Sie `rjgit-`als Präfix hinzu * Entweder `org_`, `device_`, `group_`, `user_` als Bereich hinzu (genau einen 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) für weitere Details. ### Beispiel Nehmen wir folgende Situation an: * Sie haben Ihre RealmJoin-API-Anmeldedaten und sie 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. Lassen Sie uns 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. Versuchen Sie andernfalls die Verwendung des `start` Endpunkts, der sofort zurückgegeben wird. Die Antwort enthält den `jobID`wird der `Status` (`Fehlgeschlagen` oder `Abgeschlossen`) und alle Ausgabeströme 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: Automatisierungsverbindung 'AzureRunAsConnection' wird abgerufen", "streamType": "Ausführlich", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:31.560861+00:00", "summary": "Connect-RjRbAzureAD: Verbindung mit dem AzureAD-Modul wird hergestellt: ...", "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 Ausgabeströme werden in verschiedene Kanäle unterteilt (`Streamtypen`): `Ausgabe`, `Ausführlich`, `Fehler`. Dadurch können Sie nach Fehlern filtern oder die Ausgabe auf relevante Informationen reduzieren, indem nur `Ausgabe`. Sie können diese Streams nach Abschluss eines Runbooks über den `/runbook/jobs/{jobID}/output/streams` Endpunkt abrufen. (siehe unten) ## Status und Ausgabe eines Jobs abfragen Wenn ein Job bereits erstellt wurde, können Sie die API von RealmJoin verwenden, um seinen Zustand und seine Ausgabe abzufragen. ### Job-Status abfragen Verwenden Sie `/runbook/jobs/{jobID}/status` um den aktuellen Status abzufragen. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)wie man einen Authorization-Header erstellt, das Folgende ist nur ein Beispiel. Nehmen Sie an, dass die `jobID` folgendermaßen lautet `1234545e-7a24-436a-90c9-6056b512345` **`Anforderung`** 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 ``` Weitere mögliche Zustände sind `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 Verwenden Sie `/runbook/jobs/{jobID}/output/text` um eine einfache Klartextdarstellung der Ausgabe eines Runbooks zu erhalten. Dies 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 ](/de/dev-reference/realmjoin-api/authentication.md)wie man einen Authorization-Header erstellt, das Folgende ist nur ein Beispiel. Nehmen Sie an, dass die `jobID` folgendermaßen lautet `1234545e-7a24-436a-90c9-6056b512345` **Anforderung** 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 Verteilungsgruppe 'Sales Team' wurde erstellt. ``` ### Bestimmte Streams lesen Verwenden Sie `/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 ](/de/dev-reference/realmjoin-api/authentication.md)wie man einen Authorization-Header erstellt, das Folgende ist nur ein Beispiel. Nehmen Sie an, dass die `jobID` folgendermaßen lautet `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": "Modul wird von Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' geladen.", "streamType": "Ausführlich", "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": "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) Wenn Sie nur einen einzelnen Stream erhalten möchten, zum Beispiel Ausführlich, 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": "Modul wird von Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' geladen.", "streamType": "Ausführlich", "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": "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 Verwenden Sie `/runbook/jobs/{jobID}/exception/text` um eine einfache Klartextdarstellung der Ausnahme-Nachricht eines Runbooks zu erhalten (falls vorhanden). Dies enthält nicht die `Ausgabe`, `Ausführlich` und `Fehler` Streams. Siehe [Streams lesen](#reading-specific-streams) um andere Streams zu lesen. Ausnahmen werden protokolliert, wenn bei der Ausführung des mit dem Runbook verknüpften PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Klartextnachricht und enthält keine technischen Details, wie etwa die Zeile im Code, an der das Skript angehalten wurde. In unserem Beispiel wurde ein unterbrechender Fehler verursacht durch `throw "Exception"`. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)wie man einen Authorization-Header erstellt, das Folgende ist nur ein Beispiel. Nehmen Sie an, dass die `jobID` folgendermaßen lautet `1234545e-7a24-436a-90c9-6056b512345` **Anforderung** 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) ``` Ausnahme (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 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.