تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

Node.js

يُسمح للدالة باستخدام وحدات 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 في دليل الدالة. إذا كنت تستخدم Yarn v2 أو إصدارًا أحدث كمدير للحِزم، يُطلق على هذا الملف اسم .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. إذا كنت تستخدم Yarn v2 أو إصدارًا أحدث، ما عليك سوى إدراج مستودع 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.

Python

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

لا تتوفّر مواصفات التبعية باستخدام معيار 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 إلى الإنترنت مقيّدًا.

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

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

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

# Code in main.py
from localpackage import script

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