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

ضبط البيئة

ستحتاج غالبًا إلى ضبط إعدادات إضافية لدوالك، مثل مفاتيح واجهة برمجة التطبيقات التابعة لجهات خارجية أو الإعدادات القابلة للتعديل. توفّر حزمة تطوير البرامج (SDK) لـ Firebase في Cloud Functions إعدادات بيئة مدمجة لتسهيل تخزين هذا النوع من البيانات واستردادها لمشروعك.

ويمكنك الاختيار من بين ما يلي:

الإعدادات المستندة إلى المَعلمات (يُنصح بها لمعظم السيناريوهات). يتيح ذلك ضبط بيئة قوية من خلال مَعلمات يتم التحقّق من صحتها في وقت النشر، ما يمنع الأخطاء ويسهّل تصحيح الأخطاء.
إعداد متغيّرات البيئة المستند إلى الملفات باستخدام هذا النهج، يمكنك إنشاء ملف dotenv يدويًا لتحميل متغيرات البيئة.

بالنسبة إلى معظم حالات الاستخدام، يُنصح باستخدام الإعدادات المستندة إلى المَعلمات. تتيح هذه الطريقة قيم الإعدادات في وقت التشغيل ووقت النشر، ويتم حظر النشر ما لم تكن جميع المَعلمات تحتوي على قيمة صالحة. في المقابل، لا تتوفّر الإعدادات التي تستخدم متغيّرات البيئة في وقت النشر.

الإعدادات المستندة إلى مَعلمات

توفّر Cloud Functions for Firebase واجهة لتحديد مَعلمات الإعدادات بشكل تعريفي داخل قاعدة الرموز البرمجية. تتوفّر قيمة هذه المَعلمات أثناء نشر الدالة، عند ضبط خيارات النشر ووقت التشغيل، وأثناء التنفيذ. هذا يعني أنّ واجهة سطر الأوامر ستحظر عملية النشر ما لم تكن جميع المَعلمات تحتوي على قيمة صالحة.

Node.js

const { onRequest } = require('firebase-functions/v2/https');
const { defineInt, defineString } = require('firebase-functions/params');

// Define some parameters
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
const welcomeMessage = defineString('WELCOME_MESSAGE');

// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = onRequest(
  { minInstances: minInstancesConfig },
(req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

Python

from firebase_functions import https_fn
from firebase_functions.params import IntParam, StringParam

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")
WELCOME_MESSAGE = StringParam("WELCOME_MESSAGE")

# To use configured parameters inside the config for a function, provide them
# directly. To use them at runtime, call .value() on them.
@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    return https_fn.Response(f'{WELCOME_MESSAGE.value()}! I am a function!')

عند نشر دالة باستخدام متغيّرات إعدادات ذات مَعلمات، يحاول Firebase CLI أولاً تحميل قيمها من ملفات ‎ .env المحلية. إذا لم تكن هذه القيم متوفّرة في تلك الملفات ولم يتم ضبط default، ستطلب واجهة سطر الأوامر (CLI) القيم أثناء عملية النشر، ثم ستحفظها تلقائيًا في ملف .env باسم .env.<project_ID> في دليل functions/:

$ firebase deploy
i  functions: preparing codebase default for deployment
? Enter a string value for ENVIRONMENT: prod
i  functions: Writing new parameter values to disk: .env.projectId
…
$ firebase deploy
i  functions: Loaded environment variables from .env.projectId

استنادًا إلى سير عمل التطوير، قد يكون من المفيد إضافة ملف .env.<project_ID> الذي تم إنشاؤه إلى نظام التحكّم في الإصدارات.

استخدام المَعلمات في النطاق العام

أثناء عملية النشر، يتم تحميل رمز الدوال وفحصه قبل أن تحصل المَعلمات على قيم فعلية. وهذا يعني أنّ جلب قيم المَعلمات أثناء النطاق العام يؤدي إلى تعذُّر النشر. في الحالات التي تريد فيها استخدام مَعلمة لإعداد قيمة عامة، استخدِم دالة ردّ الاتصال للإعداد onInit(). يتم تشغيل رد الاتصال هذا قبل تشغيل أي دوال في مرحلة الإنتاج، ولكن لا يتم استدعاؤه أثناء وقت النشر، لذا فهو مكان آمن للوصول إلى قيمة المَعلمة.

Node.js

const { GoogleGenerativeAI } = require('@google/generative-ai');
const { defineSecret } = require('firebase-functions/params');
const { onInit } = require('firebase-functions/v2/core');

const apiKey = defineSecret('GOOGLE_API_KEY');

let genAI;
onInit(() => {
  genAI = new GoogleGenerativeAI(apiKey.value());
})

Python

from firebase_functions.core import init
from firebase_functions.params import StringParam, PROJECT_ID
import firebase_admin
import vertexai

location = StringParam("LOCATION")

x = "hello"

@init
def initialize():
  # Note: to write back to a global, you'll need to use the "global" keyword
  # to avoid creating a new local with the same name.
  global x
  x = "world"
  firebase_admin.initialize_app()
  vertexai.init(PROJECT_ID.value, location.value)

إذا كنت تستخدم مَعلمات من النوع Secret، يُرجى العِلم أنّها لا تتوفّر إلا في عملية الدوال التي ربطت الرمز السري. إذا كان الرمز السرّي مرتبطًا ببعض الدوال فقط، يُرجى التحقّق مما إذا كانت قيمة secret.value() خاطئة قبل استخدامه.

ضبط سلوك واجهة سطر الأوامر

يمكن ضبط المَعلمات باستخدام عنصر Options يتحكّم في كيفية طلب واجهة سطر الأوامر (CLI) للقيم. يضبط المثال التالي الخيارات للتحقّق من صحة تنسيق رقم الهاتف، ولتوفير خيار تحديد بسيط، ولتعبئة خيار تحديد تلقائيًا من مشروع Firebase:

Node.js

const { defineString } = require('firebase-functions/params');

const welcomeMessage = defineString('WELCOME_MESSAGE', {default: 'Hello World',
description: 'The greeting that is returned to the caller of this function'});

const onlyPhoneNumbers = defineString('PHONE_NUMBER', {
  input: {
    text: {
      validationRegex: /\d{3}-\d{3}-\d{4}/,
      validationErrorMessage: "Please enter
a phone number in the format XXX-YYY-ZZZZ"
    },
  },
});

const selectedOption = defineString('PARITY', {input: params.select(["odd", "even"])});

const memory = defineInt("MEMORY", {
  description: "How much memory do you need?",
  input: params.select({ "micro": 256, "chonky": 2048 }),
});

const extensions = defineList("EXTENSIONS", {
  description: "Which file types should be processed?",
  input: params.multiSelect(["jpg", "tiff", "png", "webp"]),
});

const storageBucket = defineString('BUCKET', {
  description: "This will automatically
populate the selector field with the deploying Cloud Project’s
storage buckets",
  input: params.PICK_STORAGE_BUCKET,
});

Python

from firebase_functions.params import (
    StringParam,
    ListParam,
    TextInput,
    SelectInput,
    SelectOptions,
    ResourceInput,
    ResourceType,
)

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")

WELCOME_MESSAGE = StringParam(
    "WELCOME_MESSAGE",
    default="Hello World",
    description="The greeting that is returned to the caller of this function",
)

ONLY_PHONE_NUMBERS = StringParam(
    "PHONE_NUMBER",
    input=TextInput(
        validation_regex="\d{3}-\d{3}-\d{4}",
        validation_error_message="Please enter a phone number in the format XXX-YYY-XXX",
    ),
)

SELECT_OPTION = StringParam(
    "PARITY",
    input=SelectInput([SelectOptions(value="odd"), SelectOptions(value="even")]),
)

STORAGE_BUCKET = StringParam(
    "BUCKET",
    input=ResourceInput(type=ResourceType.STORAGE_BUCKET),
    description="This will automatically populate the selector field with the deploying Cloud Project's storage buckets",
)

أنواع المعلّمات

توفّر الإعدادات المستندة إلى المَعلمات كتابة قوية لقيم المَعلمات، وتتيح أيضًا استخدام الرموز السرية من Cloud Secret Manager. الأنواع المتوافقة هي:

سري
سلسلة
قيمة منطقية
عدد صحيح
عائم
List (Node.js)
JSON Secret (Node.js)

يمكنك الاطّلاع على مرجع مساحة الاسم params للحصول على معلومات عن الدوال الخاصة بتحديد المَعلمات.

قيم المَعلمات والتعبيرات

يقيّم Firebase المَعلمات أثناء النشر وأثناء تنفيذ الدالة. بسبب هاتين البيئتين، يجب توخي بعض الحذر عند مقارنة قيم المَعلمات وعند استخدامها لضبط خيارات وقت التشغيل للدوال.

لتمرير مَعلمة إلى الدالة كخيار وقت التشغيل، مرِّرها مباشرةً:

Node.js

const { onRequest } = require('firebase-functions/v2/https');
const { defineInt } = require('firebase-functions/params');
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');

export const helloWorld = onRequest(
  { minInstances: minInstancesConfig },
  (req, res) => {
    //…

Python

from firebase_functions import https_fn
from firebase_functions.params import IntParam

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")

@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    ...

بالإضافة إلى ذلك، إذا كنت بحاجة إلى المقارنة مع مَعلمة لمعرفة الخيار الذي يجب تحديده، عليك استخدام المقارِنات المضمّنة بدلاً من التحقّق من القيمة:

Node.js

const { onRequest } = require('firebase-functions/v2/https');
const environment = params.defineString(‘ENVIRONMENT’, {default: 'dev'});

// use built-in comparators
const minInstancesConfig = environment.equals('PRODUCTION').thenElse(10, 1);
export const helloWorld = onRequest(
  { minInstances: minInstancesConfig },
  (req, res) => {
    //…

Python

from firebase_functions import https_fn
from firebase_functions.params import IntParam, StringParam

ENVIRONMENT = StringParam("ENVIRONMENT", default="dev")
MIN_INSTANCES = ENVIRONMENT.equals("PRODUCTION").then(10, 0)

@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    ...

يمكن الوصول إلى المَعلمات وتعبيرات المَعلمات التي يتم استخدامها فقط في وقت التشغيل من خلال دالة value:

Node.js

const { onRequest } = require('firebase-functions/v2/https');
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE');

// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = onRequest(
(req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

Python

from firebase_functions import https_fn
from firebase_functions.params import StringParam

WELCOME_MESSAGE = StringParam("WELCOME_MESSAGE")

@https_fn.on_request()
def hello_world(req):
    return https_fn.Response(f'{WELCOME_MESSAGE.value()}! I am a function!')

المَعلمات المضمّنة

توفّر حزمة تطوير البرامج (SDK) الخاصة بـ Cloud Functions ثلاث مَعلمات محدّدة مسبقًا، وهي متاحة من الحزمة الفرعية firebase-functions/params:

Node.js

‫projectID: مشروع على السحابة الإلكترونية الذي يتم تشغيل الدالة فيه
‫databaseURL: عنوان URL لمثيل قاعدة بيانات الوقت الفعلي المرتبط بالدالة (في حال تفعيله في مشروع Firebase)
‫storageBucket: حزمة Cloud Storage المرتبطة بالدالة (في حال تفعيلها في مشروع Firebase)

Python

‫PROJECT_ID: مشروع على السحابة الإلكترونية الذي يتم تشغيل الدالة فيه
‫DATABASE_URL: عنوان URL لمثيل قاعدة بيانات الوقت الفعلي المرتبط بالدالة (في حال تفعيله في مشروع Firebase)
‫STORAGE_BUCKET: حزمة Cloud Storage المرتبطة بالدالة (في حال تفعيلها في مشروع Firebase)

تعمل هذه المَعلمات مثل مَعلمات السلسلة التي يحدّدها المستخدم من جميع النواحي، باستثناء أنّه بما أنّ قيمها معروفة دائمًا لواجهة سطر أوامر Firebase، لن تتم المطالبة بقيمها مطلقًا عند النشر ولن يتم حفظها في ملفات .env.

المَعلمات السرية

تمثّل المَعلمات من النوع Secret، المحدّدة باستخدام defineSecret()، مَعلمات سلسلة لها قيمة مخزّنة في Cloud Secret Manager. بدلاً من التحقّق من ملف .env محلي وكتابة قيمة جديدة في الملف في حال عدم توفّرها، تتحقّق المَعلمات السرية من توفّرها في Cloud Secret Manager، وتطلب بشكل تفاعلي قيمة مفتاح سرّي جديد أثناء عملية النشر.

يجب ربط المَعلمات السرية بالدوال الفردية التي يجب أن يكون لديها إذن الوصول إليها:

Node.js

const { onRequest } = require('firebase-functions/v2/https');
const { defineSecret } = require('firebase-functions/params');
const discordApiKey = defineSecret('DISCORD_API_KEY');

export const postToDiscord = onRequest(
  { secrets: [discordApiKey] },
  (req, res) => {
  const apiKey = discordApiKey.value();
    //…

Python

from firebase_functions import https_fn
from firebase_functions.params import SecretParam

DISCORD_API_KEY = SecretParam('DISCORD_API_KEY')

@https_fn.on_request(secrets=[DISCORD_API_KEY])
def post_to_discord(req):
    api_key = DISCORD_API_KEY.value

بما أنّ قيم البيانات السرية تكون مخفية إلى أن يتم تنفيذ الدالة، لا يمكنك استخدامها أثناء ضبط الدالة.

أسرار JSON المنظَّمة

إذا كانت لديك قيم ضبط متعددة مرتبطة منطقيًا (على سبيل المثال، إعدادات خدمة تابعة لجهة خارجية)، يمكنك تخزينها معًا ككائن JSON منظَّم ضمن بيانات سرية واحدة باستخدام defineJsonSecret(). يمكن أن يساعد هذا النهج في تنظيم الإعدادات والاستفادة بشكل أكثر كفاءة من الفئة المجانية في Cloud Secret Manager من خلال تخزين مجموعة من قيم الإعدادات ذات الصلة في رمز سري واحد.

يجب أن تكون القيمة المخزّنة في Secret Manager سلسلة JSON صالحة. ستحلّل حزمة تطوير البرامج (SDK) تلقائيًا سلسلة JSON إلى كائن JavaScript عند الوصول إلى .value().

مثال:

const { onRequest } = require('firebase-functions/v2/https');
const { defineJsonSecret } = require('firebase-functions/params');

// Define a single secret to hold all configuration for some API
const someApiConfig = defineJsonSecret('SOMEAPI_CONFIG');

exports.myApi = onRequest(
  { secrets: [someApiConfig] },
  (req, res) => {
    // someApiConfig.value() automatically parses the JSON secret
    const { apiKey, webhookSecret, clientId } = someApiConfig.value();

    // Now you can use apiKey, webhookSecret, clientId
    // ...
  }
);

لإنشاء رمز SOMEAPI_CONFIG السرّي، عليك ضبط قيمته في Secret Manager على سلسلة JSON مثل:

{
  "apiKey": "key_...",
  "webhookSecret": "secret_...",
  "clientId": "client_..."
}

إذا لم تكن قيمة المفتاح السري بتنسيق JSON صالح، سيؤدي الوصول إلى someApiConfig.value() إلى ظهور خطأ أثناء التشغيل.

متغيّرات البيئة

يتيح Cloud Functions for Firebase استخدام تنسيق ملف dotenv لتحميل متغيّرات البيئة المحدّدة في ملف .env إلى وقت تشغيل التطبيق. بعد نشر المتغيّرات البيئية، يمكن قراءتها من خلال واجهة process.env (في المشاريع المستندة إلى Node.js) أو os.environ (في المشاريع المستندة إلى Python).

لضبط بيئتك بهذه الطريقة، أنشئ ملف .env في مشروعك، وأضِف المتغيّرات المطلوبة، ثم انشرها:

أنشِئ ملف .env في دليل functions/:

# Directory layout:
#   my-project/
#     firebase.json
#     functions/
#       .env
#       package.json
#       index.js

افتح ملف .env لتعديله، وأضِف المفاتيح المطلوبة. على سبيل المثال:
```
PLANET=Earth
AUDIENCE=Humans
```

انشر الدوال وتحقَّق من تحميل متغيّرات البيئة:

firebase deploy --only functions
# ...
# i functions: Loaded environment variables from .env.
# ...

بعد نشر متغيّرات البيئة المخصّصة، يمكن لرمز الدالة الوصول إليها:

Node.js

// Responds with "Hello Earth and Humans"
exports.hello = onRequest((request, response) => {
  response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});

Python

import os

@https_fn.on_request()
def hello(req):
    return https_fn.Response(
        f"Hello {os.environ.get('PLANET')} and {os.environ.get('AUDIENCE')}"
    )

نشر مجموعات متعددة من متغيرات البيئة

إذا كنت بحاجة إلى مجموعة بديلة من متغيرات البيئة لمشاريع Firebase (مثل التقسيم المرحلي مقابل الإنتاج)، فأنشئ ملف .env.<project or alias> واكتب متغيرات البيئة الخاصة بالمشروع هناك. سيتم تضمين متغيّرات البيئة من ملفات .env و.env الخاصة بالمشروع (في حال توفّرها) في جميع الدوال المنشورة.

على سبيل المثال، يمكن أن يتضمّن المشروع هذه الملفات الثلاثة التي تحتوي على قيم مختلفة قليلاً للتطوير والإنتاج:

`.env`	`.env.dev`	`.env.prod`
PLANET=Earth AUDIENCE=Humans	AUDIENCE=Dev Humans	AUDIENCE=Prod Humans

بناءً على القيم في هذه الملفات المنفصلة، ستختلف مجموعة متغيّرات البيئة التي يتم نشرها مع الدوال حسب المشروع المستهدَف:

$ firebase use dev
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.dev.
# Deploys functions with following user-defined environment variables:
#   PLANET=Earth
#   AUDIENCE=Dev Humans

$ firebase use prod
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.prod.
# Deploys functions with following user-defined environment variables:
#   PLANET=Earth
#   AUDIENCE=Prod Humans

متغيّرات البيئة المحجوزة

بعض مفاتيح متغيرات البيئة محجوزة للاستخدام الداخلي. لا تستخدم أيًا من هذه المفاتيح في ملفات .env:

جميع المفاتيح التي تبدأ بـ X_GOOGLE_
جميع المفاتيح التي تبدأ بـ EXT_‎
جميع المفاتيح التي تبدأ بـ FIREBASE_‎
أي مفتاح من القائمة التالية:
CLOUD_RUNTIME_CONFIG
ENTRY_POINT
GCP_PROJECT
GCLOUD_PROJECT
GOOGLE_CLOUD_PROJECT
FUNCTION_TRIGGER_TYPE
FUNCTION_NAME
FUNCTION_MEMORY_MB
FUNCTION_TIMEOUT_SEC
FUNCTION_IDENTITY
FUNCTION_REGION
FUNCTION_TARGET
FUNCTION_SIGNATURE_TYPE
K_SERVICE
K_REVISION
PORT
K_CONFIGURATION

تخزين معلومات الإعدادات الحساسة والوصول إليها

يمكن استخدام متغيّرات البيئة المخزَّنة في ملفات .env لضبط الدوال، ولكن لا يُنصح باعتبارها طريقة آمنة لتخزين المعلومات الحسّاسة، مثل بيانات اعتماد قاعدة البيانات أو مفاتيح واجهة برمجة التطبيقات. ويُعدّ ذلك مهمًا على وجه الخصوص إذا كنت تتحقّق من ملفات .env في نظام التحكّم بالمصادر.

لمساعدتك في تخزين معلومات الإعدادات الحساسة، يتكامل Cloud Functions for Firebase مع Google Cloud Secret Manager. تخزّن هذه الخدمة المشفّرة قيم الإعدادات بأمان، مع السماح بالوصول إليها بسهولة من الدوال عند الحاجة.

إنشاء بيانات سرية واستخدامها

لإنشاء بيانات سرية، استخدِم واجهة سطر الأوامر (CLI) في Firebase.

لإنشاء رمز سرّي واستخدامه:

من جذر دليل مشروع على جهاز المستخدم، نفِّذ الأمر التالي:
```
firebase functions:secrets:set SECRET_NAME
```
أدخِل قيمة لـ SECRET_NAME.

تعرض واجهة سطر الأوامر رسالة نجاح وتحذيرًا بأنّه عليك نشر الدوال لتطبيق التغيير.

قبل النشر، تأكَّد من أنّ رمز الدوال يسمح للدالة بالوصول إلى البيانات السرية باستخدام الخيار secrets:

Node.js

const { onRequest } = require('firebase-functions/v2/https');

exports.processPayment = onRequest(
  { secrets: ["SECRET_NAME"] },
  (req, res) => {
    const myBillingService = initializeBillingService(
      // reference the secret value
      process.env.SECRET_NAME
    );
    // Process the payment
  }
);

Python

import os
from firebase_functions import https_fn

@https_fn.on_request(secrets=["SECRET_NAME"])
def process_payment(req):
    myBillingService = initialize_billing(key=os.environ.get('SECRET_NAME'))
    # Process the payment
    ...

نشر Cloud Functions:

firebase deploy --only functions

يمكنك الآن الوصول إليه مثل أي متغيّر بيئة آخر. في المقابل، إذا حاولت دالة أخرى لا تحدّد البيانات السرية الوصول إليها، ستتلقّى قيمة غير محدّدة:

Node.js

exports.anotherEndpoint = onRequest((request, response) => {
  response.send(`The secret API key is ${process.env.SECRET_NAME}`);
  // responds with "The secret API key is undefined" because the `secrets` option is missing
});

Python

@https_fn.on_request()
def another_endpoint(req):
    return https_fn.Response(f"The secret API key is {os.environ.get("SECRET_NAME")}")
    # Responds with "The secret API key is None" because the `secrets` parameter is missing.

بعد نشر الدالة، ستتمكّن من الوصول إلى قيمة البيانات السرية. Only functions that specifically include a secret in their secrets option will have access to that secret as an environment variable. يساعدك ذلك في التأكّد من أنّ القيم السرية متاحة فقط عند الحاجة إليها، ما يقلّل من خطر تسرُّبها عن طريق الخطأ.

إدارة المفاتيح السرّية

استخدِم واجهة سطر الأوامر (CLI) في Firebase لإدارة بياناتك السرية. عند إدارة البيانات السرية بهذه الطريقة، يُرجى العِلم أنّ بعض التغييرات في واجهة سطر الأوامر تتطلّب منك تعديل و/أو إعادة نشر الدوال المرتبطة بها. ونخصّ بالذكر الشرط التالي:

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

في ما يلي ملخّص لأوامر واجهة سطر الأوامر في Firebase لإدارة البيانات السرية:

# Change the value of an existing secret
firebase functions:secrets:set SECRET_NAME

# Set secret from file
firebase functions:secrets:set SECRET_NAME --data-file file.json

# Validate secret value as json
cat file.json | firebase functions:secrets:set SECRET_NAME --format=json

# Pipe from stdin and set secret
cat file.json | firebase functions:secrets:set SECRET_NAME --format=json

# View the value of a secret
functions:secrets:access SECRET_NAME

# Destroy a secret
functions:secrets:destroy SECRET_NAME

# View all secret versions and their state
functions:secrets:get SECRET_NAME

# Automatically clean up all secrets that aren't referenced by any of your functions
functions:secrets:prune

بالنسبة إلى الأمرَين access وdestroy، يمكنك تقديم مَعلمة الإصدار الاختيارية لإدارة إصدار معيّن. على سبيل المثال:

functions:secrets:access SECRET_NAME[@VERSION]

لمزيد من المعلومات حول هذه العمليات، يمكنك تمرير -h مع الأمر لعرض مساعدة واجهة سطر الأوامر.

كيفية فوترة المفاتيح السرية

تسمح Secret Manager باستخدام 6 إصدارات سرية نشطة بدون أي تكلفة. هذا يعني أنّه يمكنك الحصول على 6 بيانات سرية شهريًا في مشروع Firebase بدون أي تكلفة.

بشكل تلقائي، تحاول واجهة سطر الأوامر Firebase تدمير نُسخ الرموز السرية غير المستخدَمة تلقائيًا عند الاقتضاء، مثلاً عند نشر دوال باستخدام نسخة جديدة من الرمز السري. يمكنك أيضًا تنظيف الرموز السرية غير المستخدَمة بشكل نشط باستخدام functions:secrets:destroy وfunctions:secrets:prune.

يسمح Secret Manager بإجراء 10,000 عملية وصول شهرية غير مفوترة على بيانات سرية. تقرأ نُسخ الدوال فقط البيانات الحسّاسة المحدّدة في خيار secrets في كل مرة يتم فيها تشغيلها على البارد. إذا كان لديك العديد من نُسخ الدوال التي تقرأ الكثير من البيانات السرية، قد يتجاوز مشروعك هذا الحدّ المسموح به، وعندها سيتم تحصيل 0.03 دولار أمريكي منك مقابل كل 10,000 عملية وصول.

لمزيد من المعلومات، يُرجى الاطّلاع على أسعار Secret Manager.

التوافق مع المحاكي

تم تصميم إعدادات البيئة باستخدام dotenv للعمل مع محاكي Cloud Functions محلي.

عند استخدام محاكي Cloud Functions محلي، يمكنك إلغاء متغيرات البيئة لمشروعك من خلال إعداد ملف .env.local. يكون لمحتوى .env.local الأولوية على .env وملف .env الخاص بالمشروع.

على سبيل المثال، يمكن أن يتضمّن المشروع هذه الملفات الثلاثة التي تحتوي على قيم مختلفة قليلاً للتطوير والاختبار المحلي:

`.env`	`.env.dev`	`.env.local`
PLANET=Earth AUDIENCE=Humans	AUDIENCE=Dev Humans	AUDIENCE=Local Humans

عند بدء تشغيل المحاكي في السياق المحلي، يقوم المحاكي بتحميل متغيرات البيئة كما هو موضح:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

الأسرار وبيانات الاعتماد في محاكي Cloud Functions

يتيح محاكي Cloud Functions استخدام الرموز السرية من أجل تخزين معلومات الإعدادات الحساسة والوصول إليها. سيحاول المحاكي تلقائيًا الوصول إلى بيانات الاعتماد السرية في الإصدار العلني باستخدام بيانات الاعتماد التلقائية للتطبيق. In certain situations like CI environments, the emulator may fail to access secret values due to permission restrictions.

على غرار توافق محاكي Cloud Functions مع متغيّرات البيئة، يمكنك تجاوز قيم البيانات السرية من خلال إعداد ملف .secret.local. ويسهّل ذلك عليك اختبار الدوال محليًا، خاصةً إذا لم يكن لديك إذن الوصول إلى القيمة السرية.

النقل من إعدادات وقت التشغيل

تم إيقاف واجهة برمجة التطبيقات functions.config نهائيًا، وسيتم إيقافها نهائيًا في مارس 2027. بعد ذلك التاريخ، ستتعذّر عمليات النشر باستخدام functions.config.

لتجنُّب حدوث أخطاء في عملية النشر، عليك نقل الإعدادات إلى Cloud Secret Manager باستخدام واجهة سطر الأوامر Firebase. ننصح بشدة باتّباع هذه الطريقة لأنّها الأكثر فعالية وأمانًا لنقل الإعدادات.

تصدير الإعدادات باستخدام واجهة سطر الأوامر في Firebase

استخدِم الأمر config export لتصدير إعدادات البيئة الحالية إلى رمز سرّي جديد في Cloud Secret Manager:

$ firebase functions:config:export
i  This command retrieves your Runtime Config values (accessed via functions.config())
   and exports them as a Secret Manager secret.

i  Fetching your existing functions.config() from your project...  ✔
   Fetched your existing functions.config().

i  Configuration to be exported:
⚠  This may contain sensitive data. Do not share this output.

{
   ...
}

✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG

✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```

تعديل رمز الدالة لربط الرموز السرية

لاستخدام الإعدادات المخزَّنة في البيانات السرية الجديدة في Cloud Secret Manager، استخدِم واجهة برمجة التطبيقات defineJsonSecret في مصدر الدالة. تأكَّد أيضًا من ربط البيانات السرية بجميع الدوال التي تحتاج إليها.

قبل

const functions = require("firebase-functions/v1");

exports.myFunction = functions.https.onRequest((req, res) => {
  const apiKey = functions.config().someapi.key;
  // ...
});

بعد

const { onRequest } = require("firebase-functions/v2/https");
const { defineJsonSecret } = require("firebase-functions/params");

const config = defineJsonSecret("RUNTIME_CONFIG");

exports.myFunction = onRequest(
  // Bind secret to your function
  { secrets: [config] },
  (req, res) => {
    // Access secret values via .value()
    const apiKey = config.value().someapi.key;
    // ...
});

نشر الدوال

انشر الدوال المعدَّلة لتطبيق التغييرات وربط أذونات البيانات السرية.
```
firebase deploy --only functions:<your-function-name>
```

متغيّرات البيئة التي تتم تعبئتها تلقائيًا

هناك متغيّرات بيئة تتم تعبئتها تلقائيًا في وقت تشغيل الدوال وفي الدوال التي تتم محاكاتها محليًا. وتشمل هذه المتغيّرات تلك التي تتم تعبئتها من خلال Google Cloud، بالإضافة إلى متغيّر بيئة خاص بمنصة Firebase:

‫process.env.FIREBASE_CONFIG: توفّر معلومات إعدادات مشروع Firebase التالية:

{
  databaseURL: 'https://DATABASE_NAME.firebaseio.com',
  storageBucket: 'PROJECT_ID.firebasestorage.app',
  projectId: 'PROJECT_ID'
}

يُرجى العِلم أنّ القيم في إعدادات Firebase الفعلية قد تختلف حسب الموارد التي تم توفيرها في مشروعك.

يتم تطبيق هذه الإعدادات تلقائيًا عند إعداد حزمة SDK الخاصة بمشرف Firebase بدون أي وسيطات. إذا كنت تكتب دوال في JavaScript، فابدأ على النحو التالي:

const admin = require('firebase-admin');
admin.initializeApp();

إذا كنت تكتب دوال في TypeScript، يمكنك إعدادها على النحو التالي:

import * as functions from 'firebase-functions/v1';
import * as admin from 'firebase-admin';
import 'firebase-functions/v1';
admin.initializeApp();

إذا كنت بحاجة إلى إعداد حزمة SDK للمشرف باستخدام الإعدادات التلقائية للمشروع باستخدام بيانات اعتماد حساب الخدمة، يمكنك تحميل بيانات الاعتماد من ملف وإضافتها إلى FIREBASE_CONFIG على النحو التالي:

serviceAccount = require('./serviceAccount.json');

const adminConfig = JSON.parse(process.env.FIREBASE_CONFIG);
adminConfig.credential = admin.credential.cert(serviceAccount);
admin.initializeApp(adminConfig);

ضبط البيئة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الإعدادات المستندة إلى مَعلمات

Node.js

Python

استخدام المَعلمات في النطاق العام

Node.js

Python

ضبط سلوك واجهة سطر الأوامر

Node.js

Python

أنواع المعلّمات

قيم المَعلمات والتعبيرات

Node.js

Python

Node.js

Python

Node.js

Python

المَعلمات المضمّنة

Node.js

Python

المَعلمات السرية

Node.js

Python

أسرار JSON المنظَّمة

متغيّرات البيئة

Node.js

Python

نشر مجموعات متعددة من متغيرات البيئة

متغيّرات البيئة المحجوزة

تخزين معلومات الإعدادات الحساسة والوصول إليها

إنشاء بيانات سرية واستخدامها

Node.js

Python

Node.js

Python

إدارة المفاتيح السرّية

كيفية فوترة المفاتيح السرية

التوافق مع المحاكي

الأسرار وبيانات الاعتماد في محاكي Cloud Functions

النقل من إعدادات وقت التشغيل

متغيّرات البيئة التي تتم تعبئتها تلقائيًا

ضبط البيئة