> 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 ## Ü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 Vorgänge derzeit unterstützt werden. Die folgenden Abschnitte zeigen, 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. Achten Sie außerdem darauf, [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. 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 einem Postfach eines Benutzers einen eMail-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 `Warteschlange`, `Wird ausgeführt`, `Abgeschlossen` und `Fehlgeschlagen` diesem Dokument. Beachten Sie, dass dies eine Vereinfachung zum Zweck eines besseren Verständnisses ist. ## Starten eines Runbook-Jobs Die RealmJoin API bietet zwei Endpunkte, um Runbooks auszulösen. `run` führt ein Runbook synchron aus und gibt erst dann 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 aber asynchron. Es gibt zurück, sobald ein Runbook-Job in die Warteschlange gestellt wurde. Es gibt die `jobID` zurück, um die einfache Nachverfolgung des neuen Jobs zu ermöglichen. ### 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 Scope (genau eines 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 [Benennungskonventionen](/de/automatisierung/runbooks/naming-conventions.md) für weitere Details. ### Beispiel Nehmen wir folgende Situation an: * Sie haben Ihre RealmJoin API-Anmeldedaten und haben 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 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ückgibt. Die Antwort wird den `jobID`, wird der `Status` (`Fehlgeschlagen` oder `Abgeschlossen`enthalten) sowie alle Ausgabestreams 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": "Verbose", "streamText": null, "value": null }, { "time": "2021-12-15T14:47:27.96063+00:00", "summary": "getAutomationConnectionOrFromLocalCertificate: Automation-Verbindung 'AzureRunAsConnection' wird abgerufen", "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": "## Benutzerzugriff für someone@contoso.com wurde widerrufen.", "streamType": "Output", "streamText": null, "value": null } ] } ``` Die Ausgabestreams sind in verschiedene Kanäle unterteilt (`streamTypes`): `Output`, `Verbose`, `Error`). Dadurch kann man nach Fehlern filtern oder die Ausgabe auf relevante Informationen reduzieren, indem nur `Output`. 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 ein Job bereits erstellt wurde, können Sie die RealmJoin API verwenden, um dessen Status und 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 Sie an, `jobID` sei `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 `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)wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel. Nehmen Sie an, `jobID` sei `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) ``` ## 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 `Output`, `Verbose` und `Error` 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 Sie an, `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 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: Wird im Azure Automation-Konto ausgeführt", "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`hinzufügen. Sie können auch filtern nach `Output` und `Error`. **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 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: Wird im Azure Automation-Konto ausgeführt", "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 `Output`, `Verbose` und `Error` Streams. Siehe [Streams lesen](#reading-specific-streams) um andere Streams zu lesen. Ausnahmen werden geschrieben, wenn bei der Ausführung des mit dem Runbook verbundenen PowerShell-Skripts unterbrechende Fehler auftreten. Dieser Endpunkt liest nur die Klartextmeldung und enthält keine technischen Details, wie etwa an welcher Codezeile das Skript gestoppt wurde. 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 Sie an, `jobID` sei `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, 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.