> 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 ## Überblick 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 nachzuverfolgen. Es wird vorausgesetzt, dass Sie bereits [ein Azure Automation-Konto verbunden](/de/automatisierung/connecting-azure-automation.md) mit dem RealmJoin Portal. Stellen Sie außerdem sicher, dass Sie [authentifizieren ](/de/dev-reference/realmjoin-api/authentication.md)jede Anfrage an RealmJoin's API mit einem geeigneten HTTP-Authorization-Header. ## 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 startet ein Runbook also nicht sofort. Außerdem können für dasselbe Runbook gleichzeitig mehrere Jobs in unterschiedlichen Ausführungszuständen existieren. Jeder Job hat einen Satz 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 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 zur leichteren Verständlichkeit eine Vereinfachung ist. ## Einen Runbook-Job starten Die RealmJoin API bietet zwei Endpunkte, um Runbooks auszulösen. `ausführen` 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. `starten` verwendet dieselben Parameter wie `ausführen` arbeitet jedoch asynchron. Es gibt zurück, sobald ein Runbook-Job in die Warteschlange gestellt wurde. Es gibt die `jobID` zurück, um das Nachverfolgen des neuen Jobs zu erleichtern. ### 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 einen davon) * Eine Kategorie, wie `general_`oder `security_` * Der Name des Runbooks, getrennt durch `_` wie `add-xyz-exception` Das Ergebnis in diesem Fall wäre: `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 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 `ausführen` Endpunkt, um sofort zu erfahren, ob der Job erfolgreich war. Lassen Sie uns das **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 `starten` Endpunkt zu verwenden, der sofort zurückkehrt. 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: Läuft im Azure Automation-Konto", "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 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`. Dadurch können Sie nach Fehlern filtern oder die Ausgabe auf relevante Informationen reduzieren, indem Sie 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)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Angenommen, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345` **`Auf 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 Klartext-Darstellung 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)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Angenommen, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345` **Auf 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 Verteilungsgruppe '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`, `Ausführlich` und `Fehler` 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. Angenommen, 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": "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: Läuft im Azure Automation-Konto", "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-Meldung", "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, zum Beispiel 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 (nach einem einzelnen Stream filtern)** 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: Läuft im Azure Automation-Konto", "streamType": "Ausführlich", "streamText": null, "value": null }, { "time": "2021-12-20T08:37:47.8422225+00:00", "summary": "Ausführliche oder Debug-Meldung", "streamType": "Ausführlich", "streamText": null, "value": null } ] ``` ### Ausnahmen lesen Verwenden Sie `/runbook/jobs/{jobID}/exception/text` um eine einfache Klartext-Darstellung der Ausnahmemeldung 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 geschrieben, wenn bei der Ausführung des dem Runbook zugeordneten PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Nur-Text-Nachricht 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)zur Erstellung eines Authorization-Headers; das Folgende ist nur ein Beispiel. Angenommen, die `jobID` sei `1234545e-7a24-436a-90c9-6056b512345` **Auf 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.