Migrieren auf Version 4 des Node.js-Programmiermodells für Azure Functions

Artikel
19.01.2024

In diesem Artikel werden die Unterschiede zwischen Version 3 und Version 4 des Node.js-Programmiermodells sowie das Upgrade einer vorhandenen v3-App erläutert. Wenn Sie eine neue v4-App erstellen möchten, anstatt ein Upgrade einer vorhandenen v3-App auszuführen, lesen Sie das Tutorial für Visual Studio Code (VS Code) oder Azure Functions Core Tools. In diesem Artikel werden „Tipp“-Warnungen verwendet, um die wichtigsten konkreten Aktionen, die Sie zum Upgrade Ihrer App ergreifen sollten, hervorzuheben.

Version 4 bietet Node.js-Entwicklern die folgenden Nutzen:

Stellen Sie eine vertraute und intuitive Benutzeroberfläche für Node.js-Entwickler bereit.
Stellen Sie eine flexible Dateistruktur mit Unterstützung für vollständige Anpassung bereit.
Wechseln Sie zu einem codezentrierten Ansatz zum Definieren der Funktionskonfiguration.

Überlegungen

Das Node.js-Programmiermodell sollte nicht mit der Azure Functions-Runtime verwechselt werden:
- Programmiermodell: Definiert, wie Sie Ihren Code erstellen und ist spezifisch für JavaScript und TypeScript.
- Runtime: Definiert das zugrunde liegende Verhalten von Azure Functions und wird für alle Sprachen gemeinsam verwendet.
Die Programmiermodellversion ist eng an die Version des @azure/functions-npm-Pakets gebunden. Sie wird unabhängig von der Runtime mit Versionsangaben versehen. Sowohl die Runtime als auch das Programmiermodell verwenden die Angabe „4“ als neueste Hauptversion, aber das ist Zufall.
Sie können die v3- und v4-Programmiermodelle nicht in derselben Funktions-App kombinieren. Sobald Sie eine v4-Funktion in Ihrer App registrieren, werden alle in function.json-Dateien registrierten v3-Funktionen ignoriert.

Anforderungen

Version 4 des Node.js-Programmiermodells erfordert die folgenden Mindestversionen:

@azure/functions npm-Paket v4.0.0
Node.js v18 oder höher
Azure Functions-Runtime v4.25 oder höher
Azure Functions Core Tools v4.0.5382 oder höher (bei lokaler Ausführung)

@azure/functions npm-Paket v4.0.0
Node.js v18 oder höher
TypeScript v4 oder höher
Azure Functions-Runtime v4.25 oder höher
Azure Functions Core Tools v4.0.5382 oder höher (bei lokaler Ausführung)

Einbinden des npm-Pakets

In V4 enthält das @azure/functions-npm-Paket den primären Quellcode, der das Node.js-Programmiermodell unterstützt. In früheren Versionen wurde dieser Code direkt in Azure ausgeliefert, und das npm-Paket enthielt nur die TypeScript-Typen. Sie müssen dieses Paket jetzt sowohl für TypeScript- als auch für JavaScript-Apps einschließen. Sie können das Paket für vorhandene v3-Apps einschließen, aber es ist nicht erforderlich.

Tipp

Stellen Sie sicher, dass das @azure/functions-Paket im dependencies-Abschnitt (nicht devDependencies) Ihrer package.json-Datei aufgeführt wird. Sie können V4 mit dem folgenden Befehl installieren:

npm install @azure/functions

Festlegen des App-Einstiegspunkts

In v4 des Programmiermodells können Sie Ihren Code beliebig strukturieren. Die einzigen Dateien, die Sie am Stamm Ihrer App benötigen, sind host.json und package.json.

Andernfalls definieren Sie die Dateistruktur, indem Sie das main-Feld in Ihrer Datei package.json festlegen. Sie können das main-Feld auf eine einzelne Datei oder mithilfe eines Globmusters auf mehrere Dateien festlegen. Die folgende Tabelle enthält Beispielwerte für das Feld main:

Beispiel	BESCHREIBUNG
`src/index.js`	Registrieren Sie Funktionen in einer einzelnen Stammdatei.
*`src/functions/.js`**	Registrieren Sie jede Funktion in ihrer eigenen Datei.
*`src/{index.js,functions/.js}`**	Eine Kombination, in der Sie jede Funktion in ihrer eigenen Datei registrieren, aber dennoch über eine Stammdatei für allgemeinen Code auf App-Ebene verfügen.

Beispiel	BESCHREIBUNG
`dist/src/index.js`	Registrieren Sie Funktionen in einer einzelnen Stammdatei.
*`dist/src/functions/.js`**	Registrieren Sie jede Funktion in ihrer eigenen Datei.
*`dist/src/{index.js,functions/.js}`**	Eine Kombination, in der Sie jede Funktion in ihrer eigenen Datei registrieren, aber dennoch über eine Stammdatei für allgemeinen Code auf App-Ebene verfügen.

Tipp

Stellen Sie sicher, dass Sie ein main-Feld in Ihrer Datei package.json definieren.

Ändern der Reihenfolge der Argumente

Die Triggereingabe ist jetzt das erste Argument für den Funktionshandler anstelle des Aufrufkontexts. Der Aufrufkontext, jetzt das zweite Argument, wurde in V4 vereinfacht und ist nicht so erforderlich wie die Triggereingabe. Er kann weggelassen werden, wenn Sie ihn nicht verwenden.

Tipp

Ändern Sie die Reihenfolge Ihrer Argumente. Wenn Sie beispielsweise einen HTTP-Trigger verwenden, ändern Sie (context, request) in (request, context) oder nur (request), wenn Sie den Kontext nicht verwenden.

Definieren Ihrer Funktion in Code

Sie müssen diese separaten funktions.json-Konfigurationsdateien nicht mehr erstellen und verwalten. Sie können Ihre Funktionen jetzt vollständig in Ihren TypeScript- oder JavaScript-Dateien definieren. Darüber hinaus verfügen viele Eigenschaften jetzt über Standardwerte, sodass Sie nicht jedes Mal Werte angeben müssen.

JavaScript

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

JavaScript

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

JSON

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

TypeScript

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

TypeScript

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;

JSON

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ],
  "scriptFile": "../dist/HttpTrigger1/index.js"
}

Tipp

Verschieben Sie die Konfiguration aus Ihrer function.json-Datei in Ihren Code. Der Typ des Triggers entspricht einer Methode für das app-Objekt im neuen Modell. Wenn Sie beispielsweise einen httpTrigger-Typ in function.json verwenden, rufen Sie app.http() in Ihrem Code auf, um die Funktion zu registrieren. Wenn Sie timerTrigger verwenden, rufen Sie app.timer() auf.

Überprüfen der Verwendung des Kontexts

In V4 wird das context-Objekt vereinfacht, um Dopplungen zu reduzieren und das Schreiben von Komponententests zu vereinfachen. Beispielsweise haben wir die primäre Eingabe und Ausgabe optimiert, sodass auf sie nur als Argument und Rückgabewert Ihres Funktionshandlers zugegriffen wird.

Sie können nicht mehr auf die primäre Eingabe und Ausgabe für das context-Objekt zugreifen. Sie müssen jedoch weiterhin auf sekundäre Eingaben und Ausgaben für das context-Objekt zugreifen. Weitere Informationen zu sekundären Eingaben und Ausgaben finden Sie im Entwicklerleitfaden für Node.js.

Abrufen der primären Eingabe als Argument

Die primäre Eingabe wird auch als Trigger bezeichnet und ist die einzige erforderliche Eingabe oder Ausgabe. Sie müssen genau einen Trigger verwenden.

Version 4 unterstützt nur eine Möglichkeit, die Triggereingabe abzurufen, nämlich als erstes Argument:

JavaScript

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

TypeScript

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

Version 3 unterstützt mehrere Möglichkeiten, die Triggereingabe abzurufen:

JavaScript

async function httpTrigger1(context, request) {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

TypeScript

async function httpTrigger1(context: Context, req: HttpRequest): Promise<void> {
    const option1 = request;
    const option2 = context.req;
    const option3 = context.bindings.req;

Tipp

Stellen Sie sicher, dass Sie nicht context.req oder context.bindings verwenden, um die Eingabe abzurufen.

Festlegen der primären Ausgabe als Rückgabewert

Version 4 unterstützt nur eine Möglichkeit, die primäre Ausgabe festzulegen, nämlich über den Rückgabewert:

JavaScript

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

TypeScript

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

Version 3 unterstützt mehrere Möglichkeiten, die primäre Ausgabe festzulegen:

JavaScript

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

Tipp

Stellen Sie sicher, dass Sie die Ausgabe immer im Funktionshandler zurückgeben, anstatt sie mit dem context-Objekt festzulegen.

Kontextprotokollierung

In v4 wurden Protokollierungsmethoden in das Stammobjekt context verschoben, wie im folgenden Beispiel gezeigt. Weitere Informationen zur Protokollierung finden Sie im Leitfaden für die Node.js-Entwicklung.

JavaScript

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

JavaScript

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

Erstellen eines Testkontexts

Version 3 unterstützt das Erstellen eines Aufrufkontexts außerhalb der Azure Functions-Runtime nicht, sodass das Erstellen von Komponententests schwierig sein kann. Mit Version 4 können Sie eine Instanz des Aufrufkontexts erstellen, obwohl die Informationen während der Tests nicht detailliert sind, es sei denn, Sie fügen sie selbst hinzu.

JavaScript

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

Überprüfen der Verwendung von HTTP-Typen

Die HTTP-Anforderungs- und -Antworttypen sind jetzt eine Teilmenge des Abrufstandards. Sie sind nicht mehr typspezifisch für Azure Functions.

Die Typen verwenden das undici-Paket in Node.js. Das Paket folgt dem Abrufstandard und wird derzeit in Node.js Core integriert.

HttpRequest

Text: Sie können auf den Textkörper mit einer Methode zugreifen, die für den gewünschten Typ spezifisch ist:

JavaScript

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

Header:

JavaScript

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

Abfrageparameter:

JavaScript

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

Text: Sie können auf verschiedene Weise auf den Textkörper zugreifen, aber der zurückgegebene Typ ist nicht immer konsistent:

JavaScript

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

Header. Sie können einen Header auf verschiedene Arten abrufen:

JavaScript

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

Abfrageparameter:

JavaScript
```
const name = request.query.name;
```

HttpResponse

Status:

JavaScript
```
return { status: 200 };
```
Text:

Verwenden Sie die body-Eigenschaft, um die meisten Typen wie string oder Buffer zurückzugeben:

JavaScript
```
return { body: "Hello, world!" };
```
Verwenden Sie die jsonBody-Eigenschaft als einfachste Möglichkeit, eine JSON-Antwort zurückzugeben:

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

Header. Sie können den Header auf zwei Arten festlegen, je nachdem, ob Sie die HttpResponse-Klasse oder die HttpResponseInit-Schnittstelle verwenden:

JavaScript

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

JavaScript

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

Status: Sie können einen Status auf verschiedene Arten festlegen:

JavaScript

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

Text: Sie können einen Text auf verschiedene Arten festlegen, und er ist unabhängig vom Texttyp (string, Buffer, JSON-Objekt usw.):

JavaScript

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

Header. Sie können einen Header auf verschiedene Arten festlegen:

JavaScript

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

Tipp

Aktualisieren Sie die gesamte Programmlogik mithilfe der HTTP-Anforderungs- oder Antworttypen so, dass sie den neuen Methoden entspricht.

Tipp

Aktualisieren Sie die gesamte Programmlogik mithilfe der HTTP-Anforderungs- oder Antworttypen so, dass sie den neuen Methoden entspricht. Sie sollten TypeScript-Buildfehler erhalten, aus denen hervorgeht, ob Sie alte Methoden verwenden.

Problembehandlung

Weitere Informationen finden Sie im Node.js-Leitfaden zur Problembehandlung.

Zusätzliche Ressourcen

Dokumentation

Node.js Entwicklerreferenz für Azure Functions

Erfahren Sie, wie Sie mithilfe von Node.js Funktionen entwickeln können.
Problembehandlung bei Node.js Apps in Azure Functions

Erfahren Sie, wie Sie häufige Fehler beim Bereitstellen oder Ausführen einer Node.js-App in Azure Functions beheben.
Einführung in die Entwicklung von serverlosen Node.js Apps mit Azure-Funktionen - JavaScript on Azure

Erfahren Sie, wie Sie serverlose Node.js Anwendungen mit Azure Functions entwickeln. In diesem Leitfaden werden die serverlosen Technologien von Azure vorgestellt, mit denen Sie skalierbare, on-demand-HTTP-Endpunkte mit JavaScript und TypeScript erstellen können.
Erstellen einer TypeScript-Funktion mit Visual Studio Code: Azure Functions

Erfahren Sie, wie Sie eine TypeScript-Funktion erstellen und dann das lokale Node.js-Projekt für serverloses Hosting in Azure Functions unter Verwendung der Azure Functions-Erweiterung in Visual Studio Code veröffentlichen.
Erstellen einer TypeScript-Funktion über die Befehlszeile: Azure Functions

Erfahren Sie, wie Sie eine TypeScript-Funktion über die Befehlszeile erstellen und anschließend das lokale Projekt für das serverlose Hosten in Azure Functions veröffentlichen.
Installieren von Knotenmodulen in Ihrer Azure Functions-Anwendung [8 von 16]

Erfahren Sie, wie Sie Node-Module in Ihrer Azure Functions-Anwendung installieren und die Funktionen Ihrer Logik erweitern. Zuerst installieren Sie eine Bibliothek aus der npm-Registrierung, um Datumsangaben zu bearbeiten. Anschließend importieren Sie die Bibliothek in Ihre Logik und verwenden sie, um die Datumswerte in einer HTTP GET-Funktion zu formaieren. Schließlich lösen Sie die Funktion aus und formatieren die Ablaufdaten Ihrer Produkte. Zusätzliche Ressourcen:JavaScript-Referenz für Azure-Funkti
Übersicht über die Runtimeversionen von Azure Functions

Azure Functions unterstützt mehrere Versionen der Runtime. Lernen Sie die Unterschiede kennen, und erfahren Sie, wie Sie die Version auswählen, die sich am besten für Ihre Anforderungen eignet.

Ereignisse

Intelligente Apps erstellen

17. März, 21 Uhr - 21. März, 10 Uhr

Nehmen Sie an der Meetup-Serie teil, um skalierbare KI-Lösungen basierend auf realen Anwendungsfällen mit Mitentwicklern und Experten zu erstellen.

Jetzt registrieren

Teilen über

Migrieren auf Version 4 des Node.js-Programmiermodells für Azure Functions

Überlegungen

Anforderungen

Einbinden des npm-Pakets

Festlegen des App-Einstiegspunkts

Ändern der Reihenfolge der Argumente

Definieren Ihrer Funktion in Code

Überprüfen der Verwendung des Kontexts

Abrufen der primären Eingabe als Argument

Festlegen der primären Ausgabe als Rückgabewert

Kontextprotokollierung

Erstellen eines Testkontexts

Überprüfen der Verwendung von HTTP-Typen

HttpRequest

HttpResponse

Problembehandlung

Feedback

Zusätzliche Ressourcen