# Interaction avec les Runbooks

## Vue d’ensemble

RealmJoin vous permet d’utiliser les Runbooks Azure Automation pour automatiser les opérations quotidiennes dans votre environnement. Voir [Runbooks](https://docs.realmjoin.com/fr/automatisation/runbooks) pour plus d’informations.

L’API de RealmJoin vous permet de démarrer des runbooks depuis votre application et de demander l’exécution réussie des exécutions précédemment déclenchées. Voir [la description Swagger de RealmJoin](https://customer-api.realmjoin.com/swagger/index.html) 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 des jobs de runbook. Il est supposé que vous avez déjà [connecté un compte Azure Automation](https://docs.realmjoin.com/fr/automatisation/connecting-azure-automation) à RealmJoin Portal. Assurez-vous également de [authentifier ](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication)chaque requête auprès de l’API de RealmJoin à l’aide d’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 placé en file d’attente pour exécution.

En général, un runbook ne démarre donc pas immédiatement. De plus, plusieurs jobs pour le même runbook peuvent exister en même temps dans différents états d’exécution.

Chaque job dispose d’un ensemble de paramètres (entrées) transmis au script du runbook. Il peut s’agir par exemple de 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 d’exécution actuel, voir [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses). Nous nous concentrerons sur `Queued`, `Running`, `Completed` et `Failed` dans ce document. Sachez qu’il s’agit d’une simplification destinée à 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 la réponse que lorsque le runbook sera réellement terminé ou en échec. 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 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-il synchronisé depuis le dépôt GitHub de RealmJoin ? Ajoutez `rjgit-`comme préfixe
* Soit `org_`, `device_`, `group_`, `user_` comme portée (exactement une de celles-ci)
* 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](https://docs.realmjoin.com/fr/automatisation/runbooks/naming-conventions) pour plus de détails.

### Exemple

Supposons la situation suivante :

* Vous avez 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 = "someone@contoso.com"`
  * `$Revoke = $true`

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

Construisons les **demande**:

En-têtes :

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

Requête / URI :

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

Corps (en notation JSON) :

```json
{ 
   "UserName": "someone@contoso.com", 
   "Revoke": true 
}
```

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

La réponse contiendra le `jobID`, le `statut` (`Failed` ou `Completed`) ainsi que tous les flux de sortie du runbook.

**Réponse**:

Statut HTTP : `200` (OK)

Corps (en notation JSON) :

```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 someone@contoso.com a été révoqué.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}
```

Les flux de sortie sont séparés en différents canaux (`types de flux`): `Sortie`, `Verbose`, `Error`. Cela permet de filtrer les erreurs ou de réduire la sortie aux seules 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)

## Interrogation du statut et de 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.

### Interrogation du statut du job

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

Voir [Authentification ](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication)sur la façon de créer un en-tête Authorization, ce qui suit n’est qu’un exemple.

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

**`Demande`**

En-têtes :

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

Requête / URI :

```html
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)

```
Completed
```

D’autres états possibles incluent `New`, `Failed`, `Running`. Voir [états possibles du Runbook](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### Lecture de la sortie du job

Utilisez `/runbook/jobs/{jobID}/output/text` pour obtenir une représentation texte brut simple de la sortie d’un runbook. Cela n’inclura pas le `Verbose` et `Error` flux. Voir [lecture des flux](#reading-specific-streams) pour lire les autres flux. [Exceptions](#reading-exceptions) sont gérées séparément.

Voir [Authentification ](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication)sur la façon de créer un en-tête Authorization, ce qui suit n’est qu’un exemple.

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

**Demande**

En-têtes :

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

Requête / URI :

```html
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éé.
```

### Lecture de 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 `Error` flux. [Exceptions](#reading-exceptions) sont gérées séparément.

Voir [Authentification ](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication)sur la façon de créer 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 :

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

Requête / URI :

```html
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)

```json
[
    {
        "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 normale",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Message Verbose ou Debug",
        "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 les [exceptions](#reading-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 pour `Sortie` et `Error`.

**Requête (filtrer pour un seul flux)**

En-têtes :

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

Requête / URI :

```html
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)

```json
[
    {
        "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 Verbose ou Debug",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]
```

### Lecture des exceptions

Utilisez `/runbook/jobs/{jobID}/exception/text` pour obtenir une représentation simple en texte brut du message d’exception d’un runbook (si présent). Cela n’inclura pas les `Sortie`, `Verbose` et `Error` flux. Voir [lecture des flux](#reading-specific-streams) pour lire les autres flux.

Les exceptions sont écrites lorsque des erreurs interrompantes surviennent lors de l’exécution du script PowerShell associé au runbook. Ce point de terminaison ne lit que le message en texte brut et n’inclut pas de 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 ](https://docs.realmjoin.com/fr/dev-reference/realmjoin-api/authentication)sur la façon de créer un en-tête Authorization, ce qui suit n’est qu’un exemple.

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

**Demande**

En-têtes :

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

Requête / URI :

```html
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)
```