Migreren naar versie 4 van het Node.js programmeermodel voor Azure Functions

Dit artikel bespreekt de verschillen tussen versie 3 en versie 4 van het Node.js programmeermodel en hoe je een bestaande v3-app kunt upgraden. Als u een nieuwe v4-app wilt maken in plaats van een bestaande v3-app te upgraden, raadpleegt u de zelfstudie voor Visual Studio Code (VS Code) of Azure Functions Core Tools. In dit artikel worden 'tip'-waarschuwingen gebruikt om de belangrijkste concrete acties te markeren die u moet ondernemen om uw app te upgraden. Versie 4 is ontworpen om Node.js ontwikkelaars de volgende voordelen te bieden:

  • Bied een vertrouwde en intuïtieve ervaring aan Node.js ontwikkelaars.
  • Maak de bestandsstructuur flexibel met ondersteuning voor volledige aanpassing.
  • Schakel over naar een codegerichte benadering voor het definiëren van functieconfiguratie.

Overwegingen

  • Het Node.js programmeermodel mag niet worden verward met de Azure Functions-runtime:
    • Programmeermodel: Definieert hoe u uw code ontwerpt en specifiek is voor JavaScript en TypeScript.
    • Runtime: Definieert het onderliggende gedrag van Azure Functions en wordt gedeeld in alle talen.
  • De versie van het programmeermodel is strikt gekoppeld aan de versie van het @azure/functions npm-pakket. Het heeft een eigen versiebeheer, los van de runtime. Zowel de runtime als het programmeermodel gebruiken het getal 4 als hun meest recente hoofdversie, maar dat is toeval.
  • U kunt de v3- en v4-programmeermodellen niet combineren in dezelfde functie-app. Zodra u één v4-functie in uw app registreert, worden alle v3-functies die zijn geregistreerd in function.json bestanden genegeerd.

Vereisten

Versie 4 van het Node.js programmeermodel vereist de volgende minimale versies:

Het npm-pakket opnemen

In v4 bevat het @azure/functions npm-pakket de primaire broncode die ten grondslag ligt aan het Node.js-programmeermodel. In eerdere versies werd die code rechtstreeks in Azure meegeleverd en bevatte het npm-pakket alleen de TypeScript-typen. U moet dit pakket nu opnemen voor zowel TypeScript- als JavaScript-apps. U kunt het pakket voor bestaande v3-apps opnemen, maar dit is niet vereist.

Tip

Zorg ervoor dat het @azure/functions pakket wordt vermeld in de dependencies sectie (niet devDependencies) van uw package.json bestand. U kunt v4 installeren met behulp van de volgende opdracht:

npm install @azure/functions

Uw app-invoerpunt instellen

In v4 van het programmeermodel kunt u de code naar wens structuren. De enige bestanden die u nodig hebt in de hoofdmap van uw app, zijn host.json en package.json.

Anders definieert u de bestandsstructuur door het veld in uw mainpackage.json-bestand in te stellen. U kunt het main veld instellen op één bestand of meerdere bestanden met behulp van een glob-patroon. In de volgende tabel ziet u voorbeeldwaarden voor het main veld:

Voorbeeld Beschrijving
src/index.js Registreer functies uit één hoofdbestand.
src/functions/*.js Registreer elke functie uit een eigen bestand.
src/{index.js,functions/*.js} Een combinatie waarbij u elke functie registreert vanuit een eigen bestand, maar u hebt nog steeds een hoofdbestand voor algemene code op app-niveau.
Voorbeeld Beschrijving
dist/src/index.js Registreer functies uit één hoofdbestand.
dist/src/functions/*.js Registreer elke functie uit een eigen bestand.
dist/src/{index.js,functions/*.js} Een combinatie waarbij u elke functie registreert vanuit een eigen bestand, maar u hebt nog steeds een hoofdbestand voor algemene code op app-niveau.

Tip

Zorg ervoor dat u een main veld in uw package.json-bestand definieert.

De volgorde van argumenten wijzigen

De triggerinvoer is nu het eerste argument voor de functie-handler in plaats van de aanroepcontext. De aanroepcontext, nu het tweede argument, is vereenvoudigd in v4 en is niet zo vereist als de triggerinvoer. U kunt het uitschakelen als u deze niet gebruikt.

Tip

De volgorde van de argumenten wijzigen. Als u bijvoorbeeld een HTTP-trigger gebruikt, wijzigt u (context, request) in (request, context) of gewoon in (request) als u de context niet gebruikt.

Uw functie definiëren in code

U hoeft deze afzonderlijke function.json configuratiebestanden niet meer te maken en te onderhouden. U kunt nu uw functies rechtstreeks definiëren in uw TypeScript- of JavaScript-bestanden. Bovendien hebben veel eigenschappen nu standaardwaarden, zodat u ze niet elke keer hoeft op te geven.

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}!` };
    },
});

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,
});

Tip

Verplaats de configuratie van uw function.json bestand naar uw code. Het type trigger komt overeen met een methode op het app object in het nieuwe model. Als u bijvoorbeeld een httpTrigger-type in function.json gebruikt, roept u app.http() aan in uw code om de functie te registreren. Als u timerTrigger gebruikt, roept u app.timer() aan.

Uw gebruik van context controleren

In v4 is het context object vereenvoudigd om duplicatie te verminderen en schrijfeenheidtests eenvoudiger te maken. We hebben bijvoorbeeld de primaire invoer en uitvoer gestroomlijnd, zodat deze alleen via het argument en de retourwaarde van uw functiehandler worden benaderd.

U hebt geen toegang meer tot de primaire invoer en uitvoer van het context object, maar u moet nog steeds toegang krijgen tot secundaire invoer en uitvoer op het context object. Zie de Node.js ontwikkelaarshandleiding voor meer informatie over secundaire invoer en uitvoer.

Haal de primaire invoer op als argument

De primaire invoer wordt ook wel de trigger genoemd en is de enige vereiste invoer of uitvoer. U moet één (en slechts één) trigger hebben.

Versie 4 ondersteunt slechts één manier om de triggerinvoer op te halen, als eerste argument:

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

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

Tip

Zorg ervoor dat u context.req of context.bindings niet gebruikt om de invoer op te halen.

De primaire uitvoer instellen als uw retourwaarde

Versie 4 ondersteunt slechts één manier om de primaire uitvoer in te stellen via de retourwaarde:

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

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

Tip

Zorg ervoor dat u altijd de uitvoer in de functie-handler retourneert in plaats van deze in te stellen met het context object.

Contextregistratie

In v4 zijn logboekregistratiemethoden verplaatst naar het hoofdobject context , zoals wordt weergegeven in het volgende voorbeeld. Zie de Node.js ontwikkelaarshandleiding voor meer informatie over logboekregistratie.

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

Een testcontext maken

Versie 3 biedt geen ondersteuning voor het maken van een aanroepcontext buiten de Azure Functions-runtime, zodat het ontwerpen van eenheidstests lastig kan zijn. Met versie 4 kunt u een exemplaar van de aanroepcontext maken, hoewel de informatie tijdens tests niet gedetailleerd is, tenzij u deze zelf toevoegt.

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

Uw gebruik van HTTP-typen controleren

De HTTP-aanvraag- en antwoordtypen zijn nu een subset van de ophaalstandaard. Ze zijn niet meer uniek voor Azure Functions.

De typen gebruiken het undici pakket in Node.js. Dit pakket volgt de ophaalstandaard en wordt momenteel geïntegreerd in Node.js kern.

HttpRequest

  • Hoofdtekst. U kunt de hoofdtekst openen met behulp van een methode die specifiek is voor het type dat u wilt ontvangen:

    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();

  • Header:

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

  • Queryparameter:

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

HttpResponse

  • Status:

    return { status: 200 };

  • Hoofdtekst:

    Gebruik de body-eigenschap om de meeste typen te retourneren, zoals een string of Buffer:

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

    Gebruik de jsonBody eigenschap voor de eenvoudigste manier om een JSON-antwoord te retourneren:

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

  • Koptekst. U kunt de header op twee manieren instellen, afhankelijk van of u de HttpResponse klasse of de HttpResponseInit interface gebruikt:

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

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

Tip

Werk alle logica bij met behulp van de HTTP-aanvraag- of antwoordtypen zodat deze overeenkomen met de nieuwe methoden.

Tip

Werk alle logica bij met behulp van de HTTP-aanvraag- of antwoordtypen zodat deze overeenkomen met de nieuwe methoden. U zou TypeScript-buildfouten moeten krijgen, zodat u kunt zien of u oude methoden gebruikt.

Problemen oplossen

Raadpleeg de handleiding voor het oplossen van problemen met Node.js.

  • Last updated on