Migrer vers la version 4 du modèle de programmation Node.js pour Azure Functions

Cet article décrit les différences entre la version 3 et la version 4 du modèle de programmation Node.js et explique comment mettre à niveau une application v3 existante. Si vous souhaitez créer une application v4 au lieu de mettre à niveau une application v3 existante, consultez le tutoriel pour Visual Studio Code (VS Code) ou Azure Functions Core Tools. Cet article utilise les alertes « conseil » pour mettre en évidence les actions concrètes les plus importantes que vous devez entreprendre pour mettre à niveau votre application.

La version 4 est conçue pour offrir aux développeurs Node.js les avantages suivants :

• Fournir une expérience familière et intuitive aux développeurs Node.js.
• Rendre la structure de fichiers flexible avec prise en charge de la personnalisation complète.
• Passer à une approche centrée sur le code pour définir la configuration des fonctions.

Considérations

• Le modèle de programmation Node.js ne doit pas être confondu avec le runtime Azure Functions :
  • Modèle de programmation : définit la façon dont vous créez votre code et est spécifique à JavaScript et TypeScript.
  • Runtime : définit le comportement sous-jacent de Azure Functions et est partagé entre tous les langages.
• La version du modèle de programmation est strictement liée à celle du package npm @azure/functions. Cela est versionné indépendamment du runtime. Le runtime et le modèle de programmation utilisent tous les deux le nombre 4 comme dernière version majeure, mais cela est une coïncidence.
• Vous ne pouvez pas combiner les modèles de programmation v3 et v4 dans la même application de fonction. Dès que vous inscrivez une fonction v4 dans votre application, toutes les fonctions v3 inscrites dans des fichiers function.json sont ignorées.

Configuration requise

La version 4 du modèle de programmation Node.js nécessite les versions minimales suivantes :

• @azure/functions package npm v4.0.0
• Node.js v18+
• Azure Functions Runtime v4.25 ou ultérieure
• Azure Functions Core Tools v4.0.5382 ou ultérieure (en cas d’exécution locale)

• @azure/functions package npm v4.0.0
• Node.js v18+
• TypeScript v4+
• Azure Functions Runtime v4.25 ou ultérieure
• Azure Functions Core Tools v4.0.5382 ou ultérieure (en cas d’exécution locale)

Inclure le package npm

Dans la version 4, le package npm @azure/functions contient le code source principal qui sauvegarde le modèle de programmation Node.js. Dans les versions précédentes, ce code était fourni directement dans Azure et le package npm avait uniquement les types TypeScript. Vous devez désormais inclure ce package pour les applications TypeScript et JavaScript. Vous pouvez inclure le package pour les applications v3 existantes, mais ce n’est pas obligatoire.

Conseil

Assurez-vous que le package @azure/functions figure dans la section dependencies (et non dans la section devDependencies) de votre fichier package.json. Vous pouvez installer v4 à l’aide de la commande suivante :

npm install @azure/functions

Définir le point d’entrée de votre application

Dans la version 4 du modèle de programmation, vous pouvez structurer votre code comme vous le souhaitez. Les seuls fichiers dont vous avez besoin à la racine de votre application sont host.json et package.json.

Sinon, vous définissez la structure de fichiers en définissant le champ main dans votre fichier package.json. Vous pouvez définir le champ main sur un fichier unique ou plusieurs fichiers à l’aide d’un modèle Glob. Le tableau suivant présente des exemples de valeurs pour le main champ :

Exemple	Description
src/index.js	Inscrivez des fonctions à partir d’un seul fichier racine.
src/functions/*.js	Inscrivez chaque fonction à partir de son propre fichier.
src/{index.js,functions/*.js}	Combinaison dans laquelle vous inscrivez chaque fonction à partir de son propre fichier, mais vous disposez toujours d’un fichier racine pour le code général au niveau de l’application.

Exemple	Description
dist/src/index.js	Inscrivez des fonctions à partir d’un seul fichier racine.
dist/src/functions/*.js	Inscrivez chaque fonction à partir de son propre fichier.
dist/src/{index.js,functions/*.js}	Combinaison dans laquelle vous inscrivez chaque fonction à partir de son propre fichier, mais vous disposez toujours d’un fichier racine pour le code général au niveau de l’application.

Conseil

Veillez à définir un champ main dans votre fichier package.json.

Changer l’ordre des arguments

L’entrée du déclencheur est désormais le premier argument de votre gestionnaire de fonction au lieu du contexte d’appel. Le contexte d’appel, qui est désormais le deuxième argument, est simplifié dans la version 4 et n’est pas aussi nécessaire que l’entrée du déclencheur. Vous pouvez le laisser désactivé si vous ne l’utilisez pas.

Conseil

Changez l’ordre de vos arguments. Par exemple, si vous utilisez un déclencheur HTTP, basculez (context, request) vers (request, context) ou simplement (request) si vous n’utilisez pas le contexte.

Définir votre fonction dans le code

Vous n’avez plus besoin de créer et de gérer ces fichiers de configuration function.json distincts. Vous pouvez maintenant définir entièrement vos fonctions directement dans vos fichiers TypeScript ou JavaScript. En outre, de nombreuses propriétés ont désormais une valeur par défaut afin que vous n’ayez pas à les spécifier à chaque fois.

v4

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || (await request.text()) || 'world';

        return { body: `Hello, ${name}!` };
    },
});

v3

module.exports = async function (context, req) {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

v4

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || (await request.text()) || 'world';

    return { body: `Hello, ${name}!` };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: httpTrigger1,
});

v3

import { AzureFunction, Context, HttpRequest } from "@azure/functions"

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = req.query.name || req.body || 'world';

    context.res = {
        body: `Hello, ${name}!`
    };
};

export default httpTrigger;

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ],
  "scriptFile": "../dist/HttpTrigger1/index.js"
}

Conseil

Déplacez la configuration de votre fichier function.json vers votre code. Le type du déclencheur correspond à une méthode sur l’objet app dans le nouveau modèle. Par exemple, si vous utilisez un type httpTrigger dans function.json, appelez app.http() dans votre code pour inscrire la fonction. Si vous utilisez timerTrigger, appelez app.timer().

Passer en revue votre utilisation du contexte

Dans la version 4, l’objet context est simplifié pour réduire la duplication et faciliter l’écriture de tests unitaires. Par exemple, nous avons simplifié l’entrée et la sortie primaires afin qu’elles soient accessibles uniquement en tant qu’argument et valeur de retour de votre gestionnaire de fonction.

Vous ne pouvez plus accéder à l’entrée et à la sortie primaires sur l’objet context, mais vous devez toujours accéder aux entrées et sorties secondaires sur l’objet context. Pour plus d’informations sur les entrées et sorties secondaires, consultez le Guide du développeurNode.js.

Obtenir l’entrée principale en tant qu’argument

L’entrée primaire est également appelée déclencheur et est la seule entrée ou sortie requise. Vous devez avoir un (et un seul) déclencheur.

v4

La version 4 ne prend en charge qu’une seule façon d’obtenir l’entrée du déclencheur, comme premier argument :

async function httpTrigger1(request, context) {
  const onlyOption = request;

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
  const onlyOption = request;

v3

La version 3 prend en charge plusieurs façons d’obtenir l’entrée du déclencheur :

async function httpTrigger1(context, request) {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

async function httpTrigger1(context: Context, req: HttpRequest): Promise<void> {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

Conseil

Vérifiez que vous n’utilisez pas context.req ou context.bindings pour obtenir l’entrée.

Définir la sortie primaire comme valeur de retour

v4

La version 4 ne prend en charge qu’une seule façon de définir la sortie primaire, via la valeur de retour :

return { 
  body: `Hello, ${name}!` 
};

async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    // ...
    return { 
      body: `Hello, ${name}!` 
    };
}

v3

La version 3 prend en charge plusieurs façons de définir la sortie primaire :

// Option 1
context.res = {
    body: `Hello, ${name}!`
};
// Option 2, but you can't use this option with any async code:
context.done(null, {
    body: `Hello, ${name}!`
});
// Option 3, but you can't use this option with any async code:
context.res.send(`Hello, ${name}!`);
// Option 4, if "name" in function.json is "res":
context.bindings.res = {
    body: `Hello, ${name}!`
}
// Option 5, if "name" in function.json is "$return":
return {
    body: `Hello, ${name}!`
};

Conseil

Assurez-vous que vous retournez toujours la sortie dans votre gestionnaire de fonction, au lieu de la définir avec l’objet context.

Journalisation du contexte

Dans v4, les méthodes de journalisation ont été déplacées vers l’objet racine context , comme illustré dans l’exemple suivant. Pour plus d’informations sur la journalisation, consultez le guide du développeur Node.js.

v4

context.log('This is an info log');
context.error('This is an error');
context.warn('This is an error');

v3

context.log('This is an info log');
context.log.error('This is an error');
context.log.warn('This is an error');

Créer un contexte de test

La version 3 ne prend pas en charge la création d’un contexte d’appel en dehors du runtime Azure Functions, de sorte que la création de tests unitaires peut être difficile. La version 4 vous permet de créer une instance du contexte d’appel, bien que les informations pendant les tests ne soient pas détaillées, sauf si vous les ajoutez vous-même.

v4

const testInvocationContext = new InvocationContext({
  functionName: 'testFunctionName',
  invocationId: 'testInvocationId'
});

v3

Impossible.

Passer en revue votre utilisation des types HTTP

Les types de requête et de réponse HTTP sont désormais un sous-ensemble de la norme de récupération. Ils ne sont plus propres à Azure Functions.

Les types utilisent le package undici dans Node.js. Ce package suit la norme de récupération et est en cours d’intégration dans Node.js core.

HttpRequest

v4

• Corps. Vous pouvez accéder au corps à l’aide d’une méthode spécifique au type que vous souhaitez recevoir :

  const body = await request.text();
  const body = await request.json();
  const body = await request.formData();
  const body = await request.arrayBuffer();
  const body = await request.blob();
  

• En-tête:

  const header = request.headers.get('content-type');
  

• Paramètre de requête :

  const name = request.query.get('name');
  

v3

• Corps. Vous pouvez accéder au corps de plusieurs façons, mais le type retourné n’est pas toujours cohérent :

  // returns a string, object, or Buffer
  const body = request.body;
  // returns a string
  const body = request.rawBody;
  // returns a Buffer
  const body = request.bufferBody;
  // returns an object representing a form
  const body = await request.parseFormBody();
  

• En-tête. Vous pouvez récupérer un en-tête de plusieurs façons :

  const header = request.get('content-type');
  const header = request.headers.get('content-type');
  const header = context.bindingData.headers['content-type'];
  

• Paramètre de requête :

  const name = request.query.name;
  

HttpResponse

v4

• État :

  return { status: 200 };
  

• Corps :

  Utilisez la propriété pour renvoyer la body plupart des types comme a string ou Buffer:

  return { body: "Hello, world!" };
  

  Utilisez la jsonBody propriété pour le moyen le plus simple de retourner une réponse JSON :

  return { jsonBody: { hello: "world" } };
  

• En-tête. Vous pouvez définir l’en-tête de deux manières, selon que vous utilisez la classe HttpResponse ou l’interface HttpResponseInit :

  const response = new HttpResponse();
  response.headers.set('content-type', 'application/json');
  return response;
  

  return {
    headers: { 'content-type': 'application/json' }
  };
  

v3

• Status. Vous pouvez définir un état de plusieurs façons :

  context.res.status(200);
  context.res = { status: 200}
  context.res = { statusCode: 200 };
  return { status: 200};
  return { statusCode: 200 };
  

• Corps. Vous pouvez définir un corps de plusieurs façons et il est le même quel que soit le type de corps (string, Buffer, objet JSON, etc.) :

  context.res.send("Hello, world!");
  context.res.end("Hello, world!");
  context.res = { body: "Hello, world!" };
  return { body: "Hello, world!" };
  

• En-tête. Vous pouvez définir un en-tête de plusieurs façons :

  response.set('content-type', 'application/json');
  response.setHeader('content-type', 'application/json');
  response.headers = { 'content-type': 'application/json' }
  context.res = {
    headers: { 'content-type': 'application/json' }
  };
  return {
    headers: { 'content-type': 'application/json' }
  };
  

Conseil

Mettez à jour n’importe quelle logique à l’aide des types de requête ou de réponse HTTP pour qu’elle corresponde aux nouvelles méthodes.

Conseil

Mettez à jour n’importe quelle logique à l’aide des types de requête ou de réponse HTTP pour qu’elle corresponde aux nouvelles méthodes. Vous devez obtenir des erreurs de build TypeScript pour vous aider à identifier si vous utilisez d’anciennes méthodes.

Résolution des problèmes

Consultez le Guide de résolution des problèmes Node.js.