Interaktion mit Runbooks

Runbooks ausführen und ihren Status über die RealmJoin-API abfragen

Übersicht

RealmJoin ermöglicht es Ihnen, Azure Automation Runbooks zu verwenden, um tägliche Abläufe in Ihrer Umgebung zu automatisieren. Siehe Runbooks 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 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 mit dem RealmJoin Portal. Achten Sie außerdem darauf, authentifizieren 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. 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 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:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run

Body (in JSON-Notation):

{ 
   "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 Abgeschlossenenthalten) sowie alle Ausgabestreams des Runbooks.

Antwort:

HTTP-Status: 200 (OK)

Body (in JSON-Notation):

{
    "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 wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen Sie an, jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anforderung

Header:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

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.

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 um andere Streams zu lesen. Ausnahmen werden separat behandelt.

Siehe Authentifizierung wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen Sie an, jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anforderung

Header:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

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 werden separat behandelt.

Siehe Authentifizierung 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:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

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)

[
    {
        "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

Um nur einen einzelnen Stream zu erhalten, zum Beispiel Verbose, können Sie der Anfrage einen Filter hinzufügen, indem Sie ?streamTypes=Verbosehinzufügen. Sie können auch filtern nach Output und Error.

Anfrage (Filter für einen einzelnen Stream)

Header:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

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)

[
    {
        "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 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 wie ein Authorization-Header erstellt wird, ist das Folgende nur ein Beispiel.

Nehmen Sie an, jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anforderung

Header:

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

Anfrage / URI:

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)

Zuletzt aktualisiert vor 5 Tagen

War das hilfreich?