> 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/fr/dev-reference/interacting-with-runbooks.md). # Interaction avec les runbooks ## Aperçu RealmJoin vous permet d'utiliser les Runbooks Azure Automation pour automatiser les opérations quotidiennes dans votre environnement. Voir [Runbooks](/fr/automatisation/runbooks.md) pour plus d’informations. L'API de RealmJoin vous permet de démarrer des runbooks depuis votre application, et de vérifier l'exécution réussie des exécutions déclenchées précédemment. 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 tâches de runbook. Il est supposé que vous avez déjà [connecté un compte Azure Automation](/fr/automatisation/connecting-azure-automation.md) au portail RealmJoin. Assurez-vous également de [authentifier ](/fr/dev-reference/realmjoin-api/authentication.md)chaque requête vers 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, une tâche est créée pour ce runbook et mise en file d'attente pour exécution. Ainsi, en général, un runbook ne démarre pas immédiatement. De plus, plusieurs tâches pour le même runbook peuvent exister en même temps dans différents états d'exécution. Chaque tâche possède un ensemble de paramètres (entrées) transmis au script du runbook. Il peut s'agir, par ex., 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 tâche 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 dans le but de faciliter la compréhension. ## Démarrer une tâche 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 retournera/terminera que lorsque le runbook est réellement terminé ou en échec. Ce point de terminaison renvoie directement l'état de réussite et la sortie de la tâche de runbook associée. `start` prendra les mêmes paramètres que `run` mais fonctionne de manière asynchrone. Il retournera dès qu'une tâche de runbook sera mise en file d'attente. Il renverra le `jobID` pour permettre un suivi facile de la nouvelle tâche. ### 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 `préfixe rjgit-`comme préfixe * Soit `org_`, `device_`, `group_`, `user_` comme portée (exactement l'une d'entre elles) * 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](/fr/automatisation/runbooks/naming-conventions.md) pour plus de détails. ### Exemple Supposons 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 = "someone@contoso.com"` * `$Revoke = $true` Nous utiliserons le `run` point de terminaison pour savoir immédiatement si la tâche a réussi. Construisons le **demander**: 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 de la tâche. Veuillez vous assurer d'adapter le délai d'attente de votre client HTTP en conséquence. Sinon, essayez d'utiliser le `start` point de terminaison, qui retournera immédiatement. La réponse contiendra le `jobID`, le `statut` (`Failed` ou `Completed`) et 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 un 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 de l'utilisateur 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 (`streamTypes`): `Output`, `Verbose`, `Error`. Cela permet de filtrer les erreurs ou de réduire la sortie aux seules informations pertinentes en n'affichant que `Output`. Vous pouvez obtenir ces flux une fois qu'un runbook est terminé en utilisant le `/runbook/jobs/{jobID}/output/streams` point de terminaison. (voir ci-dessous) ## Interrogation du statut et de la sortie d'une tâche Si une tâche a déjà été créée, vous pouvez utiliser l'API RealmJoin pour interroger son état et sa sortie. ### Interrogation du statut d'une tâche Utilisez `/runbook/jobs/{jobID}/status` pour interroger le statut actuel. Voir [Authentification ](/fr/dev-reference/realmjoin-api/authentication.md)sur la manière de créer un en-tête d'autorisation, ce qui suit n'est qu'un exemple. Supposons le `jobID` être `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 ``` Les autres états possibles comprennent `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 de la tâche 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 `Error` flux. Voir [lecture des flux](#reading-specific-streams) pour lire d'autres flux. [Exceptions](#reading-exceptions) sont traités séparément. Voir [Authentification ](/fr/dev-reference/realmjoin-api/authentication.md)sur la manière de créer un en-tête d'autorisation, ce qui suit n'est qu'un exemple. Supposons le `jobID` être `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 `Output`, `Verbose` et `Error` flux. [Exceptions](#reading-exceptions) sont traités séparément. Voir [Authentification ](/fr/dev-reference/realmjoin-api/authentication.md)sur la manière de créer un en-tête d'autorisation, ce qui suit n'est qu'un exemple. Supposons le `jobID` être `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 un 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 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 bloquant", "streamType": "Error", "streamText": null, "value": null } ] ``` Voir ci-dessous pour lire les messages d'erreur bloquants et [exceptions](#reading-exceptions) Pour recevoir un seul flux, par exemple Verbose, vous pouvez ajouter un filtre à la requête en ajoutant `?streamTypes=Verbose`. Vous pouvez également filtrer pour `Output` 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 un 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 simple en texte brut du message d'exception d'un runbook (si présent). Cela n'inclura pas les `Output`, `Verbose` et `Error` flux. Voir [lecture des flux](#reading-specific-streams) pour lire d'autres flux. Les exceptions sont écrites lorsqu'une erreur bloquante se produit 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 les détails techniques, comme la ligne de code où le script s'est arrêté. Dans notre exemple, une erreur bloquante a été causée par `throw "Exception"`. Voir [Authentification ](/fr/dev-reference/realmjoin-api/authentication.md)sur la manière de créer un en-tête d'autorisation, ce qui suit n'est qu'un exemple. Supposons le `jobID` être `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) ``` --- # 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/fr/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.