Migrar para a versão 4 do modelo de programação Node.js para o Azure Functions

Artigo
01/19/2024

Este artigo discute as diferenças entre a versão 3 e a versão 4 do modelo de programação Node.js e como atualizar um aplicativo v3 existente. Se você quiser criar um novo aplicativo v4 em vez de atualizar um aplicativo v3 existente, consulte o tutorial para Visual Studio Code (VS Code) ou Azure Functions Core Tools. Este artigo usa alertas de "dica" para destacar as ações concretas mais importantes que você deve tomar para atualizar seu aplicativo.

A versão 4 foi projetada para fornecer aos desenvolvedores .js nó os seguintes benefícios:

Forneça uma experiência familiar e intuitiva aos desenvolvedores .js Node.
Torne a estrutura de arquivos flexível com suporte para personalização completa.
Mude para uma abordagem centrada em código para definir a configuração da função.

Considerações

O modelo de programação Node.js não deve ser confundido com o tempo de execução do Azure Functions:
- Modelo de programação: define como você cria seu código e é específico para JavaScript e TypeScript.
- Tempo de execução: define o comportamento subjacente do Azure Functions e é compartilhado em todos os idiomas.
A versão do modelo de programação está estritamente ligada à versão do @azure/functions pacote npm. É versionado independentemente do tempo de execução. Tanto o tempo de execução quanto o modelo de programação usam o número 4 como sua última versão principal, mas isso é uma coincidência.
Não é possível misturar os modelos de programação v3 e v4 no mesmo aplicativo de função. Assim que você registrar uma função v4 em seu aplicativo, todas as funções v3 registradas em arquivos function.json serão ignoradas.

Requisitos

A versão 4 do modelo de programação Node.js requer as seguintes versões mínimas:

@azure/functions Pacote npm v4.0.0
Nó.js v18+
Azure Functions Runtime v4.25+
Azure Functions Core Tools v4.0.5382+ (se executado localmente)

@azure/functions Pacote npm v4.0.0
Nó.js v18+
TypeScript v4+
Azure Functions Runtime v4.25+
Azure Functions Core Tools v4.0.5382+ (se executado localmente)

Incluir o pacote npm

Na v4, o pacote npm contém o código-fonte primário que apoia o @azure/functions modelo de programação Node.js. Em versões anteriores, esse código era enviado diretamente no Azure e o pacote npm tinha apenas os tipos TypeScript. Agora você precisa incluir este pacote para aplicativos TypeScript e JavaScript. Você pode incluir o pacote para aplicativos v3 existentes, mas ele não é necessário.

Gorjeta

Verifique se o @azure/functions pacote está listado dependencies na seção (não devDependencies) do seu arquivo package.json . Você pode instalar a v4 usando o seguinte comando:

npm install @azure/functions

Definir o ponto de entrada do aplicativo

Na v4 do modelo de programação, você pode estruturar seu código como quiser. Os únicos arquivos que você precisa na raiz do seu aplicativo são host.json e package.json.

Caso contrário, você define a estrutura do arquivo definindo o main campo no arquivo package.json . Você pode definir o main campo como um único arquivo ou vários arquivos usando um padrão glob. A tabela a seguir mostra valores de exemplo para o main campo:

Exemplo	Description
`src/index.js`	Registre funções a partir de um único arquivo raiz.
*`src/functions/.js`**	Registe cada função a partir do seu próprio ficheiro.
*`src/{index.js,functions/.js}`**	Uma combinação em que você registra cada função de seu próprio arquivo, mas ainda tem um arquivo raiz para código geral no nível do aplicativo.

Exemplo	Description
`dist/src/index.js`	Registre funções a partir de um único arquivo raiz.
*`dist/src/functions/.js`**	Registe cada função a partir do seu próprio ficheiro.
*`dist/src/{index.js,functions/.js}`**	Uma combinação em que você registra cada função de seu próprio arquivo, mas ainda tem um arquivo raiz para código geral no nível do aplicativo.

Gorjeta

Certifique-se de definir um main campo em seu arquivo package.json .

Alternar a ordem dos argumentos

A entrada de gatilho, em vez do contexto de invocação, é agora o primeiro argumento para o manipulador de funções. O contexto de invocação, agora o segundo argumento, é simplificado na v4 e não é tão necessário quanto a entrada de gatilho. Você pode deixá-lo fora se você não estiver usando.

Gorjeta

Mude a ordem dos seus argumentos. Por exemplo, se você estiver usando um gatilho HTTP, alterne (context, request) para um ou (request, context) apenas (request) se não estiver usando o contexto.

Defina sua função no código

Não é mais necessário criar e manter esses arquivos de configuração function.json separados. Agora você pode definir totalmente suas funções diretamente em seus arquivos TypeScript ou JavaScript. Além disso, muitas propriedades agora têm padrões para que você não precise especificá-los sempre.

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

Gorjeta

Mova a configuração do arquivo function.json para o código. O tipo do gatilho corresponde a um método no app objeto no novo modelo. Por exemplo, se você usar um httpTrigger tipo em function.json, chame app.http() seu código para registrar a função. Se você usa timerTriggero , ligue para app.timer().

Rever a sua utilização do contexto

Na v4, o objeto é simplificado para reduzir a context duplicação e facilitar a escrita de testes de unidade. Por exemplo, simplificamos a entrada e a saída primárias para que elas sejam acessadas apenas como o argumento e o valor de retorno do manipulador de funções.

Você não pode mais acessar a entrada e saída primária no objeto, mas ainda deve acessar entradas e saídas secundárias no context context objeto. Para obter mais informações sobre entradas e saídas secundárias, consulte o Guia do desenvolvedor .js nó.

Obter a entrada principal como argumento

A entrada primária também é chamada de gatilho e é a única entrada ou saída necessária. Você deve ter um (e apenas um) gatilho.

A versão 4 suporta apenas uma maneira de obter a entrada do gatilho, como o primeiro argumento:

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

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

A versão 3 suporta várias maneiras de obter a entrada do gatilho:

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;

Gorjeta

Certifique-se de que não está a utilizar ou context.bindings a obter a context.req entrada.

Defina a saída primária como seu valor de retorno

A versão 4 suporta apenas uma maneira de definir a saída primária, através do valor de retorno:

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

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

A versão 3 suporta várias maneiras de definir a saída primária:

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

Gorjeta

Certifique-se de sempre retornar a saída em seu manipulador de funções, em vez de defini-la com o context objeto.

Registo de contexto

Na v4, os métodos de log foram movidos para o objeto raiz context , conforme mostrado no exemplo a seguir. Para obter mais informações sobre registro, consulte o Guia do desenvolvedor .js nó.

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

Criar um contexto de teste

A versão 3 não dá suporte à criação de um contexto de invocação fora do tempo de execução do Azure Functions, portanto, a criação de testes de unidade pode ser difícil. A versão 4 permite criar uma instância do contexto de invocação, embora as informações durante os testes não sejam detalhadas, a menos que você mesmo as adicione.

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

Rever a sua utilização de tipos HTTP

Os tipos de solicitação e resposta HTTP agora são um subconjunto do padrão de busca. Eles não são mais exclusivos do Azure Functions.

Os tipos usam o undici pacote em Node.js. Este pacote segue o padrão de busca e está atualmente sendo integrado ao núcleo .js Node.

HttpRequest

Corpo. Você pode acessar o corpo usando um método específico para o tipo que você deseja receber:

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

Cabeçalho:

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

Parâmetro de consulta:

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

Corpo. Você pode acessar o corpo de várias maneiras, mas o tipo retornado nem sempre é consistente:

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

Cabeçalho. Você pode recuperar um cabeçalho de várias maneiras:

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

Parâmetro de consulta:
```
const name = request.query.name;
```

Resposta Http

Estado:
```
return { status: 200 };
```
Corpo:

Use a propriedade para retornar a body maioria dos tipos, como um string ou Buffer:
```
return { body: "Hello, world!" };
```
Use a propriedade para a jsonBody maneira mais fácil de retornar uma resposta JSON:
```
return { jsonBody: { hello: "world" } };
```

Cabeçalho. Você pode definir o cabeçalho de duas maneiras, dependendo se você estiver usando a classe ou a HttpResponse HttpResponseInit interface:

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

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

Estado. Você pode definir um status de várias maneiras:

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

Corpo. Você pode definir um corpo de várias maneiras e ele é o mesmo, independentemente do tipo de corpo (string, , objeto JSON, Bufferetc.):

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

Cabeçalho. Você pode definir um cabeçalho de várias maneiras:

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

Gorjeta

Atualize qualquer lógica usando os tipos de solicitação ou resposta HTTP para corresponder aos novos métodos.

Gorjeta

Atualize qualquer lógica usando os tipos de solicitação ou resposta HTTP para corresponder aos novos métodos. Você deve obter erros de compilação do TypeScript para ajudá-lo a identificar se você está usando métodos antigos.

Resolver problemas

Consulte o guia Solução de problemas .js nó.

Partilhar via

Migrar para a versão 4 do modelo de programação Node.js para o Azure Functions

Considerações

Requisitos

Incluir o pacote npm

Definir o ponto de entrada do aplicativo

Alternar a ordem dos argumentos

Defina sua função no código

Rever a sua utilização do contexto

Obter a entrada principal como argumento

Defina a saída primária como seu valor de retorno

Registo de contexto

Criar um contexto de teste

Rever a sua utilização de tipos HTTP

HttpRequest

Resposta Http

Resolver problemas

Comentários

Recursos adicionais