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

اختيار اللغة:

‫Node.js Python

يمكن أن تستخدم دالة Cloud Functions الوحدات الخارجية والتبعيات المحلية. تعتمد طريقة تحديد التبعيات وإدارتها على لغة وقت التشغيل.

Node.js

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

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

ملاحظة: إذا تم العثور على ملف package-lock.json أو yarn.lock أو pnpm-lock.yaml ضمن مشروعك، سيتم أخذ ملف التأمين هذا في الاعتبار عند تثبيت التبعيات باستخدام npm ci أو yarn install أو pnpm install.

في هذا المثال، يتم إدراج تبعية في ملف 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 ضمن الدليل الجذر لدالتك.

ملاحظة: تتجاهل Firebase CLI مجلد 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 في دليل الدالة. إذا كنت تستخدم Yarn الإصدار 2 أو إصدارًا أحدث كأداة لإدارة الحِزم، يُسمى هذا الملف .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 الإصدار 1. إذا كنت تستخدم Yarn الإصدار 2 أو إصدارًا أحدث، ما عليك سوى إدراج مستودع Artifact Registry في .yarnrc.yml بدون بيانات اعتماد إضافية. على سبيل المثال:

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

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

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

لا تضمِّن ملف .npmrc إذا كنت لا تستخدم مستودعات خاصة، لأنّه يمكن أن يزيد من وقت نشر الدوال.

ملاحظة: إذا كنت تستخدم أي أذونات مخصّصة (مثل الأذونات اللازمة لـ VPC)، تأكَّد من السماح لدوالك بالوصول إلى المستودع الخاص المستهدف بشكلٍ صريح.

تنسيق الملف

إذا كنت تستخدم ملف .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.

---

Python

هناك طريقتان لتحديد التبعيات في Cloud Functions المكتوبة بلغة Python: استخدام ملف pip لأداة إدارة الحِزم requirements.txt أو تجميع التبعيات المحلية بجانب دالتك.

لا يتمّ استخدام مواصفات التبعية باستخدام معيار Pipfile/Pipfile.lock. يجب ألا يتضمّن مشروعك هذه الملفات.

تحديد التبعيات باستخدام pip

تتم إدارة التبعيات في Python باستخدام pip ويتم التعبير عنها في ملف بيانات وصفية يُسمى requirements.txt. يجب أن يكون هذا الملف في الدليل نفسه الذي يحتوي على ملف main.py الذي يتضمّن رمز الدالة.

عند نشر دالتك أو إعادة نشرها، تستخدم Cloud Functions أداة pip لتنزيل أحدث إصدار من التبعيات وتثبيته كما هو موضّح في ملف requirements.txt. يحتوي ملف requirements.txt على سطر واحد لكل حزمة. يحتوي كل سطر على اسم الحزمة، ويمكن أن يحتوي اختياريًا على الإصدار المطلوب. لمزيد من التفاصيل، راجِع المرجعrequirements.txt.

لمنع تأثّر عملية الإنشاء بالتغييرات في إصدار الاعتمادية، ننصحك بتثبيت حِزم الاعتمادية على إصدار معيّن.

في ما يلي مثال على ملف requirements.txt:

functions-framework
requests==2.20.0
numpy

تجميع التبعيات المحلية

يمكنك أيضًا تجميع التبعيات ونشرها بجانب دالتك. تكون هذه الطريقة مفيدة إذا لم تكن التبعية متاحة من خلال أداة إدارة الحِزم pip أو إذا كان الوصول إلى الإنترنت في بيئة Cloud Functions محدودًا.

ملاحظة: يمكنك الاستمرار في استخدام requirements.txt ملف لتحديد التبعيات الإضافية التي لم يتم تجميعها بجانب دالتك.

على سبيل المثال، يمكنك استخدام بنية دليل مثل ما يلي:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

يمكنك بعد ذلك استيراد الرمز كالمعتاد من localpackage باستخدام عبارة import التالية.

# Code in main.py
from localpackage import script

يُرجى العِلم أنّ هذه الطريقة لن تُشغّل أي ملفات setup.py. لا يزال بإمكانك تجميع الحِزم التي تحتوي على هذه الملفات، ولكن قد لا يتم تشغيلها بشكلٍ صحيح على Cloud Functions.