Migrowanie do wersji 4 modelu programowania Node.js dla usługi Azure Functions

W tym artykule omówiono różnice między wersją 3 i wersją 4 modelu programowania Node.js oraz sposób uaktualniania istniejącej aplikacji w wersji 3. Jeśli chcesz utworzyć nową aplikację w wersji 4 zamiast uaktualniać istniejącą aplikację w wersji 3, zobacz samouczek dotyczący programu Visual Studio Code (VS Code) lub narzędzi Azure Functions Core Tools. W tym artykule użyto alertów "porada", aby wyróżnić najważniejsze konkretne działania, które należy wykonać w celu uaktualnienia aplikacji.

Wersja 4 została zaprojektowana w celu zapewnienia deweloperom Node.js następujących korzyści:

• Udostępniaj znane i intuicyjne środowisko dla deweloperów Node.js.
• Elastyczne tworzenie struktury plików dzięki obsłudze pełnego dostosowywania.
• Przejdź do podejścia skoncentrowanego na kodzie na potrzeby definiowania konfiguracji funkcji.

Kwestie wymagające rozważenia

• Model programowania Node.js nie powinien być mylony ze środowiskiem uruchomieniowym usługi Azure Functions:
  • Model programowania: definiuje sposób tworzenia kodu i jest specyficzny dla języków JavaScript i TypeScript.
  • Środowisko uruchomieniowe: definiuje podstawowe zachowanie usługi Azure Functions i jest współużytkowane we wszystkich językach.
• Wersja modelu programowania jest ściśle powiązana z wersją @azure/functions pakietu npm. Jest ona wersjonowana niezależnie od środowiska uruchomieniowego. Zarówno środowisko uruchomieniowe, jak i model programowania używają numeru 4 jako najnowszej wersji głównej, ale to zbieg okoliczności.
• Nie można mieszać modeli programowania w wersji 3 i 4 w tej samej aplikacji funkcji. Po zarejestrowaniu jednej funkcji w wersji 4 w aplikacji wszystkie funkcje w wersji 3 zarejestrowane w plikach function.json są ignorowane.

Wymagania

Wersja 4 modelu programowania Node.js wymaga następujących minimalnych wersji:

• @azure/functions Pakiet npm w wersji 4.0.0
• Node.js v18+
• Środowisko uruchomieniowe usługi Azure Functions w wersji 4.25 lub nowszej
• Narzędzia Azure Functions Core Tools w wersji 4.0.5382 lub nowszej (jeśli są uruchomione lokalnie)

• @azure/functions Pakiet npm w wersji 4.0.0
• Node.js v18+
• TypeScript v4+
• Środowisko uruchomieniowe usługi Azure Functions w wersji 4.25 lub nowszej
• Narzędzia Azure Functions Core Tools w wersji 4.0.5382 lub nowszej (jeśli są uruchomione lokalnie)

Uwzględnij pakiet npm

W wersji 4 @azure/functions pakiet npm zawiera podstawowy kod źródłowy, który wspiera model programowania Node.js. W poprzednich wersjach ten kod dostarczany bezpośrednio na platformie Azure i pakiet npm miał tylko typy TypeScript. Teraz musisz dołączyć ten pakiet zarówno dla aplikacji TypeScript, jak i JavaScript. Możesz dołączyć pakiet dla istniejących aplikacji w wersji 3, ale nie jest wymagany.

Napiwek

Upewnij się, że @azure/functions pakiet znajduje się na liście w dependencies sekcji (nie devDependencies) pliku package.json . Możesz zainstalować wersję 4 przy użyciu następującego polecenia:

npm install @azure/functions

Ustawianie punktu wejścia aplikacji

W wersji 4 modelu programowania można jednak utworzyć strukturę kodu. Jedynymi plikami potrzebnymi w katalogu głównym aplikacji są pliki host.json i package.json.

W przeciwnym razie należy zdefiniować strukturę plików, ustawiając main pole w pliku package.json . Pole można ustawić main na jeden plik lub wiele plików przy użyciu wzorca glob. W poniższej main tabeli przedstawiono przykładowe wartości pola:

Przykład	opis
src/index.js	Rejestrowanie funkcji z jednego pliku głównego.
src/functions/*.js	Zarejestruj każdą funkcję z własnego pliku.
src/{index.js,functions/*.js}	Kombinacja, w której rejestrujesz każdą funkcję z własnego pliku, ale nadal masz plik główny ogólnego kodu na poziomie aplikacji.

Przykład	opis
dist/src/index.js	Rejestrowanie funkcji z jednego pliku głównego.
dist/src/functions/*.js	Zarejestruj każdą funkcję z własnego pliku.
dist/src/{index.js,functions/*.js}	Kombinacja, w której rejestrujesz każdą funkcję z własnego pliku, ale nadal masz plik główny ogólnego kodu na poziomie aplikacji.

Napiwek

Upewnij się, że zdefiniowano main pole w pliku package.json .

Przełączanie kolejności argumentów

Dane wejściowe wyzwalacza zamiast kontekstu wywołania są teraz pierwszym argumentem programu obsługi funkcji. Kontekst wywołania, teraz drugi argument, jest uproszczony w wersji 4 i nie jest tak wymagany, jak dane wejściowe wyzwalacza. Możesz go pozostawić, jeśli nie używasz go.

Napiwek

Przełącz kolejność argumentów. Jeśli na przykład używasz wyzwalacza HTTP, przełącz się na (request, context) lub (context, request) po prostu(request), jeśli nie używasz kontekstu.

Definiowanie funkcji w kodzie

Nie trzeba już tworzyć i obsługiwać tych oddzielnych plików konfiguracji function.json . Teraz możesz w pełni zdefiniować funkcje bezpośrednio w plikach TypeScript lub JavaScript. Ponadto wiele właściwości ma teraz wartości domyślne, dzięki czemu nie trzeba ich określać za każdym razem.

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

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

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

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

Napiwek

Przenieś konfigurację z pliku function.json do kodu. Typ wyzwalacza odpowiada metodzie na app obiekcie w nowym modelu. Jeśli na przykład używasz httpTrigger typu w pliku function.json, wywołaj app.http() metodę w kodzie, aby zarejestrować funkcję. Jeśli używasz metody timerTrigger, wywołaj metodę app.timer().

Przeglądanie użycia kontekstu

W wersji 4 obiekt jest uproszczony w context celu zmniejszenia duplikacji i ułatwienia pisania testów jednostkowych. Na przykład usprawniliśmy podstawowe dane wejściowe i wyjściowe, aby były dostępne tylko jako argument i zwracana wartość programu obsługi funkcji.

Nie można już uzyskać dostępu do podstawowych danych wejściowych i wyjściowych obiektu context , ale nadal musisz uzyskać dostęp do pomocniczych danych wejściowych i wyjściowych w context obiekcie. Aby uzyskać więcej informacji na temat pomocniczych danych wejściowych i wyjściowych, zobacz Przewodnik dewelopera Node.js.

Pobieranie podstawowych danych wejściowych jako argumentu

Podstawowe dane wejściowe są również nazywane wyzwalaczem i są jedynymi wymaganymi danymi wejściowymi lub wyjściowymi. Musisz mieć jeden (i tylko jeden) wyzwalacz.

Wersja 4

Wersja 4 obsługuje tylko jeden sposób pobierania danych wejściowych wyzwalacza jako pierwszy argument:

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

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

Wersja 3

Wersja 3 obsługuje kilka sposobów pobierania danych wejściowych wyzwalacza:

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;

Napiwek

Upewnij się, że nie używasz context.req ani context.bindings nie uzyskujesz danych wejściowych.

Ustaw podstawowe dane wyjściowe jako wartość zwracaną

Wersja 4

Wersja 4 obsługuje tylko jeden sposób ustawiania podstawowych danych wyjściowych za pośrednictwem wartości zwracanej:

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

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

Wersja 3

Wersja 3 obsługuje kilka sposobów ustawiania podstawowych danych wyjściowych:

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

Napiwek

Upewnij się, że zawsze zwracasz dane wyjściowe w procedurze obsługi funkcji, zamiast ustawiać je za context pomocą obiektu .

Rejestrowanie kontekstu

W wersji 4 metody rejestrowania zostały przeniesione do obiektu głównego context , jak pokazano w poniższym przykładzie. Aby uzyskać więcej informacji na temat rejestrowania, zobacz Przewodnik dewelopera Node.js.

Wersja 4

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

Wersja 3

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

Tworzenie kontekstu testowego

Wersja 3 nie obsługuje tworzenia kontekstu wywołania poza środowiskiem uruchomieniowym usługi Azure Functions, więc tworzenie testów jednostkowych może być trudne. Wersja 4 umożliwia utworzenie wystąpienia kontekstu wywołania, chociaż informacje podczas testów nie są szczegółowe, chyba że dodasz je samodzielnie.

Wersja 4

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

Wersja 3

Nie można.

Przeglądanie użycia typów HTTP

Typy żądań HTTP i odpowiedzi są teraz podzbiorem standardu pobierania. Nie są one już unikatowe dla usługi Azure Functions.

Typy używają undici pakietu w pliku Node.js. Ten pakiet jest zgodny ze standardem pobierania i jest obecnie zintegrowany z platformą Node.js Core.

HttpRequest

Wersja 4

• Treść. Dostęp do treści można uzyskać przy użyciu metody specyficznej dla typu, który chcesz otrzymać:

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

• Nagłówek:

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

• Parametr zapytania:

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

Wersja 3

• Treść. Dostęp do treści można uzyskać na kilka sposobów, ale zwracany typ nie zawsze jest spójny:

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

• Nagłówek. Nagłówek można pobrać na kilka sposobów:

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

• Parametr zapytania:

  const name = request.query.name;
  

HttpResponse

Wersja 4

• Stan:

  return { status: 200 };
  

• Treść:

  Użyj właściwości , body aby zwrócić większość typów, takich jak a string lub Buffer:

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

  jsonBody Użyj właściwości w najprostszy sposób, aby zwrócić odpowiedź JSON:

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

• Nagłówek. Nagłówek można ustawić na dwa sposoby, w zależności od tego, czy używasz HttpResponse klasy, czy interfejsu HttpResponseInit :

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

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

Wersja 3

• Stan. Stan można ustawić na kilka sposobów:

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

• Treść. Treść można ustawić na kilka sposobów i jest taka sama niezależnie od typu treści (string, Buffer, obiektu JSON itp.):

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

• Nagłówek. Nagłówek można ustawić na kilka sposobów:

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

Napiwek

Zaktualizuj dowolną logikę przy użyciu żądania HTTP lub typów odpowiedzi, aby dopasować je do nowych metod.

Napiwek

Zaktualizuj dowolną logikę przy użyciu żądania HTTP lub typów odpowiedzi, aby dopasować je do nowych metod. Błędy kompilacji języka TypeScript powinny pomóc w ustaleniu, czy używasz starych metod.

Rozwiązywanie problemów

Zobacz Przewodnik rozwiązywania problemów z platformą Node.js.