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


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

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

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

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

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

JavaScript

const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

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

TypeScript

import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = 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 رصد أخطاء البنية، كما يتيح للمحرِّرات تقديم اقتراحات أفضل للإكمال التلقائي. تتضمّن بعض المكتبات، مثل 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 الذي تم إنشاؤه في دليل الصفحة الرئيسية لأنّه يحتوي على رمز مميّز للقراءة والكتابة. لا تكون أذونات الكتابة مطلوبة أثناء عملية النشر، وقد تشكّل خطرًا أمنيًا.

لا تضمِّن ملف .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.