Interaktion mit Runbooks

Führen Sie Runbooks aus und fragen Sie deren Status über die RealmJoin-API ab

Übersicht

RealmJoin ermöglicht Ihnen, Azure Automation Runbooks zu verwenden, um tägliche Vorgänge in Ihrer Umgebung zu automatisieren. Siehe Runbooks für weitere Informationen.

Die RealmJoin-API ermöglicht es Ihnen, Runbooks aus Ihrer Anwendung zu starten und die erfolgreiche Ausführung zuvor ausgelöster Läufe abzufragen. Siehe RealmJoin's Swagger-Beschreibung um zu sehen, welche Operationen derzeit unterstützt werden.

Die folgenden Abschnitte erläutern, wie die RealmJoin-API verwendet wird, um Runbook-Jobs zu starten und zu verfolgen. Es wird davon ausgegangen, dass Sie bereits ein Azure Automation-Konto verbunden mit dem RealmJoin-Portal. Stellen Sie außerdem sicher, dass Sie authentifizieren jede Anfrage an die RealmJoin-API mit einem geeigneten HTTP Authorization-Header.

Wie handhabt Azure Automation Runbooks?

Azure Automation verwendet einen Batch-Verarbeitungsansatz für Runbooks. Wenn Sie die Ausführung eines Runbooks auslösen, wird ein Job für dieses Runbook erstellt und zur Ausführung in die Warteschlange gestellt.

Ein Runbook startet also im Allgemeinen nicht sofort. Außerdem können mehrere Jobs für dasselbe Runbook gleichzeitig in unterschiedlichen Ausführungszuständen existieren.

Jeder Job verfügt über eine Reihe von Parametern (Eingaben), die an das Runbook-Skript übergeben werden. Das können z. B. zwei Variablen wie $username als auch für $newEmailAddress sein, 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. Wir konzentrieren uns auf In Warteschlange, Wird ausgeführt, Abgeschlossen als auch für Fehlgeschlagen in diesem Dokument. Beachten Sie, dass dies eine Vereinfachung zum leichteren Verständnis ist.

Starten eines Runbook-Jobs

Die RealmJoin-API bietet zwei Endpunkte zum Auslösen von Runbooks.

run führt ein Runbook synchron aus und gibt nur zurück/beendet erst, 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 nimmt dieselben Parameter wie run arbeitet jedoch asynchron. Er gibt zurück, sobald ein Runbook-Job in die Warteschlange gestellt wurde. Er wird die jobID zur einfachen Nachverfolgung des neuen Jobs zurückgeben.

Benennung von Runbooks

Runbooks werden in Azure Automation über ihren Namen angesprochen. Kurz gesagt:

• Wird es aus RealmJoin's GitHub-Repo synchronisiert? Füge rjgit-als Präfix hinzu

• Entweder org_, device_, group_, user_ als Bereich (genau einer 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 für weitere Details.

Beispiel

Gehen wir von der folgenden Situation aus:

• Sie haben Ihre RealmJoin-API-Anmeldeinformationen und haben diese 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 = "[email protected]"

  • $Revoke = $true

Wir werden den run Endpunkt verwenden, um sofort zu wissen, ob der Job erfolgreich war.

Lassen Sie uns die Anfrage:

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": "[email protected]", 
   "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, 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):

{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Getting automation connection 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Connecting with AzureAD module: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## User access for [email protected] has been revoked.",
            "streamType": "Output",
            "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 abrufen, nachdem ein Runbook beendet ist, mithilfe des /runbook/jobs/{jobID}/output/streams Endpunkts. (siehe unten)

Abfragen 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.

Abfrage des Job-Status

Verwenden Sie /runbook/jobs/{jobID}/status um den aktuellen Status abzufragen.

Siehe Authentifizierung zur Erstellung eines Authorization-Headers, das Folgende ist nur ein Beispiel.

Angenommen die jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anfrage

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

Andere mögliche Zustände umfassen Neu, Fehlgeschlagen, Wird ausgeführt. Siehe mögliche Runbook-Zustände.

Ausgabe eines Jobs lesen

Verwenden Sie /runbook/jobs/{jobID}/output/text um eine einfache Klartextdarstellung der Ausgabe eines Runbooks zu erhalten. Dies wird den Ausführlich als auch für Fehler Stream nicht enthalten. Siehe Streams lesen um andere Streams zu lesen. Ausnahmen werden separat behandelt.

Siehe Authentifizierung zur Erstellung eines Authorization-Headers, das Folgende ist nur ein Beispiel.

Angenommen die jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anfrage

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 Ausgabe, Ausführlich als auch für Fehler Stream zugreifen. Ausnahmen werden separat behandelt.

Siehe Authentifizierung zur Erstellung eines Authorization-Headers, das Folgende ist nur ein Beispiel.

Angenommen die 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": "Lade Modul aus Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Lade Modul aus Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
        "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": "Ausführliche 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=Verboseanhängen. Sie können auch nach filtern Ausgabe als auch für Fehler.

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": "Lade Modul aus Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Lade Modul aus Pfad 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Ausführliche 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 wird die Ausgabe, Ausführlich als auch für Fehler Streams nicht enthalten. Siehe Streams lesen um andere Streams zu lesen.

Ausnahmen werden geschrieben, wenn unterbrechende Fehler bei der Ausführung des mit dem Runbook verknüpften PowerShell-Skripts auftreten. Dieser Endpunkt liest nur die Klartextnachricht und enthält keine technischen Details, wie z. B. in welcher Codezeile das Skript gestoppt wurde.

In unserem Beispiel wurde ein unterbrechender Fehler verursacht durch throw "Exception".

Siehe Authentifizierung zur Erstellung eines Authorization-Headers, das Folgende ist nur ein Beispiel.

Angenommen die jobID sei 1234545e-7a24-436a-90c9-6056b512345

Anfrage

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)

Exception (Exception)