Bermigrasi ke versi 4 dari model pemrograman Node.js untuk Azure Functions

Artikel ini membahas perbedaan antara versi 3 dan versi 4 dari model pemrograman Node.js dan cara meningkatkan aplikasi v3 yang ada. Jika Anda ingin membuat aplikasi v4 baru alih-alih memutakhirkan aplikasi v3 yang ada, lihat tutorial untuk Visual Studio Code (VS Code) atau Azure Functions Core Tools. Artikel ini menggunakan pemberitahuan "tip" untuk menyoroti tindakan konkret terpenting yang harus Anda ambil untuk meningkatkan aplikasi Anda.

Versi 4 dirancang untuk memberi pengembang Node.js manfaat berikut:

• Berikan pengalaman yang akrab dan intuitif kepada pengembang Node.js.
• Jadikan struktur file fleksibel dengan dukungan untuk penyesuaian penuh.
• Beralih ke pendekatan yang berpusat pada kode untuk menentukan konfigurasi fungsi.

Pertimbangan

• Model pemrograman Node.js tidak boleh dikacaukan dengan runtime Bahasa Umum Azure Functions:
  • Model pemrograman: Menentukan bagaimana Anda menulis kode Anda dan khusus untuk JavaScript dan TypeScript.
  • Runtime: Menentukan perilaku yang mendasari Azure Functions dan dibagikan di semua bahasa.
• Versi model pemrograman sangat terkait dengan versi @azure/functions paket npm. Versi ini di-versi secara independen dari runtime. Baik runtime maupun model pemrograman menggunakan nomor 4 sebagai versi utama terbarunya, tetapi itu kebetulan.
• Anda tidak dapat mencampur model pemrograman v3 dan v4 di aplikasi fungsi yang sama. Segera setelah Anda mendaftarkan satu fungsi v4 di aplikasi Anda, fungsi v3 apa pun yang terdaftar dalam file function.json diabaikan.

Persyaratan

Versi 4 dari model pemrograman Node.js memerlukan versi minimum berikut:

• @azure/functions paket npm v4.0.0
• Node.js v18+
• Runtime Azure Functions v4.25+
• Azure Functions Core Tools v4.0.5382+ (jika berjalan secara lokal)

• @azure/functions paket npm v4.0.0
• Node.js v18+
• TypeScript v4+
• Runtime Azure Functions v4.25+
• Azure Functions Core Tools v4.0.5382+ (jika berjalan secara lokal)

Sertakan paket npm

Di v4, @azure/functions paket npm berisi kode sumber utama yang mendukung model pemrograman Node.js. Di versi sebelumnya, kode yang dikirim langsung di Azure dan paket npm hanya memiliki jenis TypeScript. Anda sekarang perlu menyertakan paket ini untuk aplikasi TypeScript dan JavaScript. Anda dapat menyertakan paket untuk aplikasi v3 yang ada, tetapi tidak diperlukan.

Tip

Pastikan @azure/functions paket tercantum di bagian dependencies (bukan devDependencies) file package.json Anda. Anda dapat menginstal v4 dengan menggunakan perintah berikut:

npm install @azure/functions

Mengatur titik entri aplikasi Anda

Dalam v4 model pemrograman, Anda dapat menyusun kode sesuka Anda. Satu-satunya file yang Anda butuhkan di akar aplikasi Anda adalah host.json dan package.json.

Jika tidak, Anda menentukan struktur file dengan mengatur main bidang dalam file package.json Anda. Anda dapat mengatur bidang ke main satu file atau beberapa file dengan menggunakan pola glob. Tabel berikut ini memperlihatkan contoh nilai untuk main bidang :

Contoh	Deskripsi
src/index.js	Mendaftarkan fungsi dari satu file akar.
src/functions/*.js	Daftarkan setiap fungsi dari filenya sendiri.
src/{index.js,functions/*.js}	Kombinasi tempat Anda mendaftarkan setiap fungsi dari filenya sendiri, tetapi Anda masih memiliki file root untuk kode tingkat aplikasi umum.

Contoh	Deskripsi
dist/src/index.js	Mendaftarkan fungsi dari satu file akar.
dist/src/functions/*.js	Daftarkan setiap fungsi dari filenya sendiri.
dist/src/{index.js,functions/*.js}	Kombinasi tempat Anda mendaftarkan setiap fungsi dari filenya sendiri, tetapi Anda masih memiliki file root untuk kode tingkat aplikasi umum.

Tip

Pastikan Anda menentukan main bidang dalam file package.json Anda.

Mengalihkan urutan argumen

Input pemicu, alih-alih konteks pemanggilan, sekarang menjadi argumen pertama untuk handler fungsi Anda. Konteks pemanggilan, sekarang argumen kedua, disederhanakan dalam v4 dan tidak diperlukan sebagai input pemicu. Anda dapat membiarkannya jika Anda tidak menggunakannya.

Tip

Alihkan urutan argumen Anda. Misalnya, jika Anda menggunakan pemicu HTTP, beralihlah (context, request) ke salah satu (request, context) atau hanya (request) jika Anda tidak menggunakan konteks.

Tentukan fungsi Anda dalam kode

Anda tidak lagi harus membuat dan memelihara file konfigurasi function.json terpisah tersebut. Anda sekarang dapat sepenuhnya menentukan fungsi Anda langsung di file TypeScript atau JavaScript Anda. Selain itu, banyak properti sekarang memiliki default sehingga Anda tidak perlu menentukannya setiap saat.

v4

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

v3

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

v4

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

v3

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

Tip

Pindahkan konfigurasi dari file function.json Anda ke kode Anda. Jenis pemicu sesuai dengan metode pada app objek dalam model baru. Misalnya, jika Anda menggunakan httpTrigger jenis di function.json, panggil app.http() kode Anda untuk mendaftarkan fungsi. Jika Anda menggunakan timerTrigger, hubungi app.timer().

Meninjau penggunaan konteks Anda

Di v4, objek disederhanakan context untuk mengurangi duplikasi dan membuat pengujian unit penulisan lebih mudah. Misalnya, kami menyederhanakan input dan output utama sehingga hanya diakses sebagai argumen dan nilai pengembalian handler fungsi Anda.

Anda tidak dapat mengakses input dan output utama pada context objek lagi, tetapi Anda masih harus mengakses input dan output sekunder pada context objek. Untuk informasi selengkapnya tentang input dan output sekunder, lihat panduan pengembang Node.js.

Mendapatkan input utama sebagai argumen

Input utama juga disebut pemicu dan merupakan satu-satunya input atau output yang diperlukan. Anda harus memiliki satu pemicu (dan hanya satu).

v4

Versi 4 hanya mendukung satu cara untuk mendapatkan input pemicu, sebagai argumen pertama:

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

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

v3

Versi 3 mendukung beberapa cara untuk mendapatkan input pemicu:

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;

Tip

Pastikan Anda tidak menggunakan context.req atau context.bindings untuk mendapatkan input.

Atur output utama sebagai nilai pengembalian Anda

v4

Versi 4 hanya mendukung satu cara untuk mengatur output utama, melalui nilai pengembalian:

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

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

v3

Versi 3 mendukung beberapa cara untuk mengatur output utama:

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

Tip

Pastikan Anda selalu mengembalikan output di handler fungsi Anda, alih-alih mengaturnya dengan context objek.

Pengelogan konteks

Di v4, metode pengelogan dipindahkan ke objek akar context seperti yang ditunjukkan dalam contoh berikut. Untuk informasi selengkapnya tentang pengelogan , lihat panduan pengembang Node.js.

v4

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

v3

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

Membuat konteks pengujian

Versi 3 tidak mendukung pembuatan konteks pemanggilan di luar runtime Azure Functions, sehingga pengujian unit penulisan bisa sulit. Versi 4 memungkinkan Anda membuat instans konteks pemanggilan, meskipun informasi selama pengujian tidak terperinci kecuali Anda menambahkannya sendiri.

v4

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

v3

Tidak mungkin.

Tinjau penggunaan jenis HTTP Anda

Jenis permintaan dan respons HTTP sekarang menjadi subset dari standar pengambilan. Mereka tidak lagi unik untuk Azure Functions.

Jenis menggunakan undici paket di Node.js. Paket ini mengikuti standar pengambilan dan saat ini sedang diintegrasikan ke dalam inti Node.js.

HttpRequest

v4

• Isi. Anda dapat mengakses isi dengan menggunakan metode khusus untuk jenis yang ingin Anda terima:

  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:

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

• Parameter kueri:

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

v3

• Isi. Anda dapat mengakses isi dengan beberapa cara, tetapi jenis yang dikembalikan tidak selalu konsisten:

  // 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. Anda dapat mengambil header dengan beberapa cara:

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

• Parameter kueri:

  const name = request.query.name;
  

HttpResponse

v4

• Status:

  return { status: 200 };
  

• Isi:

  body Gunakan properti untuk mengembalikan sebagian besar jenis seperti string atau Buffer:

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

  jsonBody Gunakan properti untuk cara term mudah untuk mengembalikan respons JSON:

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

• Header. Anda dapat mengatur header dengan dua cara, tergantung pada apakah Anda menggunakan HttpResponse kelas atau HttpResponseInit antarmuka:

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

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

v3

• Status. Anda dapat mengatur status dengan beberapa cara:

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

• Isi. Anda dapat mengatur isi dengan beberapa cara dan itu sama terlepas dari jenis isinya (string, Buffer, objek JSON, dll.):

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

• Header. Anda dapat mengatur header dengan beberapa cara:

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

Tip

Perbarui logika apa pun dengan menggunakan jenis permintaan atau respons HTTP agar sesuai dengan metode baru.

Tip

Perbarui logika apa pun dengan menggunakan jenis permintaan atau respons HTTP agar sesuai dengan metode baru. Anda harus mendapatkan kesalahan build TypeScript untuk membantu Anda mengidentifikasi apakah Anda menggunakan metode lama.

Pemecahan masalah

Lihat panduan Pemecahan Masalah Node.js.