> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/fr/plateforme/variables.md). # Variables Créez des variables globales et secrètes dans PowerShell Universal, gérez les coffres de secrets et consultez les variables intégrées disponibles dans les scripts, les API et les applis. Les variables peuvent être utilisées dans les API, les scripts et les tableaux de bord. Lorsque vous utilisez les environnements par défaut, toutes les variables sont importées automatiquement. Cela est réalisé en spécifiant le paramètre `-Variable` de `New-PSUEnvironment` avec un caractère générique (\*). Si vous utilisez vos propres environnements, vous devrez configurer quelles variables vous souhaitez inclure. Vous pouvez référencer une variable comme n'importe quelle autre variable PowerShell. La variable contiendra la valeur que vous avez définie. Si vous utilisez un secret, elle contiendra la valeur du secret. {% hint style="info" %} Les variables sont stockées dans le fichier de configuration `variables.ps1`. {% endhint %} ## Créer une variable Pour créer une variable, naviguez vers la page Manage > Variables & Secrets > Variables. Cliquez sur Create Variable pour définir une nouvelle variable. Les variables seront ajoutées à vos scripts avant leur exécution. ## Créer une variable secrète Les variables secrètes sont stockées dans le coffre sélectionné. La valeur de ces variables n'est jamais stockée dans Universal. Pour définir une nouvelle variable secrète, cliquez sur Create Secret Variable dans la page des variables et sélectionnez l'onglet Secret. À partir de ce dialogue, vous pourrez définir des chaînes et des PSCredentials dans le coffre spécifié. ### Format des identifiants Dans certains environnements, il peut être nécessaire de spécifier le nom de domaine dans le champ du nom d'utilisateur. Vous pouvez le spécifier au format `domain\user` ou `user@domain`. Si vous ne le faites pas, vous recevrez des erreurs en tentant de démarrer des processus, comme des scripts ou des tableaux de bord, avec ce compte d'utilisateur. ### Comptes de service géré de groupe Lorsque vous utilisez des comptes de service géré de groupe (GMSA), vous devrez vous assurer que la machine et le compte ont accès au compte GSMA. Vous pouvez suivre [le guide de Microsoft ici](https://techcommunity.microsoft.com/blog/itopstalkblog/step-by-step-how-to-work-with-group-managed-service-accounts-gmsa/329864). Une fois la configuration terminée, créez un nouvel identifiant dans la gestion des secrets de PowerShell Universal et sélectionnez l'option Password Not Required. Saisissez le compte GSMA (p. ex. domain\user$). Tant que le compte hébergeant possède les privilèges appropriés, vous pourrez exécuter des tâches avec le compte GMSA. ### Validation des identifiants Sur Windows, vous pouvez valider les identifiants avant d'enregistrer leur valeur. Cliquez sur le bouton Validate dans le champ du mot de passe pour tenter de connecter l'utilisateur localement. Ce bouton n'apparaîtra pas sur les systèmes non Windows. ### Rôles {% hint style="warning" %} Appliquer des rôles à un secret empêchera le secret d'être accessible dans les tâches planifiées, car aucun rôle n'est appliqué dans le planificateur. {% endhint %} Les variables secrètes peuvent inclure un accès basé sur les rôles. Les rôles limitent qui peut utiliser le secret dans ses scripts et comme identifiants d'exécution. Lorsqu'un rôle est défini pour un secret, celui-ci ne sera pas accessible dans les ressources qui ne peuvent pas fournir ce rôle. Cela peut inclure ce qui suit : * Tâches planifiées * API ou applis non authentifiées * Terminaux ## Coffres ### Base de données Le coffre de base de données stocke les secrets dans la base de données de PowerShell Universal. Ces secrets sont chiffrés avec le chiffrement AES à l'aide d'une clé personnalisable. Vous pouvez personnaliser la clé en spécifiant Secrets \ Database \ EncryptionKey. #### appsettings.json Vous pouvez configurer ce paramètre dans appsettings.json. {% code collapsedlinecount="10" %} ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` {% endcode %} #### Variable d'environnement Vous pouvez configurer ce paramètre avec une variable d'environnement. {% code collapsedlinecount="10" %} ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` {% endcode %} ### BuiltInLocalVault {% hint style="warning" %} Si PowerShell Universal est exécuté en tant que compte de service géré de groupe, il ne peut pas utiliser le `BuiltInLocalVault`. {% endhint %} Les valeurs des secrets du `BuiltInLocalVault` sont stockées dans l'instance du Gestionnaire d'identifiants Windows du principal de sécurité qui exécute PSU. Par exemple, le compte de service de l'utilisateur exécutant le service Universal. Si vous changez d'utilisateur (comme en exécutant sous un compte de service), le compte n'aura pas accès aux secrets de l'utilisateur précédent et vous devrez ajouter ces secrets à nouveau. ### PSUSecretStore {% hint style="warning" %} Si PowerShell Universal est exécuté en tant que compte de service géré de groupe, il ne peut pas utiliser le `PSUSecretStore`. {% endhint %} Le coffre `PSUSecretStore` est intégré au module Microsoft `SecretStore` pour stocker les secrets dans un fichier multiplateforme. Ce fichier est lié au compte d'utilisateur actuel exécutant PowerShell Universal. Le mot de passe du coffre est stocké dans `appsettings.json`. ### Az.KeyVault {% hint style="info" %} Utilisez l'enregistrement de coffre Azure Key Vault pour configurer Azure Key Vault pour PowerShell Universal. {% endhint %} Par défaut, nous n'incluons pas l'extension Azure Key Vault directement dans PowerShell Universal. Un conteneur incluant les modules Az.Accounts et Az.KeyVault requis est disponible pour vous permettre d'utiliser KeyVault dès le départ. Il se trouve sur [Docker Hub](https://hub.docker.com/r/devolutions/powershell-universal). Vous trouverez ci-dessous comment le configurer. Cet exemple utilise une version de PowerShell Universal en application web hébergée sur Azure. Dans Azure, nous devrons configurer une identité gérée pour notre application web. Cette étape n'est pas nécessairement requise si vous exécutez à l'extérieur d'Azure. Vous pouvez activer l'identité gérée dans la page Identity de votre application web. Enfin, nous devrons enregistrer le key vault et nous connecter à Azure au démarrage de l'application web. Cela peut être réalisé en utilisant les modules Az.Account et Az.KeyVault. Après avoir déployé votre application web, vous devrez d'abord installer les modules Az.Account et Az.KeyVault. Vous pouvez le faire dans la page des modules. Ils seront installés dans le dépôt local de l'application web. Ensuite, créez un script dans PowerShell Universal pour vous connecter à Azure et enregistrer le coffre. Exécutez le script pour vérifier qu'il fonctionne correctement. {% code collapsedlinecount="10" %} ```powershell $sub = 'affdf0d4-eed5-48a6-889c-599d482xxxxx' Connect-AzAccount -Id -Scope CurrentUser -SubscriptionId $sub Register-SecretVault -ModuleName Az.KeyVault -Name AzureKeyVault -VaultParameters @{ AZKVaultName = 'psu-demo' SubscriptionId = $sub } -AllowClobber ``` {% endcode %} Maintenant, lorsque vous créerez des secrets, vous verrez AzureKeyVault disponible. Pour vous assurer que l'application est connectée à Azure et que le key vault est enregistré, exécutez le script dans `vaults.ps1`. Nous recommandons d'exécuter le script dans un processus PowerShell externe afin d'éviter les conflits d'assemblages avec les DLL de PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` {% endcode %} Ce script s'exécute avant que les variables soient enregistrées et que les coffres soient localisés. Vous pouvez créer ce fichier directement dans le répertoire Repository.universal. Il sera exécuté au démarrage du système avant que les autres scripts de configuration soient exécutés. ### vaults.ps1 Le fichier `vaults.ps1` contient les commandes d'enregistrement de coffres. Bien que l'exemple ci-dessus définisse un enregistrement de coffre de secrets Azure KeyVault, vous pouvez en fait inclure tout enregistrement de coffre dont vous avez besoin dans ce fichier. Vous pouvez modifier les coffres en cliquant sur Manage > Variables & Secrets > Vaults, puis en naviguant vers l'onglet vaults.ps1. ## Importer des variables secrètes Vous pouvez également importer des secrets préexistants comme variables dans Universal. Les valeurs des variables ne sont pas importées, mais elles seront recherchées lors de l'exécution. Cliquez sur le bouton Import Secret pour importer des secrets. ## Utiliser des variables Les variables peuvent être utilisées dans les API, les scripts et les tableaux de bord. Lorsque vous utilisez les environnements par défaut, toutes les variables sont importées automatiquement. Cela est réalisé en spécifiant le paramètre `-Variable` de `New-PSUEnvironment` avec un caractère générique (\*). Si vous utilisez vos propres environnements, vous devrez configurer [quelles variables vous souhaitez inclure](https://docs.powershelluniversal.com/config/environments#variables). Vous pouvez référencer une variable comme n'importe quelle autre variable PowerShell. La variable contiendra la valeur que vous avez définie. Si vous utilisez un secret, elle contiendra la valeur du secret. {% code collapsedlinecount="10" %} ``` $MyVariable ``` {% endcode %} Vous pouvez personnaliser quelles variables sont autorisées dans un environnement en personnalisant le paramètre `-Variable` de l'environnement. Consultez Environnements pour plus d'information. ## Portée des secrets Pour accéder aux secrets que vous avez ajoutés à PowerShell Universal, vous pouvez utiliser la portée `$Secret`. Par exemple, si vous avez défini un secret nommé `Credential`, vous pourriez accéder à ce secret n'importe où avec la portée des secrets. Vous ne pouvez pas définir de secrets en utilisant la portée des secrets. {% code collapsedlinecount="10" %} ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` {% endcode %} ### Accéder aux variables par nom Vous pouvez accéder aux variables par nom en utilisant le préfixe `$Secret:`. {% code collapsedlinecount="10" %} ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` {% endcode %} ### Accéder aux valeurs dynamiquement Vous pouvez accéder à la portée des secrets dynamiquement en utilisant `Get-Item`. La portée des secrets est implémentée comme un fournisseur. Cela est utile si vous n'avez pas de noms de variables statiques. {% code collapsedlinecount="10" %} ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` {% endcode %} ### ForEach-Object -Parallel Afin d'utiliser des secrets avec `ForEach-Object` et le paramètre `-Parallel`, vous devrez tirer parti du mot-clé `$using`. {% code collapsedlinecount="10" %} ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` {% endcode %} ## Configurer le mot de passe de `PSUSecretStore` Par défaut, le mot de passe du coffre `PSUSecretStore` est stocké dans `appsettings.json` sous Secrets \ SecretStore \ Password. ## Variables intégrées Les variables suivantes sont disponibles dans tous les environnements de PowerShell Universal. Cette référence énumère les variables de PowerShell Universal destinées à être utilisées dans votre code. `Get-Variable` retourne également les variables automatiques standards de PowerShell et les variables d'implémentation internes, de sorte que sa sortie ne correspondra pas exactement à ces tableaux. | Nom | Type | Description | | --------------- | ------ | ----------------------------------------------------------------------------- | | $PSUEnvironment | string | Le nom de l'environnement dans lequel le script s'exécute (p. ex. Integrated) | | $Repository | string | Le chemin absolu vers le dossier du dépôt. | ### API Il existe un ensemble de variables prédéfinies disponibles dans les terminaux d'API. Vous pourrez utiliser ces variables dans vos scripts. | Variable | Description | Type | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | $Url | L'URL que le client a utilisée pour appeler le terminal | String | | $Method | La méthode HTTP utilisée pour appeler le terminal | String | | $Headers | Les en-têtes fournis par le client pour appeler le terminal | Hashtable | | $Body | La chaîne encodée en UTF8 du contenu de la requête | String | | $Data | Tableau d'octets binaire du contenu de la requête | Byte\[] | | $RemoteIpAddress | L'adresse IP distante du client effectuant la requête | String | | $LocalIpAddress | L'adresse IP distante du service traitant la requête | String | | $RemotePort | Le port distant qui a été appelé pour effectuer la requête | Integer | | $LocalPort | Le port local qui a été utilisé pour traiter la requête | Integer | | $Identity | Le nom de l'identité du principal accédant à l'API. | String | | $UrlDefinition | La définition de l'URL. | String | | $ConnectionId | L'[ID de connexion du contexte HTTP](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.connectioninfo.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ConnectionInfo.Id). | String | | $SessionId | L'[ID de session du contexte HTTP.](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.isession.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ISession.Id) | String | | $RequestId | L'[ID de requête du contexte HTTP](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httpcontext.traceidentifier?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.HttpContext.TraceIdentifier) | String | | $ClaimsPrincipal | Le claims principal de l'utilisateur actuel. Il s'agit du même objet que celui fourni aux stratégies d'accès basées sur les rôles. | ClaimPrincipal | ### Applis Voici les variables disponibles dans les applis en plus des variables globales. | Nom | Description | Type | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------- | | $User | Le nom d'utilisateur de l'utilisateur connecté. $Null si l'authentification est désactivée. | String | | $Roles | Les rôles accordés à l'utilisateur. $Null si l'authentification est désactivée. | String\[] | | $RemoteIpAddress | L'adresse IP distante de l'utilisateur connecté. | String | | $RemotePort | Le port distant de l'utilisateur connecté. | Int | | $ClaimsPrincipal | Le claims principal de l'utilisateur actuel. Il s'agit du même objet que celui fourni aux stratégies d'accès basées sur les rôles. | ClaimPrincipal | | $Headers | Les en-têtes fournis par le navigateur. | hashtable | | $Cookies | Les témoins de requête fournis par le navigateur. | hashtable | | $PSUAppToken | Le jeton d'appli de l'utilisateur actuel. Disponible uniquement lorsque -GrantAppToken est activé. | string | | $PSUURL | L'URL du serveur PSU. Disponible uniquement lorsque -GrantAppToken est activé. | string | | $DashboardName | Le nom de l'appli actuelle | string | | $Query | Les paramètres de la chaîne de requête provenant de l'URL de l'appli | Hashtable | | $RefreshToken | Le jeton d'actualisation lors de l'utilisation d'OpenID Connect | string | | $AccessToken | Le jeton d'appli lors de l'utilisation d'OpenID Connect | string | | $UDPage | Le nom de la page actuelle | string | ### Scripts Il existe plusieurs variables intégrées qui sont définies lorsqu'une tâche est exécutée. Vous pouvez utiliser ces variables dans vos scripts pour récupérer des informations sur la tâche actuelle. | Nom | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | $UAJob | La tâche en cours d'exécution. Cela comprendra des propriétés telles que le script, l'utilisateur qui a démarré la tâche et le moment où la tâche a été démarrée. | | $UAJobId | L'identifiant de la tâche en cours d'exécution. | | $UAScript | Le script en cours d'exécution. Cela comprendra des propriétés telles que le nom du script et le chemin d'accès au script. | | $UAScriptId | L'identifiant du script en cours d'exécution. | | $UASchedule | La planification qui a été utilisée pour démarrer le script. | | $UAScheduleId | L'identifiant de la planification qui a démarré le script. | | $AccessToken | Lors de l'utilisation de l'authentification OIDC, vous pouvez récupérer le jeton d'accès de l'utilisateur actuel afin d'accéder à des ressources en son nom. | | $Roles | Les rôles de l'appelant du script. | #### Structure de l'objet $UAJob Notez que les propriétés peuvent être nulles. Les objets `DateTime` sont retournés dans le fuseau horaire UTC. {% code collapsedlinecount="10" %} ```csharp class Job { public long Id { get; set; } public DateTime CreatedTime { get; set; } public DateTime StartTime { get; set; } public DateTime EndTime { get; set; } public JobStatus Status { get; set; } public string Output { get; set; } public string ScriptFullPath { get; set; } public Identity Identity { get; set; } public Job ParentJob { get; set; } public int ParentLineNumber { get; set; } public string ComputerName { get; set; } public int ProcessId { get; set; } public long MemoryBytes { get; set; } public int RunspaceId { get; set; } public string Activity { get; set; } public string CurrentOperation { get; set; } public int PercentComplete { get; set; } public int SecondsRemaining { get; set; } public string StatusDescription { get; set; } public string Environment { get; set; } public Computer Computer { get; set; } public ActionPreference ErrorAction { get; set; } public IEnumerable Children { get; set; } public IEnumerable Parameters { get; set; } public string Credential { get; set; } public long ScheduleId { get; set; } public bool Triggered { get; set; } public string Trigger { get; set; } public int RetryCount { get; set; } public string Tags { get; set; } public string Schedule { get; set; } public bool Archived { get; set; } public bool Batch { get; set; } public Guid? RunId { get; set; } public string Roles { get; set; } } public enum JobStatus { Queued, Running, Completed, Failed, WaitingOnFeedback, Canceled, Canceling, Historical, Active, TimedOut, Warning, Error } ``` {% endcode %} #### Récupérer l'utilisateur qui a démarré un script Vous pouvez récupérer le nom de l'utilisateur qui a démarré un script en utilisant la variable `UAJob` {% code collapsedlinecount="10" %} ``` $UAJob.Identity.Name ``` {% endcode %} #### Vérifier si une tâche a été exécutée manuellement Vous pouvez vérifier si une tâche a été exécutée manuellement en utilisant les propriétés Schedule et Trigger. {% code collapsedlinecount="10" %} ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` {% endcode %} ## Variables de préférence Les variables de préférence peuvent être configurées sur un script, pendant l'exécution d'une tâche et au niveau global. Elles comprennent : * DebugPreference * ErrorActionPreference * InformationPreference * ProgressPreference * VerbosePreference * WarningPreference Les variables de préférence ont une préséance. La liste suivante est classée par ordre de préséance. Par exemple, si un script définit manuellement la variable `$DebugPreference`, celle-ci remplacera la valeur définie dans la boîte de dialogue des propriétés du script. * Script * Boîte de dialogue d'exécution ou Invoke-PSUScript * Propriétés du script * Paramètres globaux ## API * New-PSUVariable * Get-PSUVariable * Remove-PSUVariable * Set-PSUVariable ### Voir aussi * [Devolutions Academy – Ajout de la fonctionnalité de déverrouillage d'utilisateur](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) --- # 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.devolutions.net/powershell-universal/fr/plateforme/variables.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.