Partager via

Guide des développeurs PowerShell sur Azure Functions

  • Article

Cet article fournit des détails sur la méthode d’écriture d’Azure Functions à l’aide de PowerShell.

Une Azure Function PowerShell (fonction) est représentée comme un script PowerShell qui s’exécute lorsqu’elle est déclenchée. Chaque script de fonction inclut un fichier function.json associé qui définit le comportement de la fonction, comme sa méthode de déclenchement et ses paramètres d’entrée et de sortie. Pour en savoir plus, consultez l’article sur les déclencheurs et les liaisons.

Comme d’autres types de fonctions, les fonctions de script PowerShell utilisent des paramètres correspondant aux noms de toutes les liaisons d’entrée définies dans le fichier function.json. Un paramètre TriggerMetadata contenant des informations supplémentaires sur le déclencheur qui a démarré la fonction est également transmis.

Cet article suppose que vous ayez déjà lu l’article Informations de référence pour les développeurs sur Azure Functions. Il suppose également que vous avez effectué le démarrage rapide de Functions pour PowerShell afin de créer votre première fonction PowerShell.

Structure de dossiers

La structure de dossiers requise pour un projet PowerShell est similaire à la structure ci-après. Cette valeur par défaut peut être modifiée. Pour plus d’informations, consultez la section scriptFile.

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

À la racine du projet se trouve un fichier host.json partagé que vous pouvez utiliser pour configurer l’application de fonction. Chaque fonction a un dossier avec ses propres fichier de code (.ps1) et fichier de configuration de liaison (function.json). Le nom du répertoire parent du fichier function.json est toujours le nom de votre fonction.

Certaines liaisons nécessitent la présence d’un fichier extensions.csproj. Les extensions de liaison, nécessaires dans la version 2.x et les versions ultérieures du runtime Functions, sont définies dans le fichier extensions.csproj, les fichiers bibliothèque proprement dits se trouvant dans le dossier bin. Quand vous développez localement, vous devez inscrire les extensions de liaison. Quand vous développez des fonctions dans le Portail Azure, cette inscription est effectuée pour vous.

Dans les applications de fonction PowerShell, vous pouvez éventuellement avoir un profile.ps1 qui s’exécute au démarrage d’une application de fonction (appelé aussi démarrage à froid). Pour plus d’informations, consultez Profil PowerShell.

Définition d’un script PowerShell en tant que fonction

Par défaut, le runtime Functions recherche votre fonction dans run.ps1, où run.ps1 partage le même répertoire parent en tant que function.json correspondant.

Plusieurs arguments sont transmis à votre script lors de l’exécution. Pour gérer ces paramètres, ajoutez un bloc param en haut de votre script, comme dans l’exemple suivant :

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

Paramètre TriggerMetadata

Le paramètre TriggerMetadata est utilisé pour fournir des informations supplémentaires sur le déclencheur. Ces métadonnées varient d’une liaison à une autre, mais elles contiennent toutes une propriété sys incluant les données suivantes :

$TriggerMetadata.sys
Propriété Description Type
UtcNow Moment, au format UTC, où fonction a été déclenchée DateTime
MethodName Nom de la fonction qui a été déclenchée string
RandGuid GUID unique pour cette exécution de la fonction string

Chaque type de déclencheur a un ensemble de métadonnées différent. Par exemple, $TriggerMetadata pour QueueTrigger contient, entre autres, InsertionTime, Id, DequeueCount. Pour plus d’informations sur les métadonnées du déclencheur de file d’attente, accédez à la documentation officielle des déclencheurs de file d’attente. Consultez la documentation sur le déclencheur que vous utilisez pour savoir ce que les métadonnées de déclencheur incluent.

Liaisons

Dans PowerShell, les liaisons sont configurées et définies dans le fichier function.json d’une fonction. Les fonctions interagissent de plusieurs façons avec des liaisons.

Lecture du déclencheur et données d’entrée

Le déclencheur et les liaisons d’entrée sont lus sous forme de paramètres transmis à votre fonction. direction est défini sur in dans le fichier function.json des liaisons d’entrée. La propriété name définie dans function.json correspond au nom du paramètre, dans le bloc param. Étant donné que PowerShell utilise des paramètres nommés pour la liaison, l’ordre des paramètres importe peu. Toutefois, il est recommandé de suivre l’ordre des liaisons défini dans function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Écriture des données de sortie

Dans Functions, direction est défini sur out dans le fichier function.json d’une liaison de sortie. Vous pouvez écrire dans une liaison de sortie à l’aide de la cmdlet Push-OutputBinding, qui est disponible pour le runtime Functions. Dans tous les cas, la propriété name de la liaison, telle que définie dans function.json, correspond au paramètre Name de la cmdlet Push-OutputBinding.

L’exemple suivant montre comment appeler Push-OutputBinding dans votre script de fonction :

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Vous pouvez également transmettre une valeur pour une liaison spécifique via le pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding se comporte différemment selon la valeur spécifiée pour -Name :

  • Lorsque le nom spécifié ne peut pas être résolu en liaison de sortie valide, une erreur est levée.

  • Lorsque la liaison de sortie accepte une collection de valeurs, vous pouvez appeler Push-OutputBinding à plusieurs reprises pour envoyer (push) plusieurs valeurs.

  • Lorsque la liaison de sortie n’accepte qu’une valeur singleton, un second appel de Push-OutputBinding renvoie une erreur.

Syntaxe Push-OutputBinding

Les éléments suivants sont des paramètres valides pour appeler Push-OutputBinding :

Nom Type Position Description
-Name String 1 Nom de la liaison de sortie que vous souhaitez définir.
-Value Object 2 Valeur de la liaison de sortie vous souhaitez définir, qui est acceptée par la valeur ByValue du pipeline.
-Clobber SwitchParameter named (Facultatif) Si spécifié, force la définition de la valeur pour une liaison de sortie spécifiée.

Les paramètres communs suivants sont également pris en charge :

  • Verbose
  • Debug
  • ErrorAction
  • ErrorVariable
  • WarningAction
  • WarningVariable
  • OutBuffer
  • PipelineVariable
  • OutVariable

Pour plus d’informations, consultez À propos des paramètres communs.

Exemple de Push-OutputBinding : Réponses HTTP

Un déclencheur HTTP retourne une réponse à l’aide d’une liaison de sortie nommée response. Dans l’exemple suivant, la liaison de sortie response a la valeur « output #1 » :

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #1"
})

Étant donné que la sortie utilise le protocole HTTP, qui n’accepte qu’une valeur singleton, une erreur est levée lorsque Push-OutputBinding est appelé une seconde fois.

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #2"
})

Pour les sorties qui n’acceptent que les valeurs singleton, vous pouvez utiliser le paramètre -Clobber pour remplacer l’ancienne valeur au lieu de tenter de l’ajouter à une collection. L’exemple suivant suppose que vous avez déjà ajouté une valeur. Grâce à -Clobber, la réponse de l’exemple suivant remplace la valeur existante pour retourner la valeur « output #3 » :

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #3"
}) -Clobber

Exemple de Push-OutputBinding : Liaison de sortie de file d’attente

Push-OutputBinding est utilisé pour envoyer des données aux liaisons de sortie, comme une liaison de sortie de Stockage File d’attente Azure. Dans l’exemple suivant, le message écrit dans la file d’attente a la valeur de « output #1 » :

PS >Push-OutputBinding -Name outQueue -Value "output #1"

La liaison de sortie d’une file d’attente Stockage accepte plusieurs valeurs de sortie. Dans ce cas, l’appel de l’exemple suivant après la première écrit dans la file d’attente une liste de deux éléments : « output #1 » et « output #2 ».

PS >Push-OutputBinding -Name outQueue -Value "output #2"

L’exemple suivant, lors d’un appel après les deux précédents, ajoute deux valeurs supplémentaires à la collection de sortie :

PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

Lors de l’écriture dans la file d’attente, le message contient ces quatre valeurs : « output #1 », « output #2 », « output #3 » et « output #4 ».

Cmdlet Get-OutputBinding

Vous pouvez utiliser la cmdlet Get-OutputBinding pour récupérer les valeurs actuellement définies pour vos liaisons de sortie. Cette cmdlet récupère une table de hachage qui contient les noms des liaisons de sortie avec leurs valeurs respectives.

Voici un exemple d’utilisation de Get-OutputBinding pour retourner des valeurs de liaisons actuelles :

Get-OutputBinding

Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding contient également un paramètre nommé -Name, qui peut être utilisé pour filtrer la liaison retournée, comme dans l’exemple suivant :

Get-OutputBinding -Name MyQ*

Name                           Value
----                           -----
MyQueue                        myData

Les caractères génériques (*) sont pris en charge dans Get-OutputBinding.

Journalisation

La journalisation dans des fonctions PowerShell fonctionne comme la journalisation PowerShell standard. Vous pouvez utiliser les cmdlets de journalisation pour écrire dans chaque flux de sortie. Chaque cmdlet est mappée à un niveau de journal utilisé par Functions.

Niveau de journalisation de Functions Cmdlet de journalisation
Error Write-Error
Avertissement Write-Warning
Information Write-Information
Write-Host
Write-Output
Écrit au niveau de journalisation Information.
Débogage Write-Debug
Trace Write-Progress
Write-Verbose

En plus de ces cmdlets, tout de qui est écrit dans le pipeline est redirigé vers le niveau de journal Information et affiché avec la mise en forme PowerShell par défaut.

Important

L’utilisation des cmdlets Write-Verbose ou Write-Debug ne suffit pas pour voir la journalisation commentée et de niveau de débogage. Vous devez également configurer le seuil du niveau de journal, qui déclare le niveau de journaux que vous souhaitez. Pour en savoir plus, consultez Configurer le niveau de journal de Function App.

Configurer le niveau de journal de Function App

Azure Functions vous permet de définir le niveau de seuil pour contrôler plus facilement comment Azure Functions écrit dans les journaux. Utilisez la propriété logging.logLevel.default dans le fichier host.json pour définir le seuil de toutes les traces écrites dans la console. Ce paramètre s’applique à toutes les fonctions dans votre Function App.

L’exemple suivant définit le seuil d’activation de la journalisation commentée pour toutes les fonctions, mais définit le seuil d’activation la journalisation du débogage pour une fonction nommée MyFunction :

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}

Pour plus d’informations, consultez l’article de référence sur host.json reference.

Affichage des journaux

Si votre Function App s’exécute dans Azure, vous pouvez utiliser Application Insights pour la surveiller. Consultez Supervision des fonctions Azure pour en savoir plus sur l’affichage et l’interrogation des journaux d’activité de fonction.

Si vous exécutez votre Function App localement pour le développement, elle consigne par défaut dans le système de fichiers. Pour afficher les journaux dans la console, définissez la variable d’environnement AZURE_FUNCTIONS_ENVIRONMENT sur Development avant de démarrer Function App.

Types de déclencheurs et liaisons

Vous pouvez utiliser plusieurs déclencheurs et liaisons avec votre application de fonction. La liste complète des déclencheurs et liaisons est disponible ici.

Tous les déclencheurs et liaisons sont représentés dans le code par quelques types de données réels :

  • Hashtable
  • string
  • byte[]
  • int
  • double
  • HttpRequestContext
  • HttpResponseContext

Les cinq premiers types de cette liste sont des types .NET standard. Les deux derniers sont utilisés par le déclencheur HttpTrigger uniquement.

Chaque paramètre de liaison dans vos fonctions doit être de l’un de ces types.

Déclencheurs et liaisons HTTP

Les déclencheurs HTTP et webhook ainsi que les liaisons de sortie HTTP utilisent les objets de requête et de réponse pour représenter la messagerie HTTP.

Objet Requête

L’objet de requête transmis dans le script est de type HttpRequestContext, qui inclut les propriétés suivantes :

Propriété Description Type
Body Objet qui contient le corps de la demande. Body est sérialisé dans le meilleur type en fonction des données. Par exemple, si les données sont au format JSON, elles sont transmises sous forme de table de hachage. Si les données sont au format chaîne, il est transmis sous forme de chaîne. object
Headers Dictionnaire qui contient les en-têtes de requête. Dictionary<string,string>*
Method Méthode HTTP de la demande. string
Params Objet qui contient les paramètres de routage de la demande. Dictionary<string,string>*
Query Objet qui contient les paramètres de la requête. Dictionary<string,string>*
Url URL de la demande. string

* Toutes les clés Dictionary<string,string> sont insensibles à la casse.

Objet Réponse

L’objet de réponse qui doit être retourné est de type HttpResponseContext, qui inclut les propriétés suivantes :

Propriété Description Type
Body Objet qui contient le corps de la réponse. object
ContentType Abréviation définissant le type de contenu pour la réponse. string
Headers Objet qui contient les en-têtes de la réponse. Dictionnaire ou table de hachage
StatusCode Code d’état HTTP de la réponse. chaîne ou entier

Accès à la demande et à la réponse

Lorsque vous utilisez des déclencheurs HTTP, vous pouvez accéder à la requête HTTP comme vous le feriez avec toute autre liaison d’entrée. Elle se trouve dans le bloc param.

Utilisez un objet HttpResponseContext pour retourner une réponse, comme indiqué dans l’exemple suivant :

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

Le résultat de l’appel de cette fonction est alors :

PS > irm http://localhost:5001?Name=Functions
Hello Functions!

Forçage de type pour les déclencheurs et liaisons

Pour certaines liaisons, comme la liaison d’objet blob, vous pouvez spécifier le type du paramètre.

Par exemple, pour que les données du stockage d’objets blob soient fournies sous forme de chaîne, ajoutez le forçage de type suivant au bloc param :

param([string] $myBlob)

Profil PowerShell

PowerShell inclut le concept de profil PowerShell. Si vous ne connaissez pas les profils PowerShell, consultez À propos des profils.

Dans les fonctions PowerShell, le script de profil est exécuté une fois par instance worker PowerShell dans l’application, lors du premier déploiement et après une inactivité (démarrage à froid). Lorsque la concurrence est activée en définissant la valeur PSWorkerInProcConcurrencyUpperBound, le script de profil est exécuté pour chaque instance d’exécution créée.

Lorsque vous créez une Function App à l’aide d’outils, tels que Visual Studio Code et Azure Functions Core Tools, une valeur profile.ps1 par défaut est créée pour vous. Le profil par défaut est conservé dans le référentiel Core Tools GitHub et contient :

  • Authentification MSI automatique sur Azure.
  • La possibilité d’activer des alias Azure PowerShell AzureRM PowerShell si vous le souhaitez.

Versions de PowerShell

Le tableau suivant répertorie les versions de PowerShell disponibles pour chaque version majeure du runtime Functions, ainsi que la version .NET requise :

Version de Functions Version de PowerShell Version de .NET
4.x PowerShell 7.4 .NET 8
4.x PowerShell 7.2 (fin du support) .NET 6

Vous pouvez afficher la version en imprimant $PSVersionTable à partir de n’importe quelle fonction.

Pour plus d’informations sur la stratégie de support du runtime Azure Functions, consultez cet article

Remarque

La prise en charge de PowerShell 7.2 dans Azure Functions prendra fin le 8 novembre 2024. Vous devrez peut-être résoudre certains changements cassants lors de la mise à niveau de vos fonctions PowerShell 7.2 pour qu’elles s’exécutent sur PowerShell 7.4. Pour effectuer la mise à niveau vers PowerShell 7.4, suivez ce guide de migration.

Exécution locale sur une version spécifique

Lorsque vous exécutez vos fonctions PowerShell localement, vous devez ajouter le paramètre "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" au tableau Values dans le fichier local.setting.json à la racine du projet. Lorsque vous utilisez PowerShell 7.4 en local, votre fichier local.settings.json ressemble à l’exemple suivant :

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4"
  }
}

Remarque

Dans les fonctions PowerShell, la valeur « ~7 » pour FUNCTIONS_WORKER_RUNTIME_VERSION fait référence à la version « 7.0.x ». Nous ne mettons pas automatiquement à niveau les applications de fonction PowerShell qui ont « ~7 » jusqu’à « 7.4 ». À l’avenir, pour les applications de fonction PowerShell, nous exigerons que les applications spécifient à la fois la version majeure et la version mineure qu’elles veulent cibler. Par conséquent, il est nécessaire de mentionner « 7.4 » si vous souhaitez cibler « 7.4.x »

Changement de version de PowerShell

Prenez ces considérations en compte avant de migrer votre application de fonction PowerShell vers PowerShell 7.4 :

  • Comme la migration peut introduire des changements cassants dans votre application, passez en revue ce guide de migration avant de mettre à jour votre application vers PowerShell 7.4.

  • Assurez-vous que votre application de fonction s’exécute sur la dernière version du runtime Functions dans Azure, qui est la version 4.x. Pour plus d’informations, consultez Afficher et mettre à jour la version actuelle du runtime.

Procédez comme suit pour modifier la version de PowerShell utilisée par votre application de fonction. Vous pouvez effectuer cette opération dans le Portail Azure ou en tirant parti de PowerShell.

  1. Dans le portail Azure, accédez à une application de fonction.

  2. Sous Paramètres, sélectionnez Configuration. Dans l’onglet Paramètres généraux, recherchez la version de PowerShell.

    image

  3. Choisissez la version de PowerShell Core souhaitée, puis sélectionnez Enregistrer. Lorsque vous êtes averti du redémarrage en attente, sélectionnez Continuer. L’application de fonction redémarre sur la version de PowerShell choisie.

Remarque

La prise en charge d’Azure Functions pour PowerShell 7.4 est en disponibilité générale (GA). PowerShell 7.4 est peut-être toujours indiqué comme étant en préversion sur le Portail Azure, mais cette mention sera bientôt mise à jour pour refléter l’état de disponibilité générale.

L’application de fonction redémarre une fois la modification apportée à la configuration.

Gestion des dépendances

La gestion de modules dans Azure Functions écrits dans PowerShell peut être abordée de deux manières : en utilisant la fonctionnalité Dépendances managées ou en incluant les modules directement dans le contenu de votre application. Chaque méthode a ses propres avantages et le choix de celle appropriée dépend de vos besoins spécifiques.

Choisir l’approche de gestion de modules appropriée

Pour quoi utiliser la fonctionnalité Dépendances managées ?

  • Installation initiale simplifiée : gère automatiquement l’installation de modules en fonction de votre fichier requirements.psd1.
  • Mises à niveau automatiques : les modules sont automatiquement mis à jour, notamment les correctifs de sécurité, sans nécessiter d’intervention manuelle.

Pourquoi inclure des modules dans le contenu d’une application ?

  • Aucune dépendance sur le référentiel PowerShell Gallery : les modules sont regroupés avec votre application, éliminant ainsi les dépendances externes.
  • Plus de contrôle : évite le risque de régressions provoquées par des mises à niveau automatiques, ce qui vous procure un contrôle total sur les versions de module utilisées.
  • Compatibilité : fonctionne sur Consommation flexible et elle est recommandée pour d’autres SKU Linux.

Fonctionnalité Dépendances managées

La fonctionnalité Dépendances managées permet à Azure Functions de télécharger et gérer automatiquement les modules PowerShell spécifiés dans le fichier requirements.psd1. Cette fonctionnalité est activée par défaut dans les nouvelles applications de fonction PowerShell.

Configuration de requirements.psd1

Pour utiliser la fonctionnalité Dépendances managées dans Azure Functions avec PowerShell, vous devez configurer un fichier requirements.psd1. Ce fichier spécifie les modules nécessaires à votre fonction. Azure Functions télécharge et met à jour automatiquement ces modules pour veiller à ce que votre environnement reste à jour.

Voici comment installer et configurer le fichier requirements.psd1 :

  1. Créez un fichier requirements.psd1 dans le répertoire racine de votre instance Azure Function s’il n’en existe pas encore.
  2. Définissez les modules et leurs versions dans une structure de données PowerShell.

Exemple de fichier requirements.psd1 :

@{
    'Az' = '9.*'  # Specifies the Az module and will use the latest version with major version 9
}

Notamment les modules dans le contenu d’une application

Pour mieux contrôler les versions de votre module et éviter les dépendances sur des ressources externes, vous pouvez inclure les modules directement dans le contenu de votre application de fonction.

Pour inclure des modules personnalisés :

  1. Créez un dossier Modules à la racine de votre application de fonction.

    mkdir ./Modules

  2. Copiez les modules dans le dossier Modules en utilisant l’une des méthodes suivantes :

    • Si les modules sont déjà disponibles localement :

      Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse

    • Utilisez Save-Module à récupérer dans le référentiel PowerShell Gallery :

      Save-Module -Name MyCustomModule -Path ./Modules

    • Utilisez Save-PSResource à partir du module PSResourceGet :

      Save-PSResource -Name MyCustomModule -Path ./Modules

Votre application de fonction doit avoir la structure suivante :

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

Lorsque vous démarrez votre Function App, le rôle de travail du langage PowerShell ajoute ce dossier Modules à $env:PSModulePath afin que vous puissiez vous appuyer sur le chargement automatique de module comme vous le feriez dans un script PowerShell classique.

Résolution des problèmes de Dépendances managées

Activation de Dépendances managées

Pour que Dépendances managées fonctionne, vous devez activer la fonctionnalité dans host.json :

{
  "managedDependency": {
          "enabled": true
       }
}

Cibler des versions spécifiques

Lorsque vous ciblez des versions de module, il est important de suivre les étapes suivantes pour veiller à ce que la version de module correcte soit chargée :

  1. Spécifiez la version de module dans requirements.psd1 : 

    @{
  'Az.Accounts' = '1.9.5'
}

  2. Ajoutez une instruction d’importation à profile.ps1 : 

    Import-Module Az.Accounts -RequiredVersion '1.9.5'

Le suivi de cette procédure garantit que la version spécifiée est chargée lorsque votre fonction démarre.

Configurer des paramètres d’intervalle de Dépendance Managée spécifiques

Vous pouvez configurer la fonction dont la fonctionnalité Dépendances managées est téléchargée et installée en utilisant les paramètres d’application suivants :

Paramètre Valeur par défaut Description
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sept jours) Contrôle la période de mise à jour en arrière-plan pour les applications de fonction PowerShell.
MDNewSnapshotCheckPeriod 01:00:00 (une heure) Spécifie la fréquence de recherche de mises à jour par le Worker PowerShell.
MDMinBackgroundUpgradePeriod 1.00:00:00 (un jour) Temps minimal entre les vérifications de mise à niveau.

Considérations relatives à la gestion des dépendances

  • Accès à Internet : les dépendances managées doivent pouvoir accéder à https://www.powershellgallery.com pour télécharger des modules. Vérifiez que votre environnement autorise cet accès, notamment la modification des règles de réseau virtuel/pare-feu, le cas échéant.
  • Acceptation de licence : Dépendances managées ne prend pas en charge les modules qui nécessitent une acceptation de licence.
  • Plan Consommation flexible : la fonctionnalité Dépendances managées n’est pas prise en charge dans le plan Consommation flexible. Utilisez des modules personnalisés à la place.
  • Emplacements de module : sur votre ordinateur local, les modules sont généralement installés dans l’un des dossiers globalement disponibles dans votre $env:PSModulePath. Lors de l’exécution dans Azure, le $env:PSModulePath pour une application de fonction PowerShell diffère de $env:PSModulePath dans un script PowerShell régulier et contient le dossier Modules chargé avec les contenus de votre application et un emplacement distinct managé par Dépendances managées.

Variables d'environnement

Dans Functions, les paramètres de l’application, par exemple, les chaînes de connexion de service, sont exposées en tant que variables d’environnement pendant l’exécution. Vous pouvez accéder à ces paramètres à l’aide de $env:NAME_OF_ENV_VAR, comme illustré ici dans l’exemple suivant :

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

Plusieurs méthodes sont possibles pour ajouter, mettre à jour et supprimer des paramètres d’une application de fonction :

Les changements apportés aux paramètres d’application de fonction nécessitent le redémarrage de votre application de fonction.

Lors de l’exécution en local, les paramètres de l’application sont lus à partir du fichier projet local.settings.json.

Accès concurrentiel

Par défaut, le runtime Functions PowerShell ne peut traiter qu’un appel de fonction à la fois. Toutefois, ce niveau de concurrence peut ne pas suffire dans les situations suivantes :

  • Lorsque vous essayez de gérer un grand nombre d’appels en même temps.
  • Lorsque vous disposez de fonctions qui appellent d’autres fonctions dans la même Function App.

Il existe plusieurs modèles de concurrence que vous pouvez explorer en fonction du type de charge de travail :

  • Augmenter FUNCTIONS_WORKER_PROCESS_COUNT. L’augmentation de ce paramètre permet de gérer les appels de fonction dans plusieurs processus au sein de la même instance, ce qui entraîne une certaine surcharge du processeur et de la mémoire. En général, les fonctions liées aux E/S ne subissent pas cette surcharge. Pour les fonctions liées à l’UC, l’impact peut être significatif.

  • Augmenter la valeur du paramètre d’application PSWorkerInProcConcurrencyUpperBound. L’augmentation de ce paramètre permet de créer plusieurs instances d’exécution dans le même processus, ce qui réduit considérablement la surcharge du processeur et de la mémoire.

Vous définissez ces variables d’environnement dans les paramètres d’application de votre application de fonction.

Selon votre cas d’usage, Durable Functions peut considérablement améliorer la scalabilité. Pour plus d’informations, consultez les modèles d’application Durable Functions.

Notes

Il est possible que vous receviez des avertissements de type « les requêtes sont mises en file d’attente en l’absence d’instances d’exécution disponibles ». Notez qu’il ne s’agit pas d’une erreur. Ce message vous informe que les requêtes sont en file d’attente et qu’elles seront gérées au terme des requêtes précédentes.

Considérations relatives à l’utilisation de la concurrence

PowerShell est un langage de scripts single_threaded par défaut. Toutefois, la concurrence peut être ajoutée en utilisant plusieurs instances d’exécution de PowerShell dans le même processus. Le nombre d’instances d’exécution créées, et par conséquent le nombre de threads simultanés par Worker, sont limités par le paramètre d’application PSWorkerInProcConcurrencyUpperBound. Par défaut, le nombre d’instances d’exécution est défini sur 1 000 dans la version 4.x du runtime Functions. Dans les versions 3.x et versions antérieures, le nombre maximal d’instances d’exécution est défini sur 1. Le débit de votre application de fonction est affecté par la quantité de processeur et de mémoire disponible dans le plan sélectionné.

Azure PowerShell utilise des contextes au niveau du processus et un état pour vous libérer d’une saisie excessive. Toutefois, si vous activez la concurrence dans votre Function App et appelez des actions qui changent l’état, vous pouvez être confronté à des conditions de concurrence. Ces conditions de concurrence sont difficiles à déboguer car un appel s’appuie sur un état donné et que l’autre appel a changé l’état.

La concurrence est très importante dans Azure PowerShell car certaines opérations peuvent prendre beaucoup de temps. Faites toutefois preuve de vigilance. Si vous pensez que vous êtes confronté à une condition de concurrence, définissez le paramètre d’application PSWorkerInProcConcurrencyUpperBound sur 1 et utilisez plutôt l’isolation du niveau processus Worker du langage pour la concurrence.

Configurer la fonction scriptFile

Par défaut, une fonction PowerShell est exécutée à partir de run.ps1, fichier qui partage le même répertoire parent que son function.json correspondant.

La propriété scriptFile dans function.json peut être utilisée pour obtenir une structure de dossiers semblable à l’exemple suivant :

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

Dans ce cas, le function.json pour myFunction inclut une propriété scriptFile faisant référence au fichier contenant la fonction exportée à exécuter.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

Utiliser des modules PowerShell en configurant un entryPoint

Les fonctions PowerShell de cet article sont affichées avec le fichier de script run.ps1 par défaut généré par les modèles. Vous pouvez toutefois également inclure vos fonctions dans des modules PowerShell. Vous pouvez faire référence à votre code de fonction spécifique dans le module à l’aide des champs scriptFile et entryPoint dans le fichier de configuration « function.json ».

Dans ce cas, entryPoint est le nom d’une fonction ou d’une cmdlet dans le module PowerShell référencé dans scriptFile.

Prenez en compte la structure de dossiers suivante :

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

Où PSFunction.psm1 contient :

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

Dans cet exemple, la configuration de myFunction inclut une propriété scriptFile qui fait référence à PSFunction.psm1, un module PowerShell se trouvant dans un autre dossier. La propriété entryPoint fait référence à la fonction Invoke-PSTestFunc, le point d’entrée dans le module.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

Avec cette configuration, le Invoke-PSTestFunc est exécuté exactement comme le serait un run.ps1.

Considérations relatives aux fonctions PowerShell

Lorsque vous utilisez des fonctions PowerShell, tenez compte des considérations décrites dans les sections suivantes.

Démarrage à froid

Lorsque vous développez Azure Functions dans le modèle d’hébergement serverless, les démarrages à froid sont une réalité. Le démarrage à froid fait référence à la période nécessaire à votre Function App pour commencer à traiter une requête. Le démarrage à froid se produit plus fréquemment dans le plan de consommation, car votre Function App s’arrête pendant les périodes d’inactivité.

Éviter d’utiliser Install-Module

L’exécution de Install-Module dans votre script de fonction sur chaque appel peut entraîner des problèmes de performance. Au lieu de cela, utilisez Save-Module ou Save-PSResource avant de publier votre application de fonction pour regrouper les modules nécessaires.

Pour découvrir plus d’informations, consultez la section Gestion des dépendances.

Étapes suivantes

Pour plus d’informations, consultez les ressources suivantes :