Interaction avec les runbooks

Exécutez des runbooks et interrogez leur état en utilisant l'API de RealmJoin

onglet Vue d'ensemble

RealmJoin vous permet d'utiliser les Runbooks Azure Automation pour automatiser les opérations quotidiennes dans votre environnement. Voir Runbooks pour plus d'informations.

L'API de RealmJoin vous permet de démarrer des runbooks depuis votre application, et de consulter l'exécution réussie des exécutions précédemment déclenchées. Voir la description Swagger de RealmJoin pour voir quelles opérations sont actuellement prises en charge.

Les sections suivantes expliquent comment utiliser l'API de RealmJoin pour démarrer et suivre les jobs de runbook. On suppose que vous avez déjà connecté un compte Azure Automation au portail RealmJoin. Assurez-vous également de vous authentifier pour chaque requête vers l'API de RealmJoin en utilisant un en-tête http Authorization approprié.

Comment Azure Automation gère-t-il les runbooks ?

Azure Automation adopte une approche de traitement par lots pour les runbooks. Lorsque vous déclenchez l'exécution d'un runbook, un job est créé pour ce runbook et mis en file d'attente pour exécution.

Ainsi, en général, un runbook ne commencera pas immédiatement. De plus, plusieurs jobs pour le même runbook peuvent exister simultanément dans différents états d'exécution.

Chaque job a un ensemble de paramètres (entrées) qui sont transmis au script du runbook. Cela peut par exemple être deux variables comme $username et $newEmailAddress si le runbook est censé ajouter un alias e-mail à la boîte aux lettres d'un utilisateur.

Chaque job a un statut qui représente son état actuel d'exécution, voir Microsoft Docs. Nous nous concentrerons sur En file d'attente, En cours, Terminé et Échoué dans ce document. Sachez qu'il s'agit d'une simplification pour faciliter la compréhension.

Démarrer un job de Runbook

L'API RealmJoin propose deux points de terminaison pour déclencher des runbooks.

run exécutera un runbook de manière synchrone et ne renverra/terminera que lorsque le runbook sera effectivement terminé ou échoué. Ce point de terminaison renvoie directement l'état de réussite et la sortie du job de runbook associé.

start prendra les mêmes paramètres que run mais fonctionne de manière asynchrone. Il renverra dès qu'un job de runbook est mis en file d'attente. Il renverra le jobID pour permettre un suivi facile du nouveau job.

Nommage des Runbooks

Les runbooks sont adressés par leur nom dans Azure Automation. En bref :

• Est-ce synchronisé depuis le dépôt GitHub de RealmJoin ? Ajoutez préfixe rjgit-comme préfixe

• Soit org_, device_, group_, user_ comme portée (exactement l'un d'entre eux)

• Une catégorie, comme general_ou security_

• Le nom du runbook, séparé par _ comme add-xyz-exception

Le résultat dans ce cas serait : rjgit-org_security_add-xyz-exception

Voir Conventions de nommage pour plus de détails.

Exemple

Partons de la situation suivante :

• Vous disposez de vos identifiants API RealmJoin et les avez encodés en dC0xMjM0MTIzNDpteVMzY3JldCE= (Base64)

• Vous souhaitez démarrer le runbook rjgit-user_security_revoke-or-restore-access pour bloquer la connexion d'un utilisateur spécifique

• Les paramètres du runbook (PowerShell) sont :

  • $UserName = "[email protected]"

  • $Revoke = $true

Nous utiliserons le run point de terminaison pour savoir immédiatement si le job a réussi.

Construisons le demande:

En-têtes :

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

Requête / URI :

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

Corps (en notation JSON) :

{ 
   "UserName": "[email protected]", 
   "Revoke": true 
}

La requête prendra un certain temps, car elle attend l'exécution du job. Veuillez vous assurer d'adapter le timeout de votre client HTTP en conséquence. Sinon, essayez d'utiliser le start point de terminaison, qui renverra immédiatement.

La réponse contiendra le jobID, le statut (Échoué ou Terminé) et tous les flux de sortie du runbook.

Réponse:

Statut HTTP : 200 (OK)

Corps (en notation JSON) :

{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper : Exécution dans le compte Azure Automation",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate : Obtention de la connexion d'automatisation 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD : Connexion avec le module AzureAD : ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## L'accès utilisateur pour [email protected] a été révoqué.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

Les flux de sortie sont séparés en différents canaux (streamTypes): Sortie, Verbose, Erreur. Cela permet de filtrer les erreurs ou de réduire la sortie uniquement aux informations pertinentes en n'affichant que Sortie.

Vous pouvez obtenir ces flux après la fin d'un runbook en utilisant le /runbook/jobs/{jobID}/output/streams point de terminaison. (voir ci-dessous)

Interroger le statut et la sortie d'un job

Si un job a déjà été créé, vous pouvez utiliser l'API RealmJoin pour interroger son état et sa sortie.

Interroger le statut d'un job

Utilisez /runbook/jobs/{jobID}/status pour interroger le statut actuel.

Voir Authentification sur la création d'un en-tête Authorization, ce qui suit n'est qu'un exemple.

Supposons que le jobID soit 1234545e-7a24-436a-90c9-6056b512345

Requête

En-têtes :

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

Requête / URI :

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status

Cette requête n'a pas de corps.

Réponse

Statut HTTP 200 (OK)

Corps (texte brut)

Terminé

D'autres états possibles incluent Nouveau, Échoué, En cours. Voir états possibles des Runbooks.

Lire la sortie d'un job

Utilisez /runbook/jobs/{jobID}/output/text pour obtenir une représentation simple en texte brut de la sortie d'un runbook. Cela n'inclura pas le Verbose et Erreur flux. Voir lecture des flux pour lire d'autres flux. Exceptions sont traités séparément.

Voir Authentification sur la création d'un en-tête Authorization, ce qui suit n'est qu'un exemple.

Supposons que le jobID soit 1234545e-7a24-436a-90c9-6056b512345

Requête

En-têtes :

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

Requête / URI :

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text

Cette requête n'a pas de corps.

Réponse

Statut HTTP 200 (OK)

Corps (texte brut)

## Le groupe de distribution 'Sales Team' a été créé.

Lire des flux spécifiques

Utilisez /runbook/jobs/{jobID}/output/streams pour obtenir une représentation JSON complète de la sortie d'un runbook. De cette façon, vous pouvez accéder au Sortie, Verbose et Erreur flux. Exceptions sont traités séparément.

Voir Authentification sur la création d'un en-tête Authorization, ce qui suit n'est qu'un exemple.

Supposons que le jobID soit 1234545e-7a24-436a-90c9-6056b512345

Requête (tous les flux)

En-têtes :

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

Requête / URI :

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams

Cette requête n'a pas de corps.

Réponse

Statut HTTP 200 (OK)

Corps (JSON, tableau de messages)

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Chargement du module depuis le chemin 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Chargement du module depuis le chemin '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 : Exécution dans le compte Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Sortie régulière",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Message Verbeux ou de Débogage",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Message d'erreur non interrompant",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]

Voir ci-dessous pour lire les messages d'erreur interrompants et exceptions

Pour ne recevoir qu'un seul flux, par exemple Verbose, vous pouvez ajouter un filtre à la requête en ajoutant ?streamTypes=Verbose. Vous pouvez également filtrer par Sortie et Erreur.

Requête (filtrer pour un seul flux)

En-têtes :

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

Requête / URI :

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose

Cette requête n'a pas de corps.

Réponse

Statut HTTP 200 (OK)

Corps (JSON, tableau de messages)

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Chargement du module depuis le chemin 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Chargement du module depuis le chemin '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 : Exécution dans le compte Azure Automation",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Message Verbeux ou de Débogage",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]

Lecture des exceptions

Utilisez /runbook/jobs/{jobID}/exception/text pour obtenir une représentation en texte brut du message d'exception d'un runbook (si présent). Cela n'inclura pas les Sortie, Verbose et Erreur flux. Voir lecture des flux pour lire d'autres flux.

Les exceptions sont écrites lorsqu'une erreur interrompante survient lors de l'exécution du script PowerShell associé au runbook. Ce point de terminaison lira uniquement le message en texte brut et n'inclut pas les détails techniques, comme la ligne de code à laquelle le script s'est arrêté.

Dans notre exemple, une erreur interrompante a été causée par throw "Exception".

Voir Authentification sur la création d'un en-tête Authorization, ce qui suit n'est qu'un exemple.

Supposons que le jobID soit 1234545e-7a24-436a-90c9-6056b512345

Requête

En-têtes :

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

Requête / URI :

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text

Cette requête n'a pas de corps.

Réponse

Statut HTTP 200 (OK)

Corps (texte brut)

Exception (Exception)