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

  • Artigo

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:

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

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

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 contextcontext 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;

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

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

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

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 HttpResponseHttpResponseInit interface:

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

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