Configurer les paramètres d’entrée de runbook dans Automation

Article
08/18/2023

Les paramètres d’entrée de runbook augmentent la flexibilité d’un runbook en vous permettant de lui transmettre des données lors de son démarrage. Ces paramètres permettent de cibler les actions des runbooks pour des scénarios et environnements spécifiques. Cet article décrit la configuration et l’utilisation des paramètres d’entrée dans vos runbooks.

Vous pouvez configurer des paramètres d’entrée pour des runbooks PowerShell, PowerShell Workflow, graphiques et Python. Un runbook peut avoir plusieurs paramètres avec différents types de données, ou aucun paramètre. Les paramètres d’entrée peuvent être obligatoires ou facultatifs, et vous pouvez utiliser des valeurs par défaut pour les paramètres facultatifs.

Vous affectez des valeurs aux paramètres d’entrée d’un runbook quand vous le démarrez. Vous pouvez démarrer un runbook à partir du portail Azure, d’un service web ou de PowerShell. Vous pouvez également démarrer un Runbook en tant que Runbook enfant appelé en ligne dans un autre Runbook.

Types d'entrée

Azure Automation prend en charge différentes valeurs de paramètres d’entrée sur les différents types de runbooks. Les types d’entrée pris en charge pour chaque type de runbook sont répertoriés dans le tableau suivant.

Type de runbook	Entrées de paramètre prises en charge
PowerShell	- Chaîne - Security.SecureString - INT32 - Booléen - DateHeure - Tableau - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell Workflow	- Chaîne - Security.SecureString - INT32 - Booléen - DateHeure - Tableau - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell graphique	- Chaîne - INT32 - INT64 - Booléen - Décimal - DateHeure - Objet
Python	- Chaîne

Configurer des paramètres d'entrée dans des Runbooks PowerShell

Les runbooks PowerShell et PowerShell Workflow dans Azure Automation prennent en charge les paramètres d’entrée définis par le biais des propriétés suivantes.

Propriété	Description
Type	Obligatoire. Le type de données est attendu pour la valeur du paramètre. Tout type .NET est valide.
Nom	Obligatoire. Nom du paramètre. Ce nom doit être unique au sein du runbook, doit commencer par une lettre et ne peut contenir que des lettres, des chiffres ou des caractères de soulignement.
Obligatoire	facultatif. La valeur booléenne spécifie si le paramètre requiert une valeur. Si vous définissez ce paramètre sur True, une valeur doit être fournie au démarrage du runbook. Si vous le définissez sur False, la valeur est facultative. Si vous ne spécifiez pas de valeur pour la propriété `Mandatory`, PowerShell considère que le paramètre d’entrée est facultatif par défaut.
Valeur par défaut	facultatif. Valeur utilisée pour le paramètre si aucune valeur d’entrée n’est passée au démarrage du runbook. Le runbook peut définir une valeur par défaut pour n’importe quel paramètre.

Windows PowerShell prend en charge d’autres attributs de paramètres d’entrée que ceux listés ci-dessus, comme la validation, les alias et les jeux de paramètres. Toutefois, Azure Automation ne prend actuellement en charge que les propriétés de paramètres d’entrée listées ci-dessus.

À titre d’exemple, examinons une définition de paramètre dans un runbook PowerShell Workflow. Cette définition se présente sous la forme générale suivante, où plusieurs paramètres sont séparés par des virgules.

Param
(
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,

  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
)

À présent, configurons les paramètres d’entrée pour un runbook PowerShell Workflow qui génère des détails sur des machines virtuelles, soit une machine virtuelle unique, soit toutes les machines virtuelles au sein d’un groupe de ressources. Ce runbook comporte deux paramètres, comme le montre la capture d’écran suivante : le nom de la machine virtuelle (VMName) et le nom du groupe de ressources (resourceGroupName).

Automation PowerShell Workflow

Dans cette définition de paramètre, les paramètres d’entrée sont des paramètres simples de type chaîne.

Notez que les runbooks PowerShell et PowerShell Workflow prennent en charge tous les types, simples et complexes, comme Object ou PSCredential pour les paramètres d’entrée. Si votre runbook comporte un paramètre d’entrée objet, vous devez utiliser une table de hachage PowerShell contenant des paires nom-valeur pour transmettre une valeur. Par exemple, vous avez le paramètre suivant dans un runbook.

[Parameter (Mandatory = $true)]
[object] $FullName

Dans ce cas, vous pouvez transmettre la valeur suivante au paramètre.

@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}

Pour les runbooks PowerShell 7.1, fournissez des paramètres d’entrée de tableau au format ci-dessous :

Nom	Valeur
TESTPARAMETER	does,this,even,work

Remarque

Quand vous ne transmettez pas de valeur à un paramètre de type String facultatif dont la valeur par défaut est null, la valeur du paramètre est une chaîne vide et non la valeur null.

Configurer des paramètres d’entrée dans des Runbooks graphiques

Pour illustrer la configuration des paramètres d’entrée d’un runbook graphique, créons un runbook qui génère des détails sur des machines virtuelles, soit une machine virtuelle unique, soit toutes les machines virtuelles au sein d’un groupe de ressources. Pour plus d’informations, consultez Mon premier runbook graphique.

Un runbook graphique utilise ces activités principales :

Authentifiez-vous auprès d’Azure à l’aide de l’identité managée configurée pour le compte Automation.
Définition d’une applet de commande Get-AzVM pour obtenir les propriétés d’une machine virtuelle.
Utilisation de l’activité Write-Output pour générer les noms des machines virtuelles.

L’activité Get-AzVM définit deux entrées : le nom de la machine virtuelle et le nom du groupe de ressources. Étant donné que ces noms peuvent être différents à chaque démarrage du runbook, vous devez ajouter des paramètres d’entrée à votre runbook pour accepter ces entrées. Reportez-vous à Création de graphiques dans Azure Automation.

Effectuez ces étapes pour configurer les paramètres d’entrée.

Sélectionnez le runbook graphique dans la page Runbooks, puis cliquez sur Modifier.
Dans l’éditeur graphique, cliquez sur le bouton Entrée et sortie, puis le bouton Ajouter une entrée pour ouvrir le volet Paramètre d’entrée de runbook.
Le contrôle Entrée et sortie présente la liste des paramètres d’entrée définis pour le runbook. Vous pouvez alors ajouter un nouveau paramètre d’entrée ou modifier la configuration d’un paramètre d’entrée existant. Pour ajouter un nouveau paramètre pour le runbook, cliquez sur Ajouter une entrée pour ouvrir le panneau Paramètre d’entrée de runbook, où vous pouvez configurer des paramètres à partir des propriétés définies dans Création de graphiques dans Azure Automation.
Créez deux paramètres avec les propriétés suivantes qui seront utilisées par l’activité Get-AzVM, puis cliquez sur OK.
- Paramètre 1 :
  - Nom -- VMName
  - Type -- Chaîne
  - Obligatoire -- Non
- Paramètre 2 :
  - Nom -- resourceGroupName
  - Type -- Chaîne
  - Obligatoire -- Non
  - Valeur par défaut -- Personnalisé
  - Valeur par défaut personnalisée -- Nom du groupe de ressources qui contient les machines virtuelles
Affichez les paramètres dans le contrôle Entrée et sortie.
Recliquez sur OK, puis sur Enregistrer.
Cliquez sur Publier pour publier votre runbook.

Configurer des paramètres d’entrée dans des Runbooks Python

Contrairement aux runbooks PowerShell, PowerShell Workflow et graphiques, les runbooks Python ne prennent pas de paramètres nommés. L’éditeur de runbook analyse tous les paramètres d’entrée sous la forme d’un tableau de valeurs d’arguments. Vous pouvez accéder au tableau en important le module sys dans votre script Python, puis en utilisant le tableau sys.argv. Il est important de noter que le premier élément du tableau, sys.argv[0], est le nom du script. Par conséquent, le premier paramètre d’entrée réel est sys.argv[1].

Pour obtenir un exemple montrant comment utiliser les paramètres d’entrée dans un runbook Python, consultez My first Python runbook in Azure Automation (Mon premier runbook Python dans Azure Automation).

Remarque

Les arguments avec des espaces ne sont actuellement pas pris en charge. Pour contourner ce problème, vous pouvez utiliser \\t en plus de \\n.

Affecter des valeurs aux paramètres d’entrée dans des Runbooks

Cette section décrit plusieurs façons de passer des valeurs aux paramètres d’entrée dans des runbooks. Vous pouvez affecter des valeurs de paramètre lors des opérations suivantes :

Démarrer un runbook
Tester un runbook
Lier une planification pour le runbook
Créer un webhook pour le runbook

Démarrer un Runbook et affecter des paramètres

Un runbook peut être démarré de plusieurs façons : par le biais du portail Azure, avec un webhook, avec des applets de commande PowerShell, avec l’API REST ou avec le SDK.

Démarrer un runbook publié à l’aide du portail Azure et affecter des paramètres

Au démarrage du runbook dans le portail Azure, le panneau Démarrer le runbook s’ouvre. Vous pouvez y entrer les valeurs des paramètres que avez créés.

Start using the portal

Dans l’étiquette située sous la zone d’entrée, vous pouvez voir les propriétés qui ont été définies pour les attributs de paramètre, par exemple un caractère obligatoire ou facultatif, un type, une valeur par défaut. La bulle d’aide située en regard du nom de paramètre définit aussi les informations clés dont vous avez besoin pour prendre des décisions sur les valeurs d’entrée du paramètre.

Remarque

Les paramètres de chaîne prennent en charge des valeurs vides de type chaîne. Le fait d’entrer [EmptyString] dans la zone de paramètre d’entrée a pour effet de transmettre une chaîne vide au paramètre. De plus, les paramètres de chaîne ne prennent pas en charge la valeur Null. Si vous ne transmettez pas de valeur à un paramètre de chaîne, PowerShell interprète sa valeur comme étant Null.

Démarrer un runbook publié à l’aide d’applets de commande PowerShell et affecter des paramètres

Applets de commande d’Azure Resource Manager : vous pouvez démarrer un runbook Automation créé dans un groupe de ressources à l’aide de l’applet de commande Start-AzAutomationRunbook.

   $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}

   Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params

Cmdlets du modèle de déploiement Azure Classic : vous pouvez démarrer un runbook Automation créé dans un groupe de ressources par défaut à l’aide de Start-AzureAutomationRunbook.

   $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}

   Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params

Remarque

Quand vous démarrez un runbook à l’aide d’applets de commande PowerShell, un paramètre par défaut, MicrosoftApplicationManagementStartedBy, est créé avec la valeur PowerShell. Vous pouvez voir ce paramètre dans le volet Détails du travail.

Démarrer un runbook à l’aide d’un SDK et affecter des paramètres

Méthode d’Azure Resource Manager : vous pouvez démarrer un runbook à l’aide du Kit de développement logiciel (SDK) d’un langage de programmation. Voici un extrait de code C# permettant de démarrer un Runbook dans votre compte Automation. Vous pouvez voir le code complet dans notre dépôt GitHub.

public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}

Méthode du modèle de déploiement Azure Classic : vous pouvez démarrer un runbook à l’aide du Kit de développement logiciel (SDK) d’un langage de programmation. Voici un extrait de code C# permettant de démarrer un Runbook dans votre compte Automation. Vous pouvez voir le code complet dans notre dépôt GitHub.

public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}

Pour lancer cette méthode, créez un dictionnaire pour stocker les paramètres de runbook VMName et resourceGroupName ainsi que leurs valeurs. Démarrez ensuite le Runbook. Voici l’extrait de code C# permettant d’appeler la méthode définie ci-dessus.

IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();

// Add parameters to the dictionary.
RunbookParameters.Add("VMName", "WSVMClassic");
RunbookParameters.Add("resourceGroupName", "WSSC1");

//Call the StartRunbook method with parameters
StartRunbook("Get-AzureVMGraphical", RunbookParameters);

Démarrer un runbook à l’aide de l’API REST et affecter des paramètres

Vous pouvez créer et démarrer une tâche de runbook avec l’API REST d’Azure Automation en utilisant la méthode PUT avec l’URI de demande suivant : https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

Dans l’URI de demande, remplacez les paramètres suivants :

subscriptionId: ID de votre abonnement Azure.
resourceGroupName : nom du groupe de ressources du compte Automation.
automationAccountName : nom de votre compte Automation hébergé dans le service cloud spécifié.
jobName : GUID du travail. Vous pouvez créer des GUID dans PowerShell à l’aide de [GUID]::NewGuid().ToString()*.

Pour transmettre des paramètres au travail du runbook, utilisez le corps de la demande. Ce dernier prend les informations suivantes, fournies au format JSON :

Runbook Name : obligatoire. Nom du Runbook pour le démarrage de la tâche.
Runbook Parameters : facultatif. Dictionnaire de la liste de paramètres au format (nom, valeur) où nom doit être un nom de type String, et valeur peut être toute valeur JSON valide.

Si vous voulez démarrer le runbook Get-AzureVMTextual créé précédemment avec VMName et resourceGroupName comme paramètres, utilisez le format JSON suivant pour le corps de la demande.

    {
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
        }
    }

Un code d’état HTTP 201 est retourné si la tâche est correctement créée. Pour plus d’informations sur les en-têtes et le corps de la réponse, consultez Créer un travail de runbook à l’aide de l’API REST.

Tester un Runbook et affecter des paramètres

Quand vous testez la version brouillon de votre runbook à l’aide de l’option de test, la page Test s’ouvre. Utilisez cette page pour configurer des valeurs pour les paramètres que vous avez créés.

Test and assign parameters

Lier une planification à un Runbook et affecter des paramètres

Vous pouvez lier une planification à votre Runbook afin de démarrer celui-ci à un moment spécifique. Lors de la création de la planification, vous affectez des paramètres d’entrée, que le runbook utilise quand la planification le démarre. Vous ne pouvez pas enregistrer la planification tant que toutes les valeurs de paramètres obligatoires n’ont pas été fournies.

Schedule and assign parameters

Créer un WebHook pour un Runbook et affecter des paramètres

Vous pouvez créer un WebHook pour votre Runbook, puis configurer les paramètres d’entrée de celui-ci. Vous ne pouvez pas enregistrer le webhook tant que toutes les valeurs de paramètres obligatoires n’ont pas été fournies.

Create webhook and assign parameters

Quand vous exécutez un runbook à l’aide d’un webhook, le paramètre d’entrée prédéfini [WebhookData](automation-webhooks.md) est envoyé avec les paramètres d’entrée que vous définissez.

WebhookData parameter

Passer un objet JSON à un runbook

Il peut être utile stocker les données à passer dans un runbook dans un fichier JSON. Par exemple, vous pouvez créer un fichier JSON qui contient tous les paramètres que vous voulez passer à un runbook. Pour ce faire, vous devez convertir le code JSON en chaîne, puis convertir la chaîne en objet PowerShell avant de la passer au runbook.

Cette section utilise un exemple dans lequel un script PowerShell appelle Start-AzAutomationRunbook pour démarrer un runbook PowerShell, en passant le contenu du fichier JSON au runbook. Le runbook PowerShell démarre une machine virtuelle Azure, en récupérant les paramètres de la machine virtuelle à partir de l’objet JSON.

Créer le fichier JSON

Tapez le code suivant dans un fichier texte et enregistrez-le sous le nom test-json quelque part sur votre ordinateur local.

{
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
}

Créer le runbook

Créez un runbook PowerShell nommé Test-Json dans Azure Automation.

Pour accepter les données JSON, le runbook doit prendre un objet comme paramètre d’entrée. Le runbook peut alors utiliser les propriétés définies dans le fichier JSON.

Param(
     [parameter(Mandatory=$true)]
     [object]$json
)

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

# Convert object to actual JSON
$json = $json | ConvertFrom-Json

# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext

Si vous souhaitez que le runbook s’exécute avec l’identité managée affectée par le système, laissez le code tel quel. Si vous préférez utiliser une identité managée affectée par l’utilisateur, procédez comme suit :

À la ligne 10, supprimez $AzureContext = (Connect-AzAccount -Identity).context,
Remplacez-la par $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context et
Entrez l'ID client.

Enregistrez et publiez ce runbook dans votre compte Automation.

Appeler le runbook à partir de PowerShell

Vous pouvez maintenant appeler le runbook à partir de votre ordinateur local à l’aide d’Azure PowerShell.

Connectez-vous à Azure comme indiqué. Par la suite, vous êtes invité à entrer vos informations d’identification Azure.
```
Connect-AzAccount
```
Remarque

Pour les runbooks PowerShell, Add-AzAccount et Add-AzureRMAccount sont des alias de Connect-AzAccount. Notez que ces alias ne sont pas disponibles pour les runbooks graphiques. Un runbook graphique peut uniquement utiliser Connect-AzAccount.
Obtenez le contenu du fichier JSON enregistré et les convertissez-le en chaîne. JsonPath indique le chemin où vous avez enregistré le fichier JSON.
```
$json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
```
Convertissez le contenu de la chaîne de $json en objet PowerShell.
```
$JsonParams = @{"json"=$json}
```
Créez une table de hachage pour les paramètres de Start-AzAutomationRunbook.
```
$RBParams = @{
     AutomationAccountName = 'AATest'
     ResourceGroupName = 'RGTest'
     Name = 'Test-Json'
     Parameters = $JsonParams
}
```
Notez que vous définissez la valeur Parameters sur l'objet PowerShell contenant les valeurs du fichier JSON.

Démarrer le runbook.

$job = Start-AzAutomationRunbook @RBParams

Étapes suivantes

Pour préparer un runbook textuel, consultez Modifier le runbooks textuel dans Azure Automation.
Pour préparer un runbook graphique, consultez Création de graphiques dans Azure Automation.

Partager via

Configurer les paramètres d’entrée de runbook dans Automation

Types d'entrée

Configurer des paramètres d'entrée dans des Runbooks PowerShell

Configurer des paramètres d’entrée dans des Runbooks graphiques

Configurer des paramètres d’entrée dans des Runbooks Python

Affecter des valeurs aux paramètres d’entrée dans des Runbooks

Démarrer un Runbook et affecter des paramètres

Démarrer un runbook publié à l’aide du portail Azure et affecter des paramètres

Démarrer un runbook publié à l’aide d’applets de commande PowerShell et affecter des paramètres

Démarrer un runbook à l’aide d’un SDK et affecter des paramètres

Démarrer un runbook à l’aide de l’API REST et affecter des paramètres

Tester un Runbook et affecter des paramètres

Lier une planification à un Runbook et affecter des paramètres

Créer un WebHook pour un Runbook et affecter des paramètres

Passer un objet JSON à un runbook

Créer le fichier JSON

Créer le runbook

Appeler le runbook à partir de PowerShell

Étapes suivantes

Ressources supplémentaires