الترحيل إلى الإصدار 4 من نموذج البرمجة Node.js ل Azure Functions

تتناول هذه المقالة الاختلافات بين الإصدار 3 والإصدار 4 من نموذج البرمجة Node.js وكيفية ترقية تطبيق v3 موجود. إذا كنت ترغب في إنشاء تطبيق v4 جديد بدلا من ترقية تطبيق v3 موجود، فشاهد البرنامج التعليمي إما ل Visual Studio Code (VS Code) أو Azure Functions Core Tools. تستخدم هذه المقالة تنبيهات "تلميح" لتسليط الضوء على أهم الإجراءات الملموسة التي يجب اتخاذها لترقية تطبيقك. تم تصميم الإصدار 4 لتزويد مطوري Node.js بالمزايا التالية:

• توفير تجربة مألوفة وبديهية للمطورين Node.js.
• اجعل بنية الملف مرنة مع دعم التخصيص الكامل.
• قم بالتبديل إلى نهج يركز على التعليمات البرمجية لتعريف تكوين الدالة.

Considerations

• لا ينبغي الخلط بين نموذج البرمجة Node.js ووقت تشغيل Azure Functions:
  • نموذج البرمجة: يحدد كيفية تأليف التعليمات البرمجية الخاصة بك وهو خاص ب JavaScript و TypeScript.
  • وقت التشغيل: يحدد السلوك الأساسي لوظائف Azure ويتم مشاركته عبر جميع اللغات.
• يرتبط إصدار نموذج البرمجة ارتباطا صارما بإصدار حزمة @azure/functions npm. تم إصداره بشكل مستقل عن وقت التشغيل. يستخدم كل من وقت التشغيل ونموذج البرمجة الرقم 4 كإصدار رئيسي أحدث، ولكن هذه صدفة.
• لا يمكنك خلط نماذج البرمجة v3 وv4 في نفس تطبيق الوظائف. بمجرد تسجيل وظيفة v4 واحدة في تطبيقك، يتم تجاهل أي وظائف v3 مسجلة في ملفاتfunction.json .

Requirements

يتطلب الإصدار 4 من نموذج البرمجة Node.js الحد الأدنى من الإصدارات التالية:

• @azure/functions حزمة npm v4.0.0
• Node.js v18+
• وقت تشغيل Azure Functions v4.25+
• Azure Functions Core Tools v4.0.5382+ (إذا كان يعمل محليا)

• @azure/functions حزمة npm v4.0.0
• Node.js v18+
• TypeScript v4 +
• وقت تشغيل Azure Functions v4.25+
• Azure Functions Core Tools v4.0.5382+ (إذا كان يعمل محليا)

تضمين حزمة npm

في v4، تحتوي حزمة @azure/functions npm على التعليمات البرمجية المصدر الأساسية التي تدعم نموذج البرمجة Node.js. في الإصدارات السابقة، كان هذا الرمز الذي تم شحنه مباشرة في Azure وحزمة npm يحتوي فقط على أنواع TypeScript. تحتاج الآن إلى تضمين هذه الحزمة لكل من تطبيقات TypeScript وJavaScript. يمكنك تضمين الحزمة لتطبيقات v3 الحالية، ولكنها ليست مطلوبة.

Tip

تأكد من إدراج الحزمة @azure/functions في dependencies القسم (وليس devDependencies) من ملف package.json الخاص بك. يمكنك تثبيت v4 باستخدام الأمر التالي:

npm install @azure/functions

تعيين نقطة إدخال التطبيق

في الإصدار 4 من نموذج البرمجة، يمكنك هيكلة التعليمات البرمجية الخاصة بك كيفما تريد. الملفات الوحيدة التي تحتاجها في جذر تطبيقك هي host.json و package.json.

وإلا، يمكنك تحديد بنية الملف عن طريق تعيين الحقل main في ملف package.json . يمكنك تعيين main الحقل إلى ملف واحد أو ملفات متعددة باستخدام نمط glob. يعرض الجدول التالي أمثلة main على قيم الحقل:

Example	Description
src/index.js	تسجيل الوظائف من ملف جذر واحد.
src/functions/*.js	تسجيل كل دالة من ملفها الخاص.
src/{index.js,functions/*.js}	تركيبة حيث تقوم بتسجيل كل وظيفة من ملفها الخاص، ولكن لا يزال لديك ملف جذر للتعليمات البرمجية العامة على مستوى التطبيق.

Example	Description
dist/src/index.js	تسجيل الوظائف من ملف جذر واحد.
dist/src/functions/*.js	تسجيل كل دالة من ملفها الخاص.
dist/src/{index.js,functions/*.js}	تركيبة حيث تقوم بتسجيل كل وظيفة من ملفها الخاص، ولكن لا يزال لديك ملف جذر للتعليمات البرمجية العامة على مستوى التطبيق.

Tip

تأكد من تحديد main حقل في ملف package.json الخاص بك.

تبديل ترتيب الوسيطات

يعد إدخال المشغل، بدلا من سياق استدعاء، الآن الوسيطة الأولى لمعالج الدالة. سياق استدعاء، الآن الوسيطة الثانية، مبسط في v4 وليس مطلوبا مثل إدخال المشغل. يمكنك تركه متوقفا عن التشغيل إذا كنت لا تستخدمه.

Tip

قم بتبديل ترتيب الوسيطات الخاصة بك. على سبيل المثال، إذا كنت تستخدم مشغل HTTP، فالتبديل (context, request) إلى أو (request, context) فقط (request) إذا كنت لا تستخدم السياق.

تعريف الدالة في التعليمات البرمجية

لم تعد مضطرا إلى إنشاء ملفات تكوين function.json المنفصلة هذه وصيانتها. يمكنك الآن تعريف وظائفك بشكل كامل مباشرة في ملفات TypeScript أو JavaScript. بالإضافة إلى ذلك، تحتوي العديد من الخصائص الآن على إعدادات افتراضية بحيث لا تضطر إلى تحديدها في كل مرة.

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

انقل التكوين من ملف function.json إلى التعليمات البرمجية الخاصة بك. يتوافق نوع المشغل مع أسلوب على app الكائن في النموذج الجديد. على سبيل المثال ، إذا كنت تستخدم نوعا httpTrigger في function.json، فقم باستدعاء app.http() التعليمات البرمجية الخاصة بك لتسجيل الوظيفة. إذا كنت تستخدم timerTrigger، فاتصل ب app.timer().

مراجعة استخدامك للسياق

في الإصدار 4، context يتم تبسيط العنصر لتقليل التكرار وتسهيل اختبارات وحدة الكتابة. على سبيل المثال، قمنا بتبسيط الإدخال والإخراج الأساسيين بحيث يتم الوصول إليها فقط كوسيطة وقيمة إرجاع لمعالج الدالة.

لا يمكنك الوصول إلى المدخلات والمخرجات الأساسية على الكائن context بعد الآن ، ولكن لا يزال يتعين عليك الوصول إلى المدخلات والمخرجات الثانوية على الكائن context . لمزيد من المعلومات حول المدخلات والمخرجات الثانوية، راجع دليل المطور Node.js.

الحصول على الإدخال الأساسي كوسيطة

يطلق على الإدخال الأساسي أيضا اسم المشغل وهو المدخل أو الإخراج الوحيد المطلوب. يجب أن يكون لديك مشغل واحد (وواحد فقط).

v4

يدعم الإصدار 4 طريقة واحدة فقط للحصول على إدخال المشغل، كوسيطة أولى:

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

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

v3

يدعم الإصدار 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;

Tip

تأكد من عدم استخدام context.req أو context.bindings للحصول على الإدخال.

تعيين الإخراج الأساسي كقيمة إرجاع

v4

يدعم الإصدار 4 طريقة واحدة فقط لتعيين الإخراج الأساسي، من خلال القيمة المرجعة:

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

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

v3

يدعم الإصدار 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}!`
};

Tip

تأكد دائما من إرجاع الإخراج في معالج الدالة الخاص بك، بدلا من تعيينه مع context العنصر .

تسجيل السياق

في الإصدار 4، تم نقل أساليب التسجيل إلى الكائن الجذر context كما هو موضح في المثال التالي. لمزيد من المعلومات حول التسجيل، راجع دليل المطور 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');

إنشاء سياق اختبار

لا يدعم الإصدار 3 إنشاء سياق استدعاء خارج وقت تشغيل Azure Functions، لذلك قد تكون اختبارات وحدة التأليف صعبة. يسمح لك الإصدار 4 بإنشاء مثيل لسياق استدعاء، على الرغم من أن المعلومات أثناء الاختبارات غير مفصلة ما لم تقم بإضافتها بنفسك.

v4

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

v3

غير ممكن.

مراجعة استخدامك للأنوع HTTP

أصبحت أنواع طلبات واستجابة HTTP الآن مجموعة فرعية من معيار الجلب. لم تعد فريدة من نوعها ل Azure Functions.

تستخدم الأنواع الحزمة undici في Node.js. تتبع هذه الحزمة معيار الإحضار ويتم دمجها حاليا في Node.js الأساسية.

HttpRequest

v4

• Body. يمكنك الوصول إلى النص الأساسي باستخدام أسلوب خاص بالنوع الذي تريد تلقيه:

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

• معلمة الاستعلام:

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

v3

• Body. يمكنك الوصول إلى النص الأساسي بعدة طرق، ولكن النوع الذي تم إرجاعه غير متسق دائما:

  // 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. يمكنك استرداد رأس بعدة طرق:

  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

v4

• Status:

  return { status: 200 };
  

• Body:

  استخدم الخاصية body لإرجاع معظم الأنواع مثل أو stringBuffer:

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

  استخدم الخاصية jsonBody لأسهل طريقة لإرجاع استجابة JSON:

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

• Header. يمكنك تعيين العنوان بطريقتين، اعتمادا على ما إذا كنت تستخدم HttpResponse الفئة أو الواجهة HttpResponseInit :

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

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

v3

• Status. يمكنك تعيين حالة بعدة طرق:

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

• Body. يمكنك تعيين نص بعدة طرق وهو نفسه بغض النظر عن نوع الجسم (string، Bufferكائن JSON، وما إلى ذلك):

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

• Header. يمكنك تعيين رأس بعدة طرق:

  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

قم بتحديث أي منطق باستخدام طلب HTTP أو أنواع الاستجابة لمطابقة الأساليب الجديدة.

Tip

قم بتحديث أي منطق باستخدام طلب HTTP أو أنواع الاستجابة لمطابقة الأساليب الجديدة. يجب أن تحصل على أخطاء إنشاء TypeScript لمساعدتك في تحديد ما إذا كنت تستخدم أساليب قديمة.

Troubleshoot

راجع دليل استكشاف الأخطاء وإصلاحها Node.js.