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

Cikk
12/18/2024

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ó úgy lett kialakítva, hogy Node.js fejlesztők számára a következő előnyöket nyújtsuk:

Biztosítson ismerős és intuitív élményt Node.js fejlesztőknek.
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 function.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 az elsődleges forráskódot, amely a Node.js programozási modellt tartalmazza. 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 (nemdevDependencies) 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 host.json és package.json fájlokra van szüksége.

Ellenkező esetben a fájlstruktúrát a package.json fájl mezőjének beállításával main határozhatja meg. 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 fenntartania. 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.

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

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

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

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 egy típust httpTrigger használ a function.json, hívja meg app.http() a kódot a függvény regisztrálásához. 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. További információ a másodlagos bemenetekről és kimenetekről: Node.js fejlesztői útmutató.

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.

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;

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

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

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.

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

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á.

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

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 csomagot Node.js undici használják. Ez a csomag a beolvasási szabványt követi, és jelenleg Node.js magba van integrálva .

HttpRequest

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

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

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

Á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.

Megosztás a következőn keresztül:

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

Megfontolások

Követelmények

Az npm-csomag belefoglalása

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

Az argumentumok sorrendjének váltása

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

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

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

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

Környezet naplózása

Tesztkörnyezet létrehozása

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

HttpRequest

HttpResponse

Hibaelhárítás

Visszajelzés

További források