Azure Functions の Node.js プログラミングモデルのバージョン 4 に移行する

[アーティクル]
01/19/2024

この記事では、Node.js プログラミングモデルのバージョン 3 とバージョン 4 の違いと、既存の v3 アプリをアップグレードする方法について説明します。既存の v3 アプリをアップグレードするのではなく、v4 アプリを新規に作成する場合は、Visual Studio Code (VS Code) または Azure Functions Core Tools のいずれかのチュートリアルを参照してください。この記事では、「ヒント」アラートを使って、アプリをアップグレードする際に行うべき重要度の高い具体的なアクションを取り上げています。

バージョン 4 は、Node.js 開発者が次の利点を得られるように設計されています。

Node.js 開発者が慣れ親しんだ直感的なエクスペリエンスを提供する。
完全なカスタマイズをサポートすることで、ファイル構造を柔軟にする。
関数構成を定義するコード中心の方法に切り替える。

考慮事項

Node.js のプログラミングモデルと Azure Functions のランタイムを混同しないでください。
- プログラミングモデル: コードの作成方法を定義します。JavaScript と TypeScript に固有です。
- ランタイム: Azure Functions の基本的な動作を定義します。すべての言語で共有されます。
プログラミングモデルのバージョンは @azure/functions npm パッケージのバージョンに厳密に関連付けられています。ランタイムとは別にバージョン管理されます。ランタイムとプログラミングモデルの両方で最新のメジャーバージョン番号として 4 が使用されていますが、これは偶然です。
同じ関数アプリ内で v3 と v4 のプログラミングモデルを混在させることはできません。アプリに v4 関数を 1 つ登録するとすぐに、function.json ファイルに登録されているすべての v3 関数は無視されます。

必要条件

Node.js プログラミングモデルのバージョン 4 には、次の最小バージョンが必要です。

@azure/functions npm パッケージ v4.0.0
Node.js v18 以降
Azure Functions Runtime v4.25 以降
Azure Functions Core Tools v4.0.5382+ 以降 (ローカルで実行する場合)

@azure/functions npm パッケージ v4.0.0
Node.js v18 以降
TypeScript v4 以降
Azure Functions Runtime v4.25 以降
Azure Functions Core Tools v4.0.5382+ 以降 (ローカルで実行する場合)

npm パッケージを含める

v4 で、Node.js プログラミングモデルを支援するプライマリソースコードが @azure/functions npm パッケージに含まれるようになりました。以前のバージョンでは、このコードは Azure で直接リリースされ、npm パッケージには TypeScript 型のみが含まれていました。今後は、TypeScript と JavaScript の両方のアプリでこのパッケージを含める必要があります。既存の v3 アプリにこのパッケージを含めることは "できます" が、必須ではありません。

ヒント

package.json ファイルの dependencies セクション (devDependencies ではありません) に必ず @azure/functions パッケージを記載してください。 v4 は、次のコマンドを使用してインストールできます。

npm install @azure/functions

アプリのエントリポイントを設定する

プログラミングモデルの v4 では、コードを自由に構成できます。アプリのルートに必要なファイルは、host.json と package.json のみです。

それ以外については、package.json ファイルの main フィールドを設定することでファイル構造を定義します。 1 つのファイル、glob パターンを使って複数のファイルに main フィールドを設定できます。次の表に、フィールドの値の例を main 示します。

例	説明
`src/index.js`	1 つのルートファイルから関数を登録します。
*`src/functions/.js`**	各関数を独自のファイルから登録します。
*`src/{index.js,functions/.js}`**	各関数を独自のファイルから登録するが、一般的なアプリレベルのコード用のルートファイルがある組み合わせ。

例	説明
`dist/src/index.js`	1 つのルートファイルから関数を登録します。
*`dist/src/functions/.js`**	各関数を独自のファイルから登録します。
*`dist/src/{index.js,functions/.js}`**	各関数を独自のファイルから登録するが、一般的なアプリレベルのコード用のルートファイルがある組み合わせ。

ヒント

package.json ファイルには必ず main フィールドを定義します

引数の順序を入れ替える

関数ハンドラーの 1 つ目の引数は、呼び出しコンテキストではなくトリガー入力になりました。呼び出しコンテキストは、v4 では 2 つ目の引数になり、簡略化されました。トリガー入力とは異なり、必須ではなくなりました。使用していない場合は、オフにしておくことができます。

ヒント

引数の順序を入れ替えてください。たとえば、HTTP トリガーを使っている場合、(context, request) を (request, context) に切り替えるか、コンテキストを使わない場合は単に (request) にします。

コードで関数を定義する

これらの個別の function.json 構成ファイルを作成して維持する必要はなくなりました。 TypeScript または 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}!` };
    },
});

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

ヒント

構成を function.json ファイルからお使いのコードに移行します。トリガーの種類は、新しいモデルの app オブジェクトのメソッドに対応します。たとえば、function.json で httpTrigger 型を使う場合、コードで app.http() を呼び出して関数を登録するようにします。 timerTrigger を使用する場合は、app.timer() を呼び出します。

コンテキストの使い方を確認する

v4 では、context オブジェクトが簡略化され、重複が減り、単体テストの作成が容易になります。たとえば、プライマリ入力と出力を整理し、関数ハンドラーの引数と戻り値としてのみアクセスするようにしました。

context オブジェクトでのプライマリ入力と出力にはアクセスできなくなりましたが、context オブジェクトでのセカンダリ入力と出力には引き続きアクセスする必要があります。セカンダリ入力と出力の詳細については、Node.js 開発者向けガイドを参照してください。

引数としてプライマリ入力を取得する

プライマリ入力は「トリガー」とも呼ばれ、唯一の必要な入力または出力です。使用できるのは 1 つのトリガーのみです。

バージョン 4 は、最初の引数としてトリガー入力を取得する以下の方法のみをサポートしています。

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

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

バージョン 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 は、戻り値を介してプライマリ出力を設定する方法のみをサポートしています。

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

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

バージョン 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 オブジェクトを使って設定するのではなく、関数ハンドラーで常に出力を返すようにしてください。

コンテキストログ

v4 では、次の例に示すように、ログ記録メソッドがルート context オブジェクトに移動されました。ログ記録の詳細については、Node.js 開発者ガイドを参照してください。

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

テストコンテキストを作成する

バージョン 3 は、Azure Functions Runtime の外部で呼び出しコンテキストを作成することをサポートしていないため、単体テストの作成が困難でした。バージョン 4 では、呼び出しコンテキストのインスタンスを作成できますが、テスト中の情報は、自分で追加しない限り詳細ではありません。

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

HTTP の型の使い方を確認する

HTTP 要求と応答の型は、fetch 標準のサブセットになりました。これらは、Azure Functions に固有ではなくなりました。

型は、Node.js の undici パッケージを使用します。このパッケージは fetch 標準に準拠し、現在は Node.js コアに統合されています。

HttpRequest

本文。受け取る型に応じたメソッドを使って、本文にアクセスできます。

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

本文。本文にアクセスする方法はいくつかありますが、戻り値の型は必ずしも一定ではありません。

// 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

状態:
```
return { status: 200 };
```
本文:

プロパティをbody使用して、次のようなほとんどの型をBufferstring返します。
```
return { body: "Hello, world!" };
```
JSON 応答を jsonBody 返す最も簡単な方法では、このプロパティを使用します。
```
return { jsonBody: { hello: "world" } };
```

ヘッダー。ヘッダーは HttpResponse クラスと HttpResponseInit インターフェイスのどちらを使うかに応じて、2 つの方法で設定できます。

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

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

Status。状態は、次のような方法で設定できます。

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

本文。本文は複数の方法で設定でき、本文の種類 (string、 BufferJSON オブジェクトなど) に関係なく同じです。

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 のトラブルシューティングガイドを参照してください。

Azure Functions の Node.js プログラミング モデルのバージョン 4 に移行する