> 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 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, um die erfolgreiche Ausführung zuvor ausgelöster Läufe abzufragen. Siehe [die API-Referenz von RealmJoin](https://customer-api.realmjoin.com/scalar/v1) 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 vorausgesetzt, dass Sie bereits ein [Azure-Automation-Konto verbunden](/de/automatisierung/connecting-azure-automation.md) mit dem RealmJoin Portal verbunden haben. Stellen Sie außerdem sicher, zu [authentifizieren ](/de/dev-reference/realmjoin-api/authentication.md)jede Anfrage an die API von RealmJoin mit einem geeigneten HTTP-Autorisierungsheader zu authentifizieren. ## Wie behandelt Azure Automation Runbooks? Azure Automation verarbeitet Runbooks stapelweise. 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 wird also im Allgemeinen nicht sofort starten. Außerdem können mehrere Jobs für dasselbe Runbook gleichzeitig in unterschiedlichen Ausführungszuständen existieren. Jeder Job verfügt über einen Parametersatz (Eingaben), der an das Runbook-Skript übergeben wird. Das können z. B. zwei Variablen wie `$username` und `$newEmailAddress` wenn das Runbook einen E-Mail-Alias zu einem 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 Zweck des leichteren Verständnisses ist. ## Einen Runbook-Job starten Die API von RealmJoin 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` funktioniert jedoch asynchron. Es gibt zurück, sobald ein Runbook-Job in die Warteschlange gestellt wurde. Es gibt die `jobID` zurück, um die Nachverfolgung des neuen Jobs zu erleichtern. ### Benennung von Runbooks Runbooks werden in Azure Automation über ihren Namen adressiert. 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 eines 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](/de/automatisierung/runbooks/naming-conventions.md) für weitere Details. ### Beispiel Nehmen wir 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 verwenden den `run` Endpunkt, um sofort zu erkennen, ob der Job erfolgreich war. Lassen Sie uns die **Anfrage**: 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 enthält die `jobID`, die `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 im Azure-Automation-Konto ausgeführt", "streamType": "Ausführlich", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:27.96063+00:00", "summary": "getAutomationConnectionOrFromLocalCertificate: Abrufen der Automation-Verbindung 'AzureRunAsConnection'", "streamType": "Ausführlich", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:31.560861+00:00", "summary": "Connect-RjRbAzureAD: Verbindung 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 Ausgabeströme sind in verschiedene Kanäle unterteilt (`streamTypes`): `Ausgabe`, `Ausführlich`, `Fehler`. Dies ermöglicht es, nach Fehlern zu filtern oder die Ausgabe auf relevante Informationen zu reduzieren, indem nur `Ausgabe`. Sie können diese Streams nach Abschluss eines Runbooks mit dem `/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 ein Authorization-Header erstellt wird, ist das folgende nur ein Beispiel. Nehmen wir an, die `jobID` auf `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 ``` 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 umfasst nicht den `Ausführlich` und `Fehler` Stream. Siehe [Lesen von Streams](#reading-specific-streams) um andere Streams zu lesen. [Ausnahmen](#reading-exceptions) werden separat behandelt. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das folgende nur ein Beispiel. Nehmen wir an, die `jobID` auf `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 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`, `Ausführlich` und `Fehler` Stream zugreifen. [Ausnahmen](#reading-exceptions) werden separat behandelt. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das folgende nur ein Beispiel. Nehmen wir an, die `jobID` auf `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 im Azure-Automation-Konto ausgeführt", "streamType": "Ausführlich", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.3122219+00:00", "summary": "Reguläre 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, z. B. Verbose, erhalten möchten, 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 im 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 Ausnahmemeldung eines Runbooks zu erhalten (falls vorhanden). Dies umfasst nicht die `Ausgabe`, `Ausführlich` und `Fehler` Streams. Siehe [Lesen von Streams](#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 Klartextmeldung und enthält keine technischen Details, wie z. B. an welcher Codezeile das Skript angehalten hat. In unserem Beispiel wurde ein unterbrechender Fehler verursacht durch `throw "Exception"`. Siehe [Authentifizierung ](/de/dev-reference/realmjoin-api/authentication.md)wie ein Authorization-Header erstellt wird, ist das folgende nur ein Beispiel. Nehmen wir an, die `jobID` auf `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) ``` 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 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=&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.