Миграция на версию 4 модели программирования Node.js для Функции Azure

В этой статье рассматриваются различия между версией 3 и версией 4 модели программирования Node.js и обновление существующего приложения версии 3. Если вы хотите создать новое приложение версии 4 вместо обновления существующего приложения версии 3, ознакомьтесь с руководством по Visual Studio Code (VS Code) или Функции Azure Core Tools. В этой статье используются оповещения "совет" для выделения наиболее важных конкретных действий, которые необходимо предпринять для обновления приложения.

Версия 4 предназначена для предоставления разработчикам Node.js следующих преимуществ:

• Предоставьте знакомый и интуитивно понятный интерфейс разработчикам Node.js.
• Гибкая структура файлов с поддержкой полной настройки.
• Переключитесь на подход, ориентированный на код для определения конфигурации функции.

Рекомендации

• Модель программирования Node.js не должна путаться с средой выполнения Функции Azure:
  • Модель программирования: определяет способ разработки кода и зависит от JavaScript и TypeScript.
  • Среда выполнения. Определяет базовое поведение Функции Azure и совместно используется на всех языках.
• Версия модели программирования строго привязана к версии @azure/functions пакета npm. Она является версией независимо от среды выполнения. Среда выполнения и модель программирования используют номер 4 в качестве последней основной версии, но это совпадение.
• Нельзя смешивать модели программирования версии 3 и версии 4 в одном приложении-функции. После регистрации одной функции версии 4 в приложении все функции версии 3, зарегистрированные в файлах function.json , игнорируются.

Requirements

Для модели программирования Node.js версии 4 требуются следующие минимальные версии:

• @azure/functions пакет npm версии 4.0.0
• Node.js версии 18+
• среда выполнения Функции Azure версии 4.25+
• Функции Azure Core Tools версии 4.0.5382+ (при локальном запуске)

• @azure/functions пакет npm версии 4.0.0
• Node.js версии 18+
• TypeScript версии 4+
• среда выполнения Функции Azure версии 4.25+
• Функции Azure Core Tools версии 4.0.5382+ (при локальном запуске)

Включение пакета npm

В версии 4 @azure/functions пакет npm содержит основной исходный код, который поддерживает модель программирования Node.js. В предыдущих версиях этот код, отправленный непосредственно в Azure, и пакет npm имел только типы TypeScript. Теперь необходимо включить этот пакет для приложений TypeScript и JavaScript. Пакет можно включить для существующих приложений версии 3, но это не обязательно.

Совет

Убедитесь, что @azure/functions пакет указан в dependencies разделе (не devDependencies) файла package.json . Вы можете установить версию 4 с помощью следующей команды:

npm install @azure/functions

Настройка точки входа приложения

В версии 4 модели программирования можно структурировать код, однако вы хотите. Единственными файлами, которые требуется в корне приложения, являются host.json и package.json.

В противном случае необходимо определить структуру файлов, задав main поле в файле package.json . Поле можно задать main для одного файла или нескольких файлов с помощью шаблона glOB-объектов. В следующей таблице показаны примеры значений main для поля:

Пример	Description
src/index.js	Зарегистрируйте функции из одного корневого файла.
src/functions/*.js	Зарегистрируйте каждую функцию из собственного файла.
src/{index.js,functions/*.js}	Сочетание, в котором вы регистрируете каждую функцию из собственного файла, но у вас по-прежнему есть корневой файл для общего кода на уровне приложений.

Пример	Description
dist/src/index.js	Зарегистрируйте функции из одного корневого файла.
dist/src/functions/*.js	Зарегистрируйте каждую функцию из собственного файла.
dist/src/{index.js,functions/*.js}	Сочетание, в котором вы регистрируете каждую функцию из собственного файла, но у вас по-прежнему есть корневой файл для общего кода на уровне приложений.

Совет

Убедитесь, что вы определили main поле в файле package.json .

Переключение порядка аргументов

Входные данные триггера вместо контекста вызова теперь являются первым аргументом обработчика функций. Контекст вызова, теперь второй аргумент, упрощен в версии 4 и не является обязательным в качестве входных данных триггера. Его можно оставить, если вы не используете его.

Совет

Переключите порядок аргументов. Например, если вы используете триггер HTTP, переключитесь (context, request) на любой (request, context) или просто (request) , если вы не используете контекст.

Определение функции в коде

Вам больше не нужно создавать и поддерживать эти отдельные файлы конфигурации function.json . Теперь вы можете полностью определить функции непосредственно в файлах TypeScript или JavaScript. Кроме того, многие свойства теперь имеют значения по умолчанию, чтобы не указывать их каждый раз.

версия 4

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

версия 3

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

версия 4

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

версия 3

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

Совет

Переместите конфигурацию из файла function.json в код. Тип триггера соответствует методу app объекта в новой модели. Например, если вы используете httpTrigger тип в function.json, вызовите app.http() код для регистрации функции. При использовании timerTriggerвызовите app.timer().

Просмотр использования контекста

В версии 4 объект упрощен для context уменьшения дублирования и упрощения написания модульных тестов. Например, мы упрощали первичные входные и выходные данные, чтобы они были доступны только в качестве аргумента и возвращаемого значения обработчика функций.

Вы больше не можете получить доступ к основным входным и выходным данным объекта, но вы по-прежнему должны получить доступ к вторичным входным и выходным context данным объектаcontext. Дополнительные сведения о дополнительных входных и выходных данных см. в руководстве разработчика Node.js.

Получение первичных входных данных в качестве аргумента

Первичный вход также называется триггером и является единственным обязательным входным или выходным данным. У вас должен быть один триггер (и только один).

версия 4

Версия 4 поддерживает только один способ получения входных данных триггера в качестве первого аргумента:

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

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

версия 3

Версия 3 поддерживает несколько способов получения входных данных триггера:

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;

Совет

Убедитесь, что вы не используете context.req или context.bindings не получаете входные данные.

Задайте первичные выходные данные в качестве возвращаемого значения

версия 4

Версия 4 поддерживает только один способ настройки основного выходных данных с помощью возвращаемого значения:

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

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

версия 3

Версия 3 поддерживает несколько способов настройки основных выходных данных:

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

Совет

Убедитесь, что вы всегда возвращаете выходные данные в обработчике context функций, а не задаете его объектом.

Ведение журнала контекста

В версии 4 методы ведения журнала были перемещены в корневой context объект, как показано в следующем примере. Дополнительные сведения о ведении журнала см. в руководстве разработчика Node.js.

версия 4

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

версия 3

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

Создание тестового контекста

Версия 3 не поддерживает создание контекста вызова за пределами среды выполнения Функции Azure, поэтому создание модульных тестов может оказаться сложным. Версия 4 позволяет создать экземпляр контекста вызова, хотя сведения во время тестов не подробно описаны, если вы не добавите его самостоятельно.

версия 4

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

версия 3

Невозможно.

Просмотр использования типов HTTP

Типы HTTP-запросов и ответов теперь являются подмножеством стандарта получения. Они больше не уникальны для Функции Azure.

Типы используют undici пакет в Node.js. Этот пакет следует стандарту получения и в настоящее время интегрирован в ядро Node.js.

HttpRequest

версия 4

• Текст. Вы можете получить доступ к тексту с помощью метода, определенного для типа, который требуется получить:

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

• Заголовок.

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

• Параметр запроса:

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

версия 3

• Текст. Вы можете получить доступ к тексту несколькими способами, но возвращаемый тип не всегда согласован:

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

• Заголовок. Вы можете получить заголовок несколькими способами:

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

• Параметр запроса:

  const name = request.query.name;
  

HttpResponse

версия 4

• Состояние:

  return { status: 200 };
  

• Текст.

  body Используйте свойство для возврата большинства типов, таких как или string Buffer:

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

  jsonBody Используйте свойство для простого способа возврата ответа JSON:

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

• Заголовок. Заголовок можно задать двумя способами в зависимости от того, используется HttpResponse ли класс или HttpResponseInit интерфейс:

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

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

версия 3

• Состояние. Вы можете задать состояние несколькими способами:

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

• Текст. Текст можно задать несколькими способами, и он одинаков независимо от типа тела (string, Bufferобъекта JSON и т. д.):

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

• Заголовок. Заголовок можно задать несколькими способами:

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

Совет

Обновите любую логику с помощью HTTP-запроса или типов ответов, чтобы соответствовать новым методам.

Совет

Обновите любую логику с помощью HTTP-запроса или типов ответов, чтобы соответствовать новым методам. Ошибки сборки TypeScript помогут определить, используется ли старый метод.

Устранение неполадок

См. руководство по устранению неполадок Node.js.