Étape PowerShell

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 9 minutes de lecture

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

    PowerShell est basé sur Windows .NET Framework et est conçu pour contrôler et automatiser l’administration des ordinateurs et des 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, consultez Calendriers juridiques - Vue d’ensemble du concentrateur d’intégration.

    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 l’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 Présentation des informations d’identification, des connexions et des 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 flow_designer ou admin 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 (2 sens cryptés) sur le panneau de données.
    Remarque :
    Ce champ est disponible lorsque l’option Utiliser l’alias de connexion est sélectionnée dans la liste Connexion.
    Alias d’informations d’identification Alias d’informations d’identification utilisé par le système pour exécuter l’étape d’action. Les utilisateurs disposant du rôle flow_designer ou admin 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 (2 sens cryptés) 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 n’est visible que lorsque la connexion est définie sur Définir l’inline de la connexion.
    Port Spécifiez le port de communication sur lequel l’hôte cible écoute les connexions. Par exemple, 5985. Laissez ce champ vide pour utiliser le port par défaut.
    Remarque :
    Ce champ n’est visible que lorsque la connexion est définie sur Définir l’inline de la connexion.
    Sélection de MID Option permettant de sélectionner le serveur MID ou la grappe MID spécifique.
    • Sélectionner automatiquement un serveur MID : sélectionne automatiquement le 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 MID Server 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 faire référence au nom de l’application MID, et non à l’enregistrement de l’application MID. Ce champ est disponible lorsque Définir l’inline de la connexion est sélectionné dans la liste Connexion et que Serveur MID auto-sélectionné est sélectionné dans la liste Sélection MID.
    Aptitudes Capacités que le doit prendre 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 Définir l’inline de la connexion est sélectionné dans la liste Connexion et que Serveur MID auto-sélectionné est sélectionné 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 Définir l’inline de la connexion est sélectionné dans la liste Connexion et que Serveur MID spécifique est sélectionné dans la liste de sélection MID.
    Grappe MID Pilule de données pour la grappe MID que vous souhaitez utiliser. Ce champ est disponible lorsque Définir l’inline de la connexion est sélectionné dans la liste Connexion et que Grappe MID spécifique est sélectionnée dans la liste 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) : établir une connexion et exécuter le script sur un serveur distant.
    • Accès distant implicite (avancé) : exécuter un script lors Serveur MID de l’importation des modules nécessaires à partir d’un serveur distant. Si sélectionné, définissez le préfixe du nom distant et les modules pour importer les champs. 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 MID, ou définissez des spécifications d’accès à distance dans le script. Il s’agit de la valeur par défaut.
    Remarque :
    Pour appeler 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 aux accès à distance explicites et implicites. Pour plus d’informations sur le bloc param, consultez la documentation de Microsoft sur les paramètres Windows Powershell à l’adresse https://technet.microsoft.com/.
    Préfixe du nom distant Chemin d’accès du fichier, à l’exclusion des noms de fichiers, vers les modules à charger à partir du serveur distant.
    Remarque :
    Ce champ n’est visible que lorsque le type d’accès distant est Accès distant implicite (avancé).
    Modules à importer Liste séparée par des virgules des modules à importer à partir du serveur distant au niveau du chemin d’accès de 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 des 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 de 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 qui sépare la logique de scripting de l’action, ce qui vous permet de mettre à jour le script sans avoir à modifier et à redéployer l’action.
    Serveur MID Script Script PowerShell prédéfini à partir de la Serveur MID table Fichiers de script [ecc_agent_script_file].
    Remarque :
    Ce champ n’est disponible que si le type de script est Fichier de script de Serveur MID.
    Chemin d’accès au script Chemin d’accès en lecture seule au script sélectionné Serveur MID .
    Remarque :
    Ce champ n’est visible que lorsque le type de script est Fichier de script de 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 au traitement interne et ne doivent pas être utilisés comme variables d’entrée. Voir Variables réservées dans les variables de script PowerShell.
    • Type : type de variable PowerShell. Sélectionnez texte brut, chiffré ou booléen. Si encrypted est sélectionné, la valeur apparaît en texte brut dans ce champ et n’est chiffré que lorsqu’elle passe à la file d’attente ECC.
    • Valeur : valeur à mapper à la variable. Saisissez manuellement une valeur ou faites glisser une pastille de données dans le champ.
    Commande 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 de l’étape pour une condition d’erreur d’action personnalisée, reportez-vous à la section Évaluation de l’erreur d’action.

    Variables de script PowerShell

    Pour accéder aux variables d’entrée à partir 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écuter sur un serveur MID ou si votre script établit une session distante, certaines variables réservées sont disponibles en plus des variables d’entrée.

    Syntaxe des variables d’entrée

    Par défaut, préfixe les noms de variables avec 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, ajoutez $env :SNC_ au nom de la variable comme un préfixe. 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, reportez-vous à la section 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 peuvent être utilisées 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 contenant les informations d’identification définies dans l’enregistrement de connexion. Utilisez cette variable avec n’importe quelle applet de commande PowerShell qui prend 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 vrai, ajoute les informations de journalisation à un script PowerShell.

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

    • script
    • useCred
    • isMid
    • isDiscovery (en anglais seulement)
    • debug
    • utilisateur
    • mot de passe
    • executingScriptDirectory
    • midScriptDirectory
    • hRésultat