Migrálás az Azure Functions Node.js programozási modelljének 4-es verziójára

Ez a cikk a Node.js programozási modell 3. és 4. verziója közötti különbségeket, valamint a meglévő v3-alkalmazások frissítésének módját ismerteti. Ha egy meglévő v3-alkalmazás frissítése helyett új v4-alkalmazást szeretne létrehozni, tekintse meg a Visual Studio Code (VS Code) vagy az Azure Functions Core Tools oktatóanyagát. Ez a cikk "tipp" riasztásokkal emeli ki az alkalmazás frissítése során végrehajtandó legfontosabb konkrét műveleteket.

A 4-es verzió a Node.js fejlesztői számára a következő előnyöket biztosítja:

• Ismerős és intuitív élményt nyújt a Node.js fejlesztőinek.
• A fájlstruktúra rugalmassá tétele a teljes testreszabás támogatásával.
• Váltson kódközpontú megközelítésre a függvénykonfiguráció definiálásához.

Megfontolások

• A Node.js programozási modellt nem szabad összekeverni az Azure Functions-futtatókörnyezettel:
  • Programozási modell: Meghatározza a kód készítésének módját, és a JavaScriptre és a TypeScriptre jellemző.
  • Futtatókörnyezet: Meghatározza az Azure Functions mögöttes viselkedését, és minden nyelven meg van osztva.
• A programozási modell verziója szigorúan az npm-csomag verziójához @azure/functions van kötve. A futtatókörnyezettől függetlenül verziószámozott. A futtatókörnyezet és a programozási modell is a 4-es számot használja a legújabb főverzióként, de ez véletlen.
• A v3- és v4-programozási modellek nem keverhetők ugyanabban a függvényalkalmazásban. Amint regisztrál egy v4-függvényt az alkalmazásban, a függvény.json fájlokban regisztrált v3-függvények figyelmen kívül lesznek hagyva.

Követelmények

A Node.js programozási modell 4. verziójához a következő minimális verziók szükségesek:

• @azure/functions npm-csomag v4.0.0
• Node.js v18+
• Azure Functions Runtime v4.25+
• Azure Functions Core Tools v4.0.5382+ (helyi futtatás esetén)

• @azure/functions npm-csomag v4.0.0
• Node.js v18+
• TypeScript v4+
• Azure Functions Runtime v4.25+
• Azure Functions Core Tools v4.0.5382+ (helyi futtatás esetén)

Az npm-csomag belefoglalása

A v4-ben az @azure/functions npm-csomag tartalmazza a Node.js programozási modellt alátámasztó elsődleges forráskódot. A korábbi verziókban a közvetlenül az Azure-ban szállított kód és az npm-csomag csak TypeScript-típusok voltak. Ezt a csomagot mostantól TypeScript- és JavaScript-alkalmazásokhoz is tartalmaznia kell. A csomagot meglévő v3-alkalmazásokhoz is felveheti, de nem szükséges.

Tipp.

Győződjön meg arról, hogy a @azure/functions csomag szerepel a dependencies package.json fájl (nem devDependencies) szakaszában. A v4-et a következő paranccsal telepítheti:

npm install @azure/functions

Az alkalmazás belépési pontának beállítása

A programozási modell v4-ben tetszés szerint strukturálhatja a kódot. Az alkalmazás gyökerében csak a host.json és a package.json fájlra van szüksége.

Ellenkező esetben a package.json fájl mezőjének beállításával definiálhatja a main fájlstruktúrát. A mezőt egy gömbmintával egyetlen fájlra vagy több fájlra állíthatja main be. Az alábbi táblázat a mezőhöz tartozó main példaértékeket mutatja be:

Példa	Leírás
src/index.js	Függvények regisztrálása egyetlen gyökérfájlból.
src/functions/*.js	Regisztrálja az egyes függvényeket a saját fájljából.
src/{index.js,functions/*.js}	Olyan kombináció, amelyben az egyes függvényeket a saját fájljából regisztrálja, de az általános alkalmazásszintű kódhoz továbbra is rendelkezik gyökérfájllal.

Példa	Leírás
dist/src/index.js	Függvények regisztrálása egyetlen gyökérfájlból.
dist/src/functions/*.js	Regisztrálja az egyes függvényeket a saját fájljából.
dist/src/{index.js,functions/*.js}	Olyan kombináció, amelyben az egyes függvényeket a saját fájljából regisztrálja, de az általános alkalmazásszintű kódhoz továbbra is rendelkezik gyökérfájllal.

Tipp.

Ügyeljen arra, hogy a package.json fájlban adjon meg egy main mezőt.

Az argumentumok sorrendjének váltása

Az eseményindító bemenete a meghívási környezet helyett most a függvénykezelő első argumentuma. A meghívási környezet, amely most a második argumentum, a v4-ben egyszerűsítve van, és nem olyan szükséges, mint az eseményindító bemenete. Ha nem használja, kikapcsolhatja.

Tipp.

Váltsa át az argumentumok sorrendjét. Ha például HTTP-eseményindítót használ, váltson (context, request) vagy (request, context) csak (request) akkor, ha nem használja a környezetet.

Függvény definiálása kódban

Ezeket a különálló function.json konfigurációs fájlokat már nem kell létrehoznia és karbantartania. Mostantól teljes mértékben definiálhatja a függvényeket közvetlenül a TypeScript- vagy JavaScript-fájlokban. Emellett számos tulajdonságnak van alapértelmezett értéke, így nem kell minden alkalommal megadnia őket.

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"
}

Tipp.

Helyezze át a konfigurációt a function.json fájlból a kódba. Az eseményindító típusa megfelel az új modell objektumának app egy metódusának. Ha például a function.json típust httpTrigger használja, hívja meg app.http() a kódban a függvény regisztrálását. Ha használja timerTrigger, hívja meg a következőt app.timer():

A környezet használatának áttekintése

A v4-ben az objektum egyszerűbbé teszi a context duplikációt, és egyszerűbbé teszi az egységtesztek írását. Leegyszerűsítettük például az elsődleges bemenetet és kimenetet, hogy csak a függvénykezelő argumentumaként és visszatérési értékeként legyenek elérhetők.

Az objektum elsődleges bemenete és kimenete context már nem érhető el, de továbbra is hozzá kell férnie az context objektum másodlagos bemeneteihez és kimeneteihez. A másodlagos bemenetekről és kimenetekről további információt a Node.js fejlesztői útmutatójában talál.

Az elsődleges bemenet lekérése argumentumként

Az elsődleges bemenetet eseményindítónak is nevezik, és ez az egyetlen szükséges bemenet vagy kimenet. Egy (és csak egy) eseményindítóval kell rendelkeznie.

v4

A 4-es verzió csak egyféleképpen támogatja az eseményindító bemenetének lekérését az első argumentumként:

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

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

v3

A 3. verzió számos módon támogatja az eseményindító bemenetének lekérését:

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;

Tipp.

Győződjön meg arról, hogy nem használja context.req a bemenetet, vagy context.bindings nem szeretné lekérni a bemenetet.

Az elsődleges kimenet beállítása visszatérési értékként

v4

A 4-es verzió csak egy módon támogatja az elsődleges kimenet beállítását a visszatérési értéken keresztül:

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

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

v3

A 3. verzió számos módon támogatja az elsődleges kimenet beállítását:

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

Tipp.

Győződjön meg arról, hogy mindig a függvénykezelőben adja vissza a kimenetet, ahelyett, hogy az context objektummal állítja be.

Környezet naplózása

A v4-ben a naplózási metódusok át lettek helyezve a gyökérobjektumba context az alábbi példában látható módon. A naplózással kapcsolatos további információkért tekintse meg a Node.js fejlesztői útmutatót.

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

Tesztkörnyezet létrehozása

A 3. verzió nem támogatja a meghívási környezet létrehozását az Azure Functions-futtatókörnyezeten kívül, így az egységtesztek készítése nehézkes lehet. A 4-es verzió lehetővé teszi a meghívási környezet egy példányának létrehozását, bár a tesztek során lévő információk csak akkor lesznek részletesek, ha ön adja hozzá.

v4

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

v3

Nem lehetséges.

HTTP-típusok használatának áttekintése

A HTTP-kérés- és választípusok mostantól a beolvasási szabvány részhalmazai. Már nem egyediek az Azure Functionsben.

A típusok a Node.js-ben használják a undici csomagot. Ez a csomag a beolvasási szabványt követi, és jelenleg a Node.js Core-ba van integrálva .

HttpRequest

v4

• Test. A törzset a kapni kívánt típusnak megfelelő metódussal érheti el:

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

• Fejléc:

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

• Lekérdezési paraméter:

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

v3

• Test. A törzs többféleképpen is elérhető, de a visszaadott típus nem mindig konzisztens:

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

• Fejléc. Az élőfejet többféleképpen is lekérheti:

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

• Lekérdezési paraméter:

  const name = request.query.name;
  

HttpResponse

v4

• Állapot:

  return { status: 200 };
  

• Törzs:

  A tulajdonság használatával adja vissza a body legtöbb típust, például a string vagy Buffer:

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

  jsonBody A JSON-válasz visszaadásának legegyszerűbb módja a tulajdonság használata:

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

• Fejléc. A fejléc kétféleképpen állítható be attól függően, hogy az osztályt vagy a HttpResponseHttpResponseInit felületet használja-e:

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

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

v3

• Állapot. Az állapotot többféleképpen is beállíthatja:

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

• Test. A törzset többféleképpen is beállíthatja, és a törzs típusátólstring (, BufferJSON-objektumtól stb.) függetlenül ugyanaz:

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

• Fejléc. Az élőfejet többféleképpen is beállíthatja:

  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' }
  };
  

Tipp.

Frissítse a logikát a HTTP-kérések vagy választípusok használatával, hogy megfeleljenek az új módszereknek.

Tipp.

Frissítse a logikát a HTTP-kérések vagy választípusok használatával, hogy megfeleljenek az új módszereknek. TypeScript buildelési hibákat kell kapnia, amelyek segítenek azonosítani, hogy régi metódusokat használ-e.

Hibaelhárítás

Tekintse meg a Node.js hibaelhárítási útmutatót.