Guide du développeur Azure Functions

Dans Azure Functions, des fonctions spécifiques partagent quelques concepts techniques et composants de base, quels que soient le langage et la liaison que vous utilisez. Avant de passer à l'apprentissage des détails propres à un langage ou une liaison donnés, veillez à lire cette présentation qui s'applique à l’ensemble d’entre eux.

Cet article suppose que vous avez déjà lu la Présentation d’Azure Functions.

Code de fonction

La fonction est le principal concept d'Azure Functions. Une fonction contient deux éléments importants - votre code, qui peut être écrit dans un certain nombre de langages, et, dans certaines configurations, le fichier function.json. Pour les langages compilés, ce fichier de configuration est généré automatiquement à partir des annotations de votre code. Pour les langages de script, vous devez fournir le fichier de configuration vous-même.

Le fichier function.json définit le déclencheur, les liaisons de fonction et d’autres paramètres de configuration. Chaque fonction possède un seul déclencheur. Le runtime utilise ce fichier de configuration pour déterminer les événements à surveiller et comment passer des données et renvoyer des données à partir de l’exécution d’une fonction. Voici un exemple de fichier function.json.

{
    "disabled":false,
    "bindings":[
        // ... bindings here
        {
            "type": "bindingType",
            "direction": "in",
            "name": "myParamName",
            // ... more depending on binding
        }
    ]
}

Pour plus d’informations, consultez Concepts des déclencheurs et liaisons Azure Functions.

La propriété bindings vous permet de configurer les liaisons et les déclencheurs. Chaque liaison partage quelques paramètres communs et des paramètres propres à un type de liaison donné. Chaque liaison requiert les paramètres suivants :

Propriété Valeurs Type Commentaires
type Nom de la liaison.

Par exemple : queueTrigger.
string
direction in, out string Indique si la liaison sert à recevoir des données dans la fonction ou à envoyer des données à partir de la fonction.
name Identificateur de fonction.

Par exemple : myQueue.
string Le nom utilisé pour les données liées dans la fonction. Pour C#, il s’agit d’un nom d'argument ; pour JavaScript, il s’agit de la clé dans une liste de clés/valeurs.

Conteneur de fonctions

Une application de fonction fournit un contexte d’exécution dans Azure dans lequel vos fonctions s’exécutent. À ce titre, elle constitue l'unité de déploiement et de gestion de vos fonctions. Un conteneur de fonctions est constitué d’une ou de plusieurs des fonctions individuelles qui sont gérées, déployées et mises à l’échelle ensemble. Toutes les fonctions d'une application de fonction partagent le même plan de tarification, la même méthode de déploiement et la même version du runtime. Considérez un conteneur de fonctions comme un moyen d’organiser et de gérer collectivement vos fonctions. Pour en savoir plus, consultez Gérer une application de fonction.

Notes

Toutes les fonctions d’une application de fonction doivent être créées dans le même langage. Dans les version précédentes du runtime Azure Functions, cela n’était pas obligatoire.

Structure de dossiers

Le code de toutes les fonctions d’une application de fonctions spécifique se trouve dans un dossier de projet racine qui contient un fichier de configuration d’hôte. Le fichier host.json contient des configurations spécifiques du runtime et se trouve dans le dossier racine de la Function App. Un dossier bin contient des packages et autres fichiers de bibliothèque requis par la Function App. Les structures de dossiers spécifiques requises par l’application de fonction dépendent du langage :

Dans les versions 2.x et ultérieures du runtime Functions, toutes les fonctions dans l’application de fonction doivent partager la même pile de langage.

La structure de dossiers ci-dessus est recommandée et utilisée par défaut pour une application de fonction. Si vous souhaitez changer l’emplacement du code d’une fonction, modifiez la section scriptFile du fichier scriptFile. Nous vous recommandons également d’utiliser un package de déploiement pour déployer votre projet sur votre application de fonction dans Azure. Vous pouvez également utiliser des outils existants tels que l’intégration et le déploiement continus et Azure DevOps.

Notes

En cas de déploiement manuel d’un package, veillez à déployer votre fichier host.json et vos dossiers de fonction directement dans le dossier . N’incluez pas le dossier wwwroot dans vos déploiements. Sinon, vous vous retrouverez avec wwwroot\wwwroot dossiers.

Utiliser des outils locaux pour la publication

Vous pouvez créer et publier des applications de fonction à l’aide de différents outils, notamment Visual Studio, Visual Studio Code, IntelliJ, Eclipse et Azure Functions Core Tools. Pour plus d’informations, consultez Coder et tester Azure Functions localement.

Comment modifier des fonctions dans le portail Azure

L’éditeur de fonctions intégré au portail Azure vous permet de mettre à jour votre code et votre fichier function.json directement en ligne. Cela n’est recommandé que pour les petites modifications ou les preuves de concept - la meilleure pratique est d’utiliser un outil de développement local comme VS Code.

Exécution parallèle

Lorsque plusieurs événements de déclenchement se produisent plus rapidement qu'un runtime de fonction monothread ne peut les traiter, le runtime peut appeler la fonction plusieurs fois en parallèle. Si un conteneur de fonctions utilise le plan d’hébergement de consommation, il peut monter automatiquement effectuer un scale-out. Que l’application s’exécute sur le plan d’hébergement de consommation ou sur un plan d’hébergement App Service standard, chaque instance de l’application de fonction peut traiter en parallèle des appels de fonction simultanés en utilisant plusieurs threads. Le nombre maximal d’appels de fonction simultanés dans chaque instance de chaque application de fonction varie en fonction du type de déclencheur utilisé, ainsi que des ressources utilisées par d’autres fonctions au sein de l’application de fonction.

Contrôle de version du runtime Functions

Vous pouvez configurer la version du runtime Functions en utilisant le paramètre d’application FUNCTIONS_EXTENSION_VERSION. Par exemple, la valeur « ~3 » indique que votre application de fonction utilise 3.x comme version principale. Les applications de fonction sont mises à niveau vers chaque nouvelle version mineure lorsqu’elles sont disponibles. Pour obtenir plus d’informations, notamment sur la façon d’afficher la version exacte de votre application de fonction, consultez Guide pratique pour cibler des versions du runtime Azure Functions.

Référentiels

Le code pour Azure Fonctions est open source et stocké dans des dépôts GitHub :

Liaisons

Voici un tableau de toutes les liaisons prises en charge.

Ce tableau présente les liaisons qui sont prises en charge dans les versions majeures du runtime Azure Functions :

Type 1.x 2.x et ultérieures1 Déclencheur Entrée Output
Stockage Blob
Azure Cosmos DB
Azure SQL (préversion)
Dapr3
Event Grid
Hubs d'événements
HTTP webhooks
IoT Hub
Kafka2
Mobile Apps
Notification Hubs
Stockage File d’attente
RabbitMQ2
SendGrid
Service Bus
SignalR
Stockage Table
Minuteur
Twilio

1 À compter du runtime de la version 2.x, toutes les liaisons à l’exception de HTTP et du minuteur doivent être inscrites. Consultez Inscrire des extensions de liaison.

2 Les déclencheurs ne sont pas pris en charge dans le plan Consommation. Nécessite des déclencheurs basés sur le runtime.

3 Pris en charge uniquement dans Kubernetes, IoT Edge et d’autres modes autohébergés uniquement.

Vous rencontrez des problèmes avec des erreurs de liaisons ? Consultez la documentation Codes d’erreur de liaison d’Azure Functions.

Connexions

Votre projet de fonction référence des informations de connexion par nom à partir de son fournisseur de configuration. Il n’accepte pas directement les détails de la connexion, ce qui leur permet d’être changés dans l’ensemble des environnements. Par exemple, une définition de déclencheur peut inclure une propriété connection. Celle-ci peut faire référence à une chaîne de connexion, mais vous ne pouvez pas définir la chaîne de connexion directement dans un function.json. Au lieu de cela, vous devez définir connection sur le nom d’une variable d’environnement qui contient la chaîne de connexion.

Le fournisseur de configuration par défaut utilise des variables d’environnement. Celles-ci peuvent être définies par paramètres d’application lors de l’exécution dans le service Azure Functions, ou à partir du fichier de paramètres local lors du développement local.

Valeurs de connexion

Quand le nom de la connexion correspond à une seule valeur exacte, le runtime identifie la valeur en tant que chaîne de connexion, qui comprend généralement un secret. Les détails d’une chaîne de connexion sont définis par le service auquel vous souhaitez vous connecter.

Toutefois, un nom de connexion peut également faire référence à un ensemble de plusieurs éléments de configuration, utiles pour la configuration des connexions basées sur l’identité. Les variables d’environnement peuvent être traitées comme une collection à l’aide d’un préfixe partagé qui se termine par deux traits de soulignement __. Il est ensuite possible de référencer le groupe en définissant le nom de la connexion sur ce préfixe.

Par exemple, la propriété connection d’une définition de déclencheur Blob Azure peut être « Storage1 ». Tant qu’aucune valeur de chaîne unique n’est configurée par une variable d’environnement nommée « Stockage1 », une variable d’environnement nommée Storage1__blobServiceUri peut être utilisée pour informer la propriété blobServiceUri de la connexion. Les propriétés de connexion sont différentes pour chaque service. Reportez-vous à la documentation du composant qui utilise la connexion.

Notes

Lorsque vous utilisez Azure App Configuration ou Key Vault pour fournir des paramètres pour les connexions d’identité managée, les noms de paramètres doivent utiliser un séparateur de clé valide tel que : ou / à la place de __ pour s’assurer que les noms sont résolus correctement.

Par exemple : Storage1:blobServiceUri.

Configurer une connexion basée sur une identité

Dans Azure Functions, certaines connexions peuvent être configurées pour utiliser une identité plutôt qu’un secret. La prise en charge dépend de l’extension qui utilise la connexion. Dans certains cas, une chaîne de connexion peut toujours être nécessaire dans Functions, même si le service auquel vous vous connectez prend en charge les connexions basées sur une identité. Pour obtenir un tutoriel sur la configuration de vos applications de fonction avec des identités managées, consultez le tutoriel Création d’une application de fonction avec des connexions basées sur l’identité.

Les connexions basées sur une identité sont prises en charge par les composants suivants :

Source de connexion Plans pris en charge En savoir plus
Déclencheurs et liaisons d’objets blob Azure Tous Extension Objets blob Azure version 5.0.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Déclencheurs et liaisons de Files d’attente Azure Tous Extension Files d’attente Azure version 5.0.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Tables Azure (lors de l’utilisation de Stockage Azure) Tous Extension Tables Azure version 1.0.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Déclencheurs et liaisons Azure Event Hubs Tous Extension Azure Event Hubs version 5.0.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Déclencheurs et liaisons Azure Service Bus Tous Extension Azure Service Bus version 5.0.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Déclencheurs et liaisons Azure Cosmos DB - Préversion Premium élastique Extension Azure Cosmos DB version 4.0.0-preview1 ou ultérieure,
Préversion du pack d’extensions 4.0.0 ou version ultérieure
Fournisseur de stockage Durable Functions (Stockage Azure) - Préversion Tous Extension Durable Functions version 2.7.0 ou ultérieure,
Pack d’extensions 3.3.0 ou version ultérieure
Stockage exigé par l’hôte (« AzureWebJobsStorage ») - Préversion Tous Connexion au stockage hôte avec une identité

Quand elles sont hébergées dans le service Azure Functions, les connexions basées sur une identité utilisent une identité managée. L’identité attribuée par le système est utilisée par défaut, bien qu’une identité attribuée par l’utilisateur puisse être spécifiée avec les propriétés credential et clientID. Notez que la configuration d’une identité affectée par l’utilisateur avec un ID de ressource n’est pas prise en charge. Lors d’une exécution dans d’autres contextes, tels que le développement local, votre identité de développeur est utilisée à la place, même si cela peut être personnalisé. Consultez Développement local avec connexions basées sur une identité.

Accorder l’autorisation à l’identité

Quelle que soit l’identité utilisée, elle doit avoir les autorisations nécessaires pour effectuer les actions prévues. Pour la plupart des services Azure, cela signifie que vous devez attribuer un rôle dans Azure RBAC en utilisant des rôles intégrés ou personnalisés qui fournissent ces autorisations.

Important

Parmi les autorisations exposées par le service cible, certaines ne sont peut-être pas nécessaires pour tous les contextes. Dans la mesure du possible, adhérez au principe du privilège minimum, en accordant à l’identité uniquement les privilèges nécessaires. Par exemple, si l’application a juste besoin de pouvoir lire à partir d’une source de données, utilisez un rôle qui a uniquement l’autorisation de lecture. Il serait inapproprié d’attribuer un rôle qui autorise aussi l’écriture dans ce service, car ce serait une autorisation excessive pour une opération de lecture. De même, vous voudrez vous assurer que l’attribution de rôle est limitée aux seules ressources qui doivent être lues.

Choisissez un onglet ci-dessous afin d’en savoir plus sur les autorisations pour chaque composant :

Vous devrez créer une attribution de rôle qui donne accès à votre conteneur de blobs au moment de l’exécution. Les rôles de gestion comme Propriétaire ne sont pas suffisants. Le tableau suivant présente les rôles intégrés qui sont recommandés lors de l’utilisation de l’extension Stockage Blob dans le cadre d’un fonctionnement normal. Votre application peut nécessiter des autorisations supplémentaires en fonction du code que vous écrivez.

Type de liaison Exemples de rôles intégrés
Déclencheur Propriétaire des données d’objet Blob de stockageetContributeur aux données en file d’attente du stockage1

Des autorisations supplémentaires doivent également être accordées à la connexion AzureWebJobsStorage.2
Liaison d’entrée Lecteur des données blob du stockage
Liaison de sortie Propriétaire des données Blob du stockage

1 Le déclencheur Blob gère l’échec sur plusieurs tentatives en écrivant des blobs incohérents dans une file d’attente sur le compte de stockage spécifié par la connexion.

2 La connexion AzureWebJobsStorage est utilisée en interne pour les blobs et les files d’attente qui activent le déclencheur. Si elle est configurée de manière à utiliser une connexion basée sur une identité, elle aura besoin d’autorisations supplémentaires au-delà de la spécification par défaut. Celles-ci sont couvertes par les rôles Propriétaire des données Blob du stockage, Contributeur aux données en file d’attente du stockage et Contributeur de compte de stockage. Pour en savoir plus, consultez Connexion au stockage hôte avec une identité.

Propriétés courantes pour les connexions basées sur une identité

Une connexion basée sur une identité pour un service Azure accepte les propriétés courantes suivantes, où <CONNECTION_NAME_PREFIX> est la valeur de votre propriété connection dans la définition de déclencheur ou de liaison :

Propriété Modèle de variable d’environnement Description
Informations d’identification du jeton <CONNECTION_NAME_PREFIX>__credential Définit la façon dont un jeton doit être obtenu pour la connexion. Recommandé uniquement lors de la spécification d’une identité attribuée par l’utilisateur, quand elle doit être définie sur « managedidentity ». Valide uniquement si hébergé dans le service Azure Functions.
ID client <CONNECTION_NAME_PREFIX>__clientId Lorsque credential est a la valeur « managedidentity », cette propriété spécifie l’identité attribuée par l’utilisateur à utiliser lors de l’obtention d’un jeton. La propriété accepte un ID client correspondant à une identité attribuée par l’utilisateur affectée à l’application. Par défaut, l’identité affectée par le système de l’application est utilisée. Cette propriété est utilisée différemment dans des scénarios de développement local lorsque ne doit pas être défini.

Des options supplémentaires peuvent être prises en charge pour un type de connexion donné. Reportez-vous à la documentation du composant qui effectue la connexion.

Développement local avec connexions basées sur une identité

Notes

Le développement local avec des connexions basées sur l’identité nécessite des versions mises à jour d’Azure Functions Core Tools. Vous pouvez vérifier la version installée en exécutant func -v. Pour Functions v3, utilisez la version 3.0.3904 ou une version ultérieure. Pour Functions v4, utilisez la version 4.0.3904 ou une version ultérieure.

Lors d’une exécution locale, la configuration ci-dessus indique au runtime d’utiliser votre identité de développeur locale. La connexion tente d’obtenir un jeton à partir des emplacements suivants, dans l’ordre :

  • Un cache local partagé entre les applications Microsoft
  • Le contexte utilisateur actuel dans Visual Studio
  • Le contexte utilisateur actuel dans Visual Studio Code
  • Le contexte utilisateur actuel dans Azure CLI

Si aucune de ces options ne fonctionne, une erreur se produit.

Votre identité a peut-être déjà des attributions de rôles pour les ressources Azure utilisées pour le développement, mais ces rôles peuvent ne pas fournir l’accès aux données nécessaire. Les rôles de gestion comme Propriétaire ne sont pas suffisants. Revérifiez quelles autorisations sont nécessaires pour les connexions de chaque composant et vérifiez qu’elles vous sont affectées.

Dans certains cas, vous souhaiterez peut-être spécifier l’utilisation d’une identité différente. Pour la connexion, vous pouvez ajouter des propriétés de configuration qui pointent vers l’identité de substitution en fonction d’un ID client et d’un secret client pour un principal de service Azure Active Directory. Cette option de configuration n’est pas prise en charge quand elle est hébergée dans le service Azure Functions. Pour utiliser un ID et un secret sur votre ordinateur local, définissez la connexion avec les propriétés supplémentaires suivantes :

Propriété Modèle de variable d’environnement Description
ID client <CONNECTION_NAME_PREFIX>__tenantId ID du locataire Azure Active Directory (annuaire).
ID client <CONNECTION_NAME_PREFIX>__clientId ID client (application) d’une inscription d’application dans le locataire.
Clé secrète client <CONNECTION_NAME_PREFIX>__clientSecret Un secret client qui a été généré pour l’inscription de l’application.

Voici un exemple de propriétés local.settings.json obligatoires pour une connexion basée sur une identité à des objets blob Azure :

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
    "<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

Connexion à un stockage hôte avec une identité (préversion)

L’hôte Azure Functions utilise la connexion « AzureWebJobsStorage » pour les comportements de base comme la coordination de l’exécution unique de déclencheurs de minuteur et du stockage de clés d’application par défaut. Cela peut également être configuré pour tirer parti d’une identité.

Attention

Dans Functions, d’autres composants reposent sur « AzureWebJobsStorage » pour les comportements par défaut. Vous ne devez pas les déplacer vers une connexion basée sur une identité si vous utilisez des versions antérieures des extensions qui ne prennent pas en charge ce type de connexion, ce qui inclut les déclencheurs et les liaisons pour les objets blob Azure, Event Hubs et Durable Functions. De même, AzureWebJobsStorage est utilisé pour les artefacts de déploiement lors de l’utilisation de la génération côté serveur dans Linux, et si vous l’activez, vous devrez effectuer le déploiement via AzureWebJobsStorage.

De plus, certaines applications réutilisent « AzureWebJobsStorage » pour d’autres connexions de stockage dans leurs déclencheurs, liaisons et/ou code de fonction. Vérifiez que toutes les utilisations de « AzureWebJobsStorage » peuvent utiliser le format de connexion basée sur une identité avant de modifier cette connexion à partir d’une chaîne de connexion.

Pour utiliser une connexion basée sur une identité pour « AzureWebJobsStorage », configurez les paramètres d’application suivants :

Paramètre Description Valeur d'exemple
AzureWebJobsStorage__blobServiceUri URI de plan de données du service BLOB du compte de stockage, utilisant le schéma HTTPS. https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri URI de plan de données du service File d’attente du compte de stockage, utilisant le schéma HTTPS. https://<storage_account_name>.queue.core.windows.net
AzureWebJobsStorage__tableServiceUri URI de plan de données d’un service Table du compte de stockage, utilisant le schéma HTTPS. https://<storage_account_name>.table.core.windows.net

Il est également possible de définir des propriétés courantes pour les connexions basées sur une identité.

Si vous configurez « AzureWebJobsStorage » à l’aide d’un compte de stockage qui utilise le suffixe DNS et le nom de service par défaut pour Azure global, en respectant le format https://<accountName>.blob/queue/file/table.core.windows.net, vous pouvez à la place définir AzureWebJobsStorage__accountName sur le nom de votre compte de stockage. Les points de terminaison de chaque service de stockage sont déduits pour ce compte. Cela ne fonctionnera pas si le compte de stockage se trouve dans un cloud souverain ou s’il a un DNS personnalisé.

Paramètre Description Valeur d'exemple
AzureWebJobsStorage__accountName Nom de compte d’un compte de stockage, valide uniquement si le compte n’est pas dans un cloud souverain et n’a pas de DNS personnalisé. Cette syntaxe est unique à « AzureWebJobsStorage » et ne peut pas être utilisée pour d’autres connexions basées sur l’identité. <storage_account_name>

Vous devrez créer une attribution de rôle qui fournit l’accès au compte de stockage pour « AzureWebJobsStorage » au moment de l’exécution. Les rôles de gestion comme Propriétaire ne sont pas suffisants. Le rôle Propriétaire des données Blob du stockage couvre les besoins de base du stockage d’hôtes de fonctions - L’accès en lecture et en écriture aux objets blob et la capacité à créer des conteneurs sont nécessaires pour l’exécution. Plusieurs extensions utilisent cette connexion comme emplacement par défaut pour les blobs, les files d’attente et les tables, et ces utilisations peuvent ajouter des exigences, comme indiqué dans le tableau ci-dessous. Vous pouvez avoir besoin d’autorisations supplémentaires si vous utilisez « AzureWebJobsStorage » à d’autres fins.

Extension Rôles requis Explication
Aucune extension (hôte uniquement) Propriétaire des données Blob du stockage Utilisé pour la coordination générale, magasin de clés par défaut
Objets Blob Azure (déclencheur uniquement) La totalité de :
Contributeur de compte de stockage,
Propriétaire des données Blob du stockage,
Contributeur aux données en file d’attente du stockage
Le déclencheur blob utilise en interne les files d’attente Azure et écrit les reçus d’objets blob. Il utilise AzureWebJobsStorage, quelle que soit la connexion configurée pour le déclencheur.
Azure Event Hubs (déclencheur uniquement) (aucune modification par rapport à l’exigence par défaut)
Propriétaire des données Blob du stockage
Les points de contrôle sont conservés dans les objets blob à l’aide de la connexion AzureWebJobsStorage.
Déclencheur de minuteur (aucune modification par rapport à l’exigence par défaut)
Propriétaire des données Blob du stockage
Pour garantir une exécution par événement, les verrous sont pris avec les objets blob à l’aide de la connexion AzureWebJobsStorage.
Fonctions durables La totalité de :
Contributeur aux données Blob du stockage,
Contributeur aux données en file d’attente du stockage,
Contributeur aux données de table du stockage
Durable Functions utilise des objets blob, des files d’attente et des tables pour coordonner les fonctions d’activité et maintenir l’état de l’orchestration. Il utilise la connexion AzureWebJobsStorage pour tous ces paramètres par défaut, mais vous pouvez spécifier une autre connexion dans la configuration de l’extension de Durable Functions.

Problèmes liés aux rapports

Élément Description Lien
Runtime Hôte script, déclencheurs & liaisons, prise en charge linguistique Signaler un problème
Modèles Problèmes de code avec le modèle de création Signaler un problème
Portail Problème d'interface utilisateur ou d'expérience Signaler un problème

Étapes suivantes

Pour plus d’informations, consultez les ressources suivantes :