التعامل مع التبعيات

يُسمح للدالة باستخدام وحدات Node.js الخارجية بالإضافة إلى data المحلية. تتم إدارة الملحقات في Node.js باستخدام npm ويتم التعبير عنها في ملف بيانات وصفية يُسمى package.json. تتوافق بيئات التشغيل Node.js في Cloud Functions مع التثبيت باستخدام npm أو yarn أو pnpm.

لتحديد تبعية لدالة معيّنة، أضِفها إلى ملف package.json.

في هذا المثال، يتم إدراج تبعية في ملف package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

بعد ذلك، يتم استيراد التبعية في الدالة:

JavaScript

const escapeHtml = require('escape-html');

// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

TypeScript

import * as escapeHtml from 'escape-html';

// Return a greeting with the input HTML-escaped.
export let hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
}

تضمين وحدات Node.js المحلية

يمكنك أيضًا تضمين وحدات Node.js المحلية كجزء من الدالة. يمكنك تحقيق ذلك من خلال الإعلان عن وحدتك في package.json باستخدام البادئة file:. في المثال التالي، يشير mymodule إلى اسم الوحدة وmymoduledir هو الدليل الذي يحتوي على وحدتك:

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

يجب تخزين رمز هذه الوحدة المحلية في مكان آخر غير مجلد node_modules ضمن الدليل الجذر لوظيفتك.

خطوات إضافية لـ TypeScript

يساعدك TypeScript على نحوٍ كبير عند استخدام مكتبات تحتوي على معلومات عن النوع. يتيح ذلك لـ TypeScript رصد الأخطاء في البنية ويسمح للمحرِّرين بتقديم اقتراحات أفضل لميزة completing. يتم شحن بعض المكتبات، مثل firebase-admin و firebase-functions، مع تضمين تعريفات TypeScript.

لا توفّر العديد من المكتبات تعريفًا خاصًا بها في TypeScript. يقدّم مشروع DefinitelyTyped تعريفات يشرف عليها المنتدى لمكتبات node الأكثر رواجًا. تنشر DefinitelyTyped هذه التعريفات ضمن اسم حزمة NPM نفسه، ولكن داخل مؤسسة "‎@types". على سبيل المثال، يمكنك تثبيت معلومات نوع مكتبة uuid باستخدام ما يلي:

npm install @types/uuid

عندما تصبح أكثر درايةً بـ TypeScript، قد تحتاج إلى دمج كلتا عمليتَي التثبيت:

npm install uuid @types/uuid

يجب أن تكون تبعيات النوع من النوع نفسه مثل تبعية المكتبة. على سبيل المثال، يجب عدم حفظ uuid كتبعية عادية و@types/uuid كتبعية مطوّر أو تبعية نظير.

تحميل وحدات Node.js

استخدِم دالة Node.js require() لتحميل أي وحدة Node.js ثبّتها. يمكنك أيضًا استخدام دالة require() لاستيراد الملفات المحلية التي يتم نشرها مع الدالة.

إذا كنت تكتب وظائف في TypeScript، استخدِم العبارة import بالطريقة نفسها لتحميل أي وحدة Node.js ثبّتها.

استخدام الوحدات الخاصة

يمكنك استخدام وحدة npm خاصة من خلال توفير إعدادات للمصادقة مع قاعدة بيانات المسجّلين في ملف .npmrc في دليل الدالة. إذا كنت تستخدم الإصدار 2 من Yarn أو إصدارًا أحدث كمدير حِزم، يكون اسم هذا الملف هو .yarnrc.yml.

الوحدات الخاصة من Artifact Registry

يمكن أن يستضيف مستودع حِزم Node.js في Artifact Registry وحدات خاصة لدالة. عند نشر دالة Google Cloud Functions ، تنشئ عملية الإنشاء تلقائيًا بيانات اعتماد Artifact Registry لحساب خدمة Cloud Build. ما عليك سوى إدراج مستودع Artifact Registry في .npmrc بدون إنشاء بيانات اعتماد إضافية. على سبيل المثال:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

يعمل هذا الأسلوب أيضًا مع مدير الحِزم Yarn v1. إذا كنت تستخدم الإصدار 2 من Yarn أو إصدارًا أحدث، ما عليك سوى إدراج مستودع Artifact Registry في .yarnrc.yml بدون بيانات اعتماد إضافية. على سبيل المثال:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

الوحدات الخاصة من مستودعات أخرى

توضّح مستندات npm كيفية إنشاء علامات تشكل رمزًا مخصّصًا للوصول للقراءة فقط. لا ننصح باستخدام ملف .npmrc الذي تم إنشاؤه في الدليل home لأنّه يحتوي على رمز مميّز للقراءة والكتابة. لا يُشترط استخدام أذونات الكتابة أثناء عملية النشر، وقد تشكل خطرًا على الأمان.

لا تُدرِج ملف .npmrc إذا كنت لا تستخدم مستودعات خاصة، لأنّ ذلك قد يؤدي إلى زيادة وقت نشر وظائفك.

تنسيق الملف

إذا كنت تستخدِم ملف .npmrc لضبط رمز مميّز مخصّص لتأكيد الهوية، يجب أن يتضمّن السطر الموضّح أدناه.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

استبدال:

REGISTRY_DOMAIN: اسم نطاق قاعدة بيانات مسجّلين npm الخاصة بك. إذا كان مستودعك مستضافًا على npmjs.org، اضبط هذا الحقل علىregistry.npmjs.org.
AUTH_TOKEN: الرمز المميّز للتفويض في سجلّ npm. يمكن أن يكون ذلك القيمة النصية الحرفية للعنصر النائب أو السلسلة النصية ${NPM_TOKEN}، التي تستبدلها npm بقيمة العنصر النائب الفعلية من البيئة.

يمكنك ضبط متغيّر البيئة $NPM_TOKEN باستخدام الوسيطة --set-build-env-vars في الأمر gcloud functions deploy. اطّلِع على الدليل التعليمي لـ NPM حول الوحدات الخاصة لمزيد من التفاصيل عن الرمز المميّز لاعتماد NPM.

إنشاء الدالة باستخدام تبعيات مزوّدة بمعلومات عن المورّد

التبعيات التي يقدّمها المورّدون هي تلك التي يتم تضمين مصدرها مباشرةً في حزمة رمز المصدر وإعادة إنشائها إلى جانب رمزك البرمجي. يمكنك إنشاء ملحقَات Node.js التي يقدّمها المورّد وتخطّي تثبيتها أثناء النشر باستخدام متغيّر بيئة الإنشاء GOOGLE_VENDOR_NPM_DEPENDENCIES.

المتطلبات الأساسية للعناصر التابعة التابعة لمورّد معيّن

تأكَّد من أنّ لديك دالة صالحة تتضمّن جميع التبعيات التي تريد أن يحدّدها المورّد في ملف package.json.
ثبِّت هذه التبعيات محليًا من خلال تشغيل
```
    npm install
```
أزِل node_modules من ملف ‎ .gcloudignore في دليل العمل.
يمكنك نشر الدالة، مع التأكّد من أنّ إصدار Node.js على الجهاز هو نفسه الإصدار الذي تحدّده أثناء عملية النشر.
يمكنك نشر الدالة والموارد الخارجية التابعة للجهة الخارجية باستخدام العبارة التالية:
```
  gcloud functions deploy FUNCTION_NAME \
    --runtime RUNTIME_NAME \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
```
استبدال:
- FUNCTION_NAME: اسم دالة Cloud Functions التي يتم نشرها
- RUNTIME_NAME: اسم وقت تشغيل Node.js لتشغيل الدالة المنشورة يجب أن يكون هذا هو إصدار Node.js نفسه الذي استخدمته في بيئة التطوير المحلي.

حزمة إطار عمل Functions هي عنصر تابع مطلوب للدوالّ. لإنشاء حِزم أسرع، ننصحك بإضافة هذه الحزمة إلى قائمة المورّدين. وإذا لم تفعل ذلك، سيتم تنزيله وتركيبه عند إنشاء الدالة.

في حال تحديد محرّك npm في ملف package.json، يتم تنزيل الإصدار المحدّد من npm في وقت الإنشاء. لإيقاف هذا السلوك، أزِل هذا العنصر من ملف package.json.