Migrace na verzi 4 programovacího modelu Node.js pro Azure Functions

Tento článek popisuje rozdíly mezi verzí 3 a verzí 4 programovacího modelu Node.js a o tom, jak upgradovat existující aplikaci v3. Pokud chcete vytvořit novou aplikaci v4 místo upgradu existující aplikace v3, prohlédni si kurz pro Visual Studio Code (VS Code) nebo Azure Functions Core Tools. Tento článek používá upozornění "tip" ke zvýraznění nejdůležitějších konkrétníchakcích

Verze 4 je navržená tak, aby vývojářům node.js poskytovala následující výhody:

• Poskytněte vývojářům Node.js známé a intuitivní prostředí.
• Zajištění flexibilní struktury souborů s podporou úplného přizpůsobení
• Přepnutí na přístup orientovaný na kód pro definování konfigurace funkcí

Důležité informace

• Programovací model Node.js by neměl být zaměňován s modulem runtime Azure Functions:
  • Programovací model: Definuje způsob vytváření kódu a je specifický pro JavaScript a TypeScript.
  • Modul runtime: Definuje základní chování služby Azure Functions a sdílí se napříč všemi jazyky.
• Verze programovacího modelu je přísně svázaná s verzí @azure/functions balíčku npm. Verze je nezávislá na modulu runtime. Modul runtime i programovací model používají číslo 4 jako nejnovější hlavní verzi, ale to je náhoda.
• Programovací modely v3 a v4 nemůžete kombinovat ve stejné aplikaci funkcí. Jakmile v aplikaci zaregistrujete jednu funkci v4, všechny funkce v3 zaregistrované v souborech function.json se ignorují.

Požadavky

Verze 4 programovacího modelu Node.js vyžaduje následující minimální verze:

• @azure/functions balíček npm v4.0.0
• Node.js v18+
• Modul runtime Azure Functions verze 4.25 nebo novější
• Azure Functions Core Tools v4.0.5382+ (pokud běží místně)

• @azure/functions balíček npm v4.0.0
• Node.js v18+
• TypeScript v4+
• Modul runtime Azure Functions verze 4.25 nebo novější
• Azure Functions Core Tools v4.0.5382+ (pokud běží místně)

Zahrnutí balíčku npm

V 4 @azure/functions obsahuje balíček npm primární zdrojový kód, který zálohuje programovací model Node.js. V předchozích verzích měl tento kód expedovaný přímo v Azure a balíček npm měl pouze typy TypeScript. Teď musíte tento balíček zahrnout pro aplikace TypeScript i JavaScript. Balíček můžete zahrnout pro existující aplikace v3, ale není to nutné.

Tip

Ujistěte se, že @azure/functions je balíček uvedený v oddílu dependencies (ne devDependencies) souboru package.json . Verzi 4 můžete nainstalovat pomocí následujícího příkazu:

npm install @azure/functions

Nastavení vstupního bodu aplikace

V 4 programovacího modelu můžete kód strukturovat, ale chcete. Jediné soubory, které potřebujete v kořenovém adresáři aplikace, jsou host.json a package.json.

V opačném případě definujete strukturu souborů nastavením main pole v souboru package.json . Pole můžete nastavit main na jeden soubor nebo více souborů pomocí vzoru globu. Následující tabulka ukazuje ukázkové hodnoty pro main pole:

Příklad	Popis
src/index.js	Zaregistrujte funkce z jednoho kořenového souboru.
src/functions/*.js	Zaregistrujte každou funkci z vlastního souboru.
src/{index.js,functions/*.js}	Kombinace, kde každou funkci zaregistrujete z vlastního souboru, ale stále máte kořenový soubor pro obecný kód na úrovni aplikace.

Příklad	Popis
dist/src/index.js	Zaregistrujte funkce z jednoho kořenového souboru.
dist/src/functions/*.js	Zaregistrujte každou funkci z vlastního souboru.
dist/src/{index.js,functions/*.js}	Kombinace, kde každou funkci zaregistrujete z vlastního souboru, ale stále máte kořenový soubor pro obecný kód na úrovni aplikace.

Tip

Ujistěte se, že v souboru package.json definujete main pole.

Přepnutí pořadí argumentů

Vstup triggeru místo kontextu vyvolání je teď prvním argumentem obslužné rutiny funkce. Kontext vyvolání, který je teď druhým argumentem, je ve verzi 4 zjednodušený a není tak povinný jako vstup triggeru. Pokud ho nepoužíváte, můžete ho nechat vypnutý.

Tip

Přepněte pořadí argumentů. Pokud například používáte trigger HTTP, přepněte (context, request) na buď (request, context) nebo jen (request) v případě, že nepoužíváte kontext.

Definování funkce v kódu

Tyto samostatné konfigurační soubory function.json už nemusíte vytvářet a udržovat. Funkce teď můžete plně definovat přímo v souborech TypeScriptu nebo JavaScriptu. Kromě toho má mnoho vlastností výchozí hodnoty, takže je nemusíte zadávat pokaždé.

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

Tip

Přesuňte konfiguraci ze souboru function.json do svého kódu. Typ triggeru odpovídá metodě objektu app v novém modelu. Pokud například použijete httpTrigger typ ve function.json, zavolejte app.http() do kódu funkci, abyste funkci zaregistrovali. Pokud používáte timerTrigger, zavolejte app.timer().

Kontrola využití kontextu

Ve verzi 4 je objekt zjednodušený, context aby se snížila duplicita a usnadnilo se psaní testů jednotek. Zjednodušili jsme například primární vstup a výstup, aby se k nim přistupovalo jenom jako k argumentu a návratové hodnotě obslužné rutiny funkce.

Už nemůžete získat přístup k primárnímu vstupu a výstupu objektu context , ale musíte stále přistupovat k sekundárním vstupům a výstupům objektu context . Další informace o sekundárních vstupech a výstupech najdete v příručce pro vývojáře Node.js.

Získání primárního vstupu jako argumentu

Primární vstup se také nazývá trigger a je jediným požadovaným vstupem nebo výstupem. Musíte mít jednu (a jenom jednu) aktivační událost.

v4

Verze 4 podporuje pouze jeden způsob získání vstupu triggeru jako prvního argumentu:

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

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

v3

Verze 3 podporuje několik způsobů získání vstupu triggeru:

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;

Tip

Ujistěte se, že vstup nepoužíváte context.req nebo context.bindings ho chcete získat.

Nastavení primárního výstupu jako návratové hodnoty

v4

Verze 4 podporuje pouze jeden způsob nastavení primárního výstupu prostřednictvím návratové hodnoty:

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

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

v3

Verze 3 podporuje několik způsobů nastavení primárního výstupu:

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

Tip

Ujistěte se, že vždy vracíte výstup v obslužné rutině funkce, místo abyste ho nastavili s objektem context .

Protokolování kontextu

V4 byly metody protokolování přesunuty do kořenového context objektu, jak je znázorněno v následujícím příkladu. Další informace o protokolování najdete v příručce pro vývojáře 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');

Vytvoření testovacího kontextu

Verze 3 nepodporuje vytvoření kontextu vyvolání mimo modul runtime Azure Functions, takže vytváření testů jednotek může být obtížné. Verze 4 umožňuje vytvořit instanci kontextu vyvolání, i když informace během testů nejsou podrobné, pokud je nepřidáte sami.

v4

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

v3

Není to možné.

Kontrola využití typů HTTP

Typy požadavků a odpovědí HTTP jsou teď podmnožinou standardu pro načtení. Už nejsou jedinečné pro Azure Functions.

Typy používají undici balíček v Node.js. Tento balíček se řídí standardem načítání a aktuálně je integrovaný do jádra Node.js.

HttpRequest

v4

• Text K textu se dostanete pomocí metody specifické pro typ, který chcete získat:

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

• Hlavička:

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

• Parametr dotazu:

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

v3

• Text K textu se dostanete několika způsoby, ale vrácený typ není vždy konzistentní:

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

• Záhlaví. Záhlaví můžete načíst několika způsoby:

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

• Parametr dotazu:

  const name = request.query.name;
  

HttpResponse

v4

• Stav:

  return { status: 200 };
  

• Text:

  body Tato vlastnost slouží k vrácení většiny typů, jako je například nebo stringBuffer:

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

  jsonBody Nejjednodušší způsob, jak vrátit odpověď JSON, použijte tuto vlastnost:

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

• Záhlaví. Záhlaví můžete nastavit dvěma způsoby podle toho, jestli používáte HttpResponse třídu nebo HttpResponseInit rozhraní:

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

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

v3

• Stav: Stav můžete nastavit několika způsoby:

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

• Text Tělo můžete nastavit několika způsoby a je stejné bez ohledu na typ těla (string, objekt BufferJSON atd.):

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

• Záhlaví. Záhlaví můžete nastavit několika způsoby:

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

Tip

Aktualizujte libovolnou logiku pomocí požadavku HTTP nebo typů odpovědí tak, aby odpovídaly novým metodám.

Tip

Aktualizujte libovolnou logiku pomocí požadavku HTTP nebo typů odpovědí tak, aby odpovídaly novým metodám. Měli byste získat chyby sestavení TypeScript, které vám pomůžou zjistit, jestli používáte staré metody.

Odstraňování potíží

Prohlédnou si průvodce odstraňováním potíží s Node.js.