Étape PowerShell

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 9 minutes de lecture

    • Exécutez des scripts PowerShell sur des ordinateurs distants à partir de votre instance ServiceNow via un Serveur MID.

    PowerShell repose sur Windows .NET Framework et est conçu pour contrôler et automatiser l’administration des machines et applications Windows. ServiceNow prend en charge PowerShell 3.0 à 5.1. PowerShell 3.0 ne prend pas en charge Windows 2003 Server.

    Remarque :
    Cette étape nécessite un abonnement Hub d'intégration. Pour plus d’informations, voir Calendriers juridiques : Hub d'intégration présentation.

    Rôles et disponibilité

    Disponible en tant qu’étape d’action Studio de workflow . Les utilisateurs disposant du rôle action_designer peuvent créer une action personnalisée avec une ou plusieurs étapes d’action.

    Champs

    Champ Description
    Connexion Type de connexion à utiliser.
    • Définir l’inline de la connexion : Définissez les informations de connexion dans l'étape d'action.
    • Utiliser des alias de connexion : Définissez les informations de connexion à l'aide de la table Alias de connexion. L'utilisation d'un alias élimine la nécessité de configurer plusieurs informations d'identification et profils d'informations de connexion lors de l'utilisation d'une action dans plusieurs environnements. De même, si les informations de connexion changent, vous n'avez pas besoin de mettre à jour votre action personnalisée.

    Pour en savoir plus sur les connexions et les informations d’identification, consultez Introduction aux informations d’identification, connexions et alias.
    Alias de connexion Enregistrement d’alias de connexion et d’informations d’identification que le système utilise pour exécuter l’étape d’action. Les utilisateurs disposant du rôle d’administrateur ou de flow_designer peuvent créer ou sélectionner un enregistrement de connexion associé. L'utilisation d'un alias élimine la nécessité de configurer plusieurs informations d'identification et profils d'informations de connexion lors de l'utilisation d'une action dans plusieurs environnements. De même, si les informations de connexion changent, vous n’avez pas besoin de mettre à jour votre action personnalisée. Pour en savoir plus sur les connexions et les informations d’identification, consultez Informations d’identification, connexions et alias. La valeur d’informations d’identification s’affiche sous la forme d’une pastille de données de mot de passe (chiffré dans 2 sens) sur le panneau de données.
    Remarque :
    Ce champ est disponible lorsque l’option Utiliser alias de connexion est sélectionnée dans la liste Connexion.
    Alias d’informations d’identification Alias d’informations d’identification que le système utilise pour exécuter l’étape d’action. Les utilisateurs disposant du rôle d’administrateur ou de flow_designer peuvent créer ou sélectionner un enregistrement de connexion associé. L’utilisation d’un alias élimine la nécessité de configurer plusieurs informations d’identification lors de l’utilisation d’une action dans plusieurs environnements. De même, si les informations d’identification changent, vous n’avez pas besoin de mettre à jour votre action personnalisée. Pour en savoir plus sur les connexions et les informations d’identification, consultez Informations d’identification, connexions et alias. La valeur d’informations d’identification s’affiche sous la forme d’une pastille de données de mot de passe (chiffré dans 2 sens) sur le panneau de données.
    Remarque :
    Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion.
    Hôte Spécifiez le nom de domaine complet de l’hôte cible sur lequel le système exécute l’étape d’action. Par exemple, host.domain.com.
    Remarque :
    Ce champ est uniquement visible lorsque la connexion est définie sur Définir la connexion en ligne.
    Port Spécifiez le port de communication sur lequel l’hôte cible écoute les connexions. Par exemple, 5985. Laissez vide pour utiliser le port par défaut.
    Remarque :
    Ce champ est uniquement visible lorsque la connexion est définie sur Définir la connexion en ligne.
    Sélection de MID Option permettant de sélectionner le serveur MID ou la grappe MID spécifique.
    • Sélectionner automatiquement Serveur MID : sélectionne automatiquement Serveur MID.
    • Serveur MID spécifique : utilise le serveur MID que vous sélectionnez.
    • Grappe MID spécifique : utilise la grappe MID que vous sélectionnez.
    Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion.
    Application MID Spécifiez l’application que le Serveur MID doit prendre en charge pour être éligible à la sélection. Le système exécute l’étape d’action à partir d’un Serveur MID qui prend en charge l’application sélectionnée. Si vous utilisez une pastille de données pour ce champ, la pastille doit référencer le nom de l’application MID et non l’enregistrement de l’application MID. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion et que Sélectionner automatiquement Serveur MID est sélectionnée dans la liste Sélection MID.
    Options Les capacités doivent être prises en charge pour être éligible à la Serveur MID sélection. Le système exécute l’étape d’action à partir d’un Serveur MID qui prend en charge les options sélectionnées. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste Connexion et que Sélectionner automatiquement Serveur MID est sélectionnée dans la liste Sélection MID.
    Serveur MID Pastille de données contenant une référence sys_id à un Serveur MID enregistrement [ecc_agent_list]. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste de connexion et qu’un Serveur MID spécifique est sélectionné dans la liste de sélection MID.
    Grappe MID Pastille de données pour la grappe MID que vous souhaitez utiliser. Ce champ est disponible lorsque l’option Définir l’inline de la connexion est sélectionnée dans la liste de connexion et que la grappe MID spécifique est sélectionnée dans la liste de sélection MID.
    Type d'accès à distance Emplacement où le script PowerShell s’exécute, tel que le MID Server ou un serveur distant.
    • Accès distant explicite (le plus courant) : établissez une connexion et exécutez le script sur un serveur distant.
    • Accès distant implicite (avancé) : exécuter un script pendant l’importation des modules nécessaires à partir d’un Serveur MID serveur distant. Si cette option est sélectionnée, définissez le préfixe du nom distant et les champs Modules à importer . Pour des performances optimales, importez uniquement les modules nécessaires à l’étape. Si ce champ est vide, tous les modules disponibles sont importés à partir du serveur.
    • Exécuter sur un serveur MID ou demander à votre script d’établir une session à distance : exécutez un script directement sur un Serveur MIDou définissez des spécifications d’accès à distance dans le script. Il s’agit de la valeur par défaut.
    Remarque :
    Pour invoquer une fonction dans une commande de script PowerShell ou un fichier de script PowerShell, la commande doit définir le bloc de paramètres de fonction si la fonction a des paramètres d’entrée. Cette exigence s’applique à l’accès à distance explicite et implicite. Pour plus d’informations sur le bloc de paramètres, consultez la documentation de Microsoft sur les paramètres Windows Powershell à l’adresse https://technet.microsoft.com/.
    Préfixe du nom distant Le chemin d’accès du fichier, à l’exclusion des noms de fichiers, aux modules à charger à partir du serveur distant.
    Remarque :
    Ce champ n’est visible que lorsque le type d’accès à distance est Accès distant implicite (avancé).
    Modules à importer Liste séparée par des virgules des modules à importer à partir du serveur distant sur le chemin d’accès au fichier défini.
    Remarque :
    Ce champ n’est visible que lorsque le type d’accès à distance est Accès distant explicite (le plus courant) ou Accès distant implicite (avancé).
    Tester l’étape PowerShell Bouton permettant de tester les informations d’identification configurées pour l’étape PowerShell. Pour plus d’informations, consultez Tester les informations d’identification pour l’étape PowerShell.
    Type de script Type de script à exécuter sur l’hôte PowerShell.
    • Script aligné : saisissez le script à exécuter dans le champ Commande de l’étape.
    • Fichier de script Serveur MID : Sélectionnez le script PowerShell à exécuter à partir de la Serveur MID table Fichiers de script [ecc_agent_script_file]. Il s’agit de la valeur par défaut. Elle sépare la logique de script de l’action, ce qui vous permet de mettre à jour le script sans avoir à le modifier et à le redéployer.
    Serveur MID Script Script PowerShell prédéfini à partir de la Serveur MID table Fichiers de script [ecc_agent_script_file].
    Remarque :
    Ce champ est disponible uniquement si le type de script est Fichier de script Serveur MID.
    Chemin d’accès au script Chemin d’accès en lecture seule au script sélectionné Serveur MID .
    Remarque :
    Ce champ est uniquement visible lorsque le type de script est Fichier de script Serveur MID.
    Variables d’entrée Paires nom-valeur facultatives qui représentent les valeurs des variables de script PowerShell. Vous pouvez utiliser les entrées d’action et les données d’autres étapes dans le script PowerShell. Définissez les champs suivants pour chaque variable :
    • Nom : nom de la variable de script à laquelle transmettre une valeur. Le nom ne peut pas correspondre à une variable PowerShell réservée ou interdite. Certains noms de variables sont réservés pour le traitement interne et ne doivent pas être utilisés comme variables d’entrée. Consultez Variables réservées dans les variables de scripting PowerShell.
    • Type : type de variable PowerShell. Sélectionnez texte brut, chiffré ou booléen. Si chiffré est sélectionné, la valeur apparaît en texte brut dans ce champ et n’est chiffrée que lorsqu’elle est transmise à la file d’attente ECC.
    • Valeur : la valeur à mapper à la variable. Saisissez manuellement une valeur ou faites glisser une pastille de données dans le champ.
    Commande Le script PowerShell en ligne à exécuter sur l’hôte cible.
    Remarque :
    Ce champ n’est visible que lorsque le type de script est Script aligné.

    Évaluation de l’erreur d’action

    En cas d'échec de cette étape
    Type de données : Choice

    Option permettant de continuer à exécuter l’étape suivante ou d’accéder à l’évaluation des erreurs. Pour utiliser le code d’état ou le message d’une étape pour une condition d’erreur d’action personnalisée, reportez-vous à la section Évaluation de l’erreur d’action.

    Variables de scripting PowerShell

    Pour accéder aux variables d’entrée du champ Commande , vous devez les appeler à l’aide d’une syntaxe spéciale. La syntaxe que vous utilisez dépend de la valeur d’une propriété système. Si le type d’accès à distance est exécuté sur un serveur MID ou si votre script doit établir une session à distance, certaines variables réservées sont disponibles en plus des variables d’entrée.

    Syntaxe de la variable d’entrée

    Par défaut, préfixez les noms de variables par un caractère $ . Par exemple, si une variable d’entrée est nommée message, utilisez $message pour accéder à la variable dans le script.

    Si le mid.powershell.command.script.parameter_passing paramètre est défini sur false, préfixez le nom de la variable avec $env :SNC_. Par exemple, si une variable d’entrée est nommée message, utilisez $env :SNC_message pour accéder à la variable dans le script. Pour en savoir plus sur le mid.powershell.command.script.parameter_passing paramètre, consultez Paramètres du serveur MID.

    Variables réservées

    Lorsque le type d’accès à distance est exécuté sur un serveur MID ou que votre script établit une session distante, les variables suivantes sont disponibles pour une utilisation dans le script. Les variables réservées ne peuvent pas être utilisées en tant que noms de variables d’entrée personnalisées.

    Variable réservée Description
    $computer Adresse IP de l’hôte définie dans l’enregistrement d’alias de connexion.
    $cred Objet d’informations d’identification qui contient les informations d’identification définies dans l’enregistrement de connexion. Utilisez cette variable avec n’importe quelle applet de commande PowerShell prenant en charge le paramètre d’informations d’identification. Par exemple, New-PSSession -credential $cred.
    $log_info Si la mid.property.powershell.log_info propriété est définie sur true, ajoute des informations de journalisation à un script PowerShell.

    Les noms de variables suivants sont réservés pour le traitement interne et ne doivent pas être utilisés comme variables d’entrée.

    • script
    • useCred
    • isMid
    • isDiscovery
    • debug
    • utilisateur
    • mot de passe
    • exécuterScriptDirectory
    • midScriptDirectory
    • hresult