تكوين بيئتك

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

يمكنك الاختيار بين التكوين المستند إلى ملف لمتغيرات البيئة (موصى به) أو تكوين بيئة وقت التشغيل باستخدام Firebase CLI و functions.config . كلا النهجين موصوفان في هذا الدليل.

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

تدعم وظائف السحابة لـ Firebase تنسيق ملف dotenv لتحميل متغيرات البيئة المحددة في ملف .env تشغيل التطبيق الخاص بك. بمجرد النشر ، يمكن قراءة متغيرات البيئة عبر واجهة process.env .

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

  1. قم بإنشاء ملف .env في دوالك functions/ دليلك:

    # Directory layout:
    #   my-project/
    #     firebase.json
    #     functions/
    #       .env
    #       package.json
    #       index.js
    
  2. افتح ملف .env للتحرير ، وأضف المفاتيح المطلوبة. علي سبيل المثال:

    PLANET=Earth
    AUDIENCE=Humans
    
  3. انشر الوظائف وتحقق من تحميل متغيرات البيئة:

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

بمجرد نشر متغيرات البيئة المخصصة الخاصة بك ، يمكن لشفرة وظيفتك الوصول إليها من خلال بناء جملة process.env :

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

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

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

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

.env .env.dev .env.prod
كوكب = الأرض

الجمهور = البشر

الجمهور = ديف البشر الجمهور = همز البشر

بالنظر إلى القيم الموجودة في هذه الملفات المنفصلة ، ستختلف مجموعة متغيرات البيئة المنشورة مع وظائفك اعتمادًا على مشروعك المستهدف:

$ 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
  • نقطة الدخول
  • GCP_PROJECT
  • GCLOUD_PROJECT
  • GOOGLE_CLOUD_PROJECT
  • FUNCTION_TRIGGER_TYPE
  • اسم وظيفة
  • FUNCTION_MEMORY_MB
  • FUNCTION_TIMEOUT_SEC
  • FUNCTION_IDENTITY
  • FUNCTION_REGION
  • FUNCTION_TARGET
  • FUNCTION_SIGNATURE_TYPE
  • K_SERVICE
  • K_REVISION
  • ميناء
  • K_CONFIGURATION

تخزين والوصول إلى معلومات التكوين الحساسة

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

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

إنشاء واستخدام سر

لإنشاء سر ، استخدم Firebase CLI.

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

  1. من جذر دليل المشروع المحلي الخاص بك ، قم بتشغيل الأمر التالي:

    firebase functions:secrets:set SECRET_NAME

  2. أدخل قيمة لـ SECRET_NAME .

    يردد CLI رسالة نجاح ويحذر من أنه يجب عليك نشر الوظائف حتى يسري التغيير.

  3. قبل النشر ، تأكد من أن كود الوظائف الخاص بك يسمح للوظيفة بالوصول إلى السر باستخدام المعلمة runWith :

    exports.processPayment = functions
      // Make the secret available to this function
      .runWith({ secrets: ["SECRET_NAME"] })
      .onCall((data, context) => {
        const myBillingService = initializeBillingService(
          // reference the secret value
          process.env.SECRET_NAME
        );
        // Process the payment
      });
  4. نشر وظائف السحابة:

    firebase deploy --only functions

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

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

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

إدارة الأسرار

استخدم Firebase CLI لإدارة أسرارك. أثناء إدارة الأسرار بهذه الطريقة ، ضع في اعتبارك أن بعض تغييرات CLI تتطلب منك تعديل و / أو إعادة نشر الوظائف المرتبطة. خاصة:

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

في ما يلي ملخص لأوامر Firebase CLI للإدارة السرية:

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

# 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 مع الأمر لعرض تعليمات CLI.

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

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

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

يسمح Secret Manager بـ 10000 عملية وصول شهرية غير مفوترة بسرية. تقرأ مثيلات الوظائف فقط الأسرار المحددة في runWith الخاصة بها في كل مرة تبدأ فيها باردة. إذا كان لديك الكثير من حالات الوظائف التي تقرأ الكثير من الأسرار ، فقد يتجاوز مشروعك هذا البدل ، وعند هذه النقطة ستدفع 0.03 دولارًا لكل 10000 عملية وصول.

لمزيد من المعلومات ، راجع تسعير المدير السري .

دعم المحاكي

تم تصميم تكوين البيئة مع dotenv للتعامل مع محاكي وظائف السحابة المحلي.

عند استخدام محاكي وظائف السحابة المحلي ، يمكنك تجاوز متغيرات البيئة لمشروعك من خلال إعداد ملف .env.local . محتويات .env.local لها الأسبقية على .env وملف .env الخاص بالمشروع.

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

.env .env.dev .env.local
كوكب = الأرض

الجمهور = البشر

الجمهور = ديف البشر AUDIENCE = البشر المحليين

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

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

الأسرار وبيانات الاعتماد في محاكي وظائف السحابة

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

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

الترحيل من تكوين البيئة

إذا كنت تستخدم تكوين البيئة مع functions.config ، فيمكنك ترحيل التكوين الحالي الخاص بك كمتغيرات بيئة (بتنسيق dotenv ). يوفر Firebase CLI أمر تصدير يقوم بإخراج تكوين كل اسم مستعار أو مشروع مدرج في ملف .firebaserc الخاص بالدليل (في المثال أدناه ، local و dev و prod ) كملفات .env .

للترحيل ، قم بتصدير تكوينات البيئة الحالية باستخدام firebase functions:config:export command:

firebase functions:config:export
i  Importing configs from projects: [project-0, project-1]
⚠  The following configs keys could not be exported as environment variables:

⚠  project-0 (dev):
    1foo.a => 1FOO\_A (Key 1FOO\_A must start with an uppercase ASCII letter or underscore, and then consist of uppercase ASCII letters, digits, and underscores.)

Enter a PREFIX to rename invalid environment variable keys: CONFIG\_
✔  Wrote functions/.env.prod
✔  Wrote functions/.env.dev
✔  Wrote functions/.env.local
✔  Wrote functions/.env

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

نوصي بمراجعة محتويات ملفات .env التي تم إنشاؤها بعناية قبل نشر وظائفك أو التحقق من ملفات .env في التحكم بالمصادر. إذا كانت أي قيم حساسة ولا يجب تسريبها ، فقم بإزالتها من ملفات .env الخاصة بك وخزنها بأمان في Secret Manager بدلاً من ذلك.

ستحتاج أيضًا إلى تحديث رمز وظائفك. أي دوال تستخدم functions.config ستحتاج الآن إلى استخدام process.env بدلاً من ذلك ، كما هو موضح في متغيرات البيئة .

تكوين البيئة

قبل إصدار دعم متغير البيئة في firebase-functions v3.18.0 ، كان استخدام functions.config() هو الأسلوب الموصى به لتكوين البيئة. لا يزال هذا النهج مدعومًا ، لكننا نوصي باستخدام جميع المشروعات الجديدة متغيرات البيئة بدلاً من ذلك ، حيث إنها أسهل في الاستخدام وتحسين قابلية نقل التعليمات البرمجية الخاصة بك.

اضبط تكوين البيئة باستخدام CLI

لتخزين بيانات البيئة ، يمكنك استخدام firebase functions:config:set command في Firebase CLI . يمكن تحديد مساحة كل مفتاح باستخدام فترات لتجميع التكوين ذي الصلة معًا. ضع في اعتبارك أنه يتم قبول الأحرف الصغيرة فقط في المفاتيح ؛ الأحرف الكبيرة غير مسموح بها.

على سبيل المثال ، لتخزين معرّف العميل ومفتاح واجهة برمجة التطبيقات لـ "بعض الخدمات" ، يمكنك تشغيل:

firebase functions:config:set someservice.key="THE API KEY" someservice.id="THE CLIENT ID"

استرجاع تكوين البيئة الحالية

لفحص ما يتم تخزينه حاليًا في تهيئة البيئة لمشروعك ، يمكنك استخدام firebase functions:config:get . سيخرج JSON شيئًا مثل هذا:

{
  "someservice": {
    "key":"THE API KEY",
    "id":"THE CLIENT ID"
  }
}

تعتمد هذه الوظيفة على Google Cloud Runtime Configuration API .

استخدم functions.config للوصول إلى تكوين البيئة في إحدى الوظائف

يتم توفير بعض التهيئة تلقائيًا ضمن مساحة اسم firebase المحجوزة. يتم توفير تكوين البيئة داخل وظيفة التشغيل الخاصة بك عبر functions.config() . لاستخدام التكوين أعلاه ، قد يبدو الرمز الخاص بك كما يلي:

const functions = require('firebase-functions');
const request = require('request-promise');

exports.userCreated = functions.database.ref('/users/{id}').onWrite(event => {
  let email = event.data.child('email').val();

  return request({
    url: 'https://someservice.com/api/some/call',
    headers: {
      'X-Client-ID': functions.config().someservice.id,
      'Authorization': `Bearer ${functions.config().someservice.key}`
    },
    body: {email: email}
  });
});

استخدم تكوين البيئة لتهيئة وحدة نمطية

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

على سبيل المثال ، لاستخدام وحدة Slack Node SDK ، يمكنك كتابة هذا:

const functions = require('firebase-functions');
const IncomingWebhook = require('@slack/client').IncomingWebhook;
const webhook = new IncomingWebhook(functions.config().slack.url);

قبل النشر ، اضبط متغير تهيئة بيئة slack.url :

firebase functions:config:set slack.url=https://hooks.slack.com/services/XXX

أوامر البيئة الإضافية

  • firebase functions:config:unset key1 key2 يزيل المفاتيح المحددة من config
  • firebase functions:config:clone --from <fromProject> استنساخ بيئة مشروع آخر إلى المشروع النشط حاليًا.

متغيرات البيئة المأهولة تلقائيا

هناك متغيرات البيئة التي يتم ملؤها تلقائيًا في وقت تشغيل الوظائف وفي الوظائف التي تمت مضاهاتها محليًا. يتضمن ذلك تلك التي تم ملؤها بواسطة Google Cloud ، بالإضافة إلى متغير بيئة خاص بـ Firebase:

process.env.FIREBASE_CONFIG : يوفر معلومات تهيئة مشروع Firebase التالية:

{
  databaseURL: 'https://databaseName.firebaseio.com',
  storageBucket: 'projectId.appspot.com',
  projectId: 'projectId'
}

يتم تطبيق هذه التهيئة تلقائيًا عند تهيئة Firebase Admin SDK بدون وسيطات. إذا كنت تكتب وظائف في JavaScript ، فقم بالتهيئة على النحو التالي:

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

إذا كنت تكتب وظائف في TypeScript ، فقم بالتهيئة على النحو التالي:

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

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

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

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