הגדר את הסביבה שלך

לעתים קרובות תזדקק לתצורה נוספת עבור הפונקציות שלך, כגון מפתחות API של צד שלישי או הגדרות הניתנות לכיוון. ה-SDK של Firebase for Cloud Functions מציע תצורת סביבה מובנית כדי להקל על אחסון ושליפה של סוג זה של נתונים עבור הפרויקט שלך.

אתה יכול לבחור בין תצורת מבוססי קובץ של משתני סביבה (מומלץ) או תצורת סביבת זמן ריצה עם 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 שלך (כגון היערכות vs הייצור), ליצור .env. <project or alias > קובץ ולכתוב משתני סביבת פרויקט הספציפי שלך שם. את משתני הסביבה מן .env ספציפי הפרויקט .env קבצים (אם הם קיימים) ייכללו כל הפונקציות פרוסים.

לדוגמה, פרויקט יכול לכלול את שלושת הקבצים האלה המכילים ערכים מעט שונים לפיתוח וייצור:

.env .env.dev .env.prod
PLANET=כדור הארץ

קהל=בני אדם

AUDIENCE=Dev 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
  • נקודת כניסה
  • 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
  • נמל
  • K_CONFIGURATION

אחסן וגישה למידע תצורה רגיש

משתני סביבה המאוחסנים .env קבצים יכולים לשמש תצורת פונקציה, אבל אתה לא צריך לשקול אותם דרך בטוחה לאחסן מידע רגיש כגון אישורי מסד או מפתחות API. זה חשוב במיוחד אם אתה בודק שלך .env קבצים לתוך בקרת תצורה.

כדי לעזור לכם לאחסן מידע תצורה רגיש, פונקציות ענן עבור משתלב Firebase עם Google Cloud הסוד מנהל . שירות מוצפן זה מאחסן ערכי תצורה בצורה מאובטחת, ועדיין מאפשר גישה קלה מהפונקציות שלך בעת הצורך.

צור סוד והשתמש בו

כדי ליצור סוד, השתמש ב-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.

כיצד מחויבים סודות

הסוד מנהל מאפשר 6 סוד פעיל גרסאות ללא עלות. זה אומר שאתה יכול לקבל 6 סודות בחודש בפרויקט Firebase ללא עלות.

כברירת מחדל, ה-CLI של Firebase מנסה להשמיד אוטומטית גרסאות סודיות שאינן בשימוש במידת הצורך, כגון כאשר אתה פורס פונקציות עם גרסה חדשה של הסוד. כמו כן, אתה יכול באופן פעיל לנקות סודות בשימוש באמצעות functions:secrets:destroy ו functions:secrets:prune .

Secret Manager מאפשר 10,000 פעולות גישה חודשיות ללא חיוב בסוד. במקרי פונקציה לקרוא רק את הסודות המפורטים שלהם runWith פרמטר בכול פעם שהם להתחיל קרים. אם יש לך הרבה מופעי פונקציות שקוראים הרבה סודות, הפרויקט שלך עלול לחרוג מהקצבה הזו, ובשלב זה תחויב ב-$0.03 לכל 10,000 פעולות גישה.

לקבלת מידע נוסף, ראה תמחור מנהל החשאי .

תמיכה באמולטור

תצורת הסביבה עם dotenv נועד לפעולה הדדית עם המקומיים אמולטור ענן פונקציות .

בעת שימוש אמולטור מקומי ענן פונקציות, אתה יכול לעקוף משתני סביבה עבור הפרויקט שלך על ידי הגדרת .env.local קובץ. תוכן של .env.local קדימות השתלטות .env והפרויקט הספציפי .env קובץ.

לדוגמה, פרויקט יכול לכלול את שלושת הקבצים האלה המכילים ערכים מעט שונים לפיתוח ובדיקות מקומיות:

.env .env.dev .env.local
PLANET=כדור הארץ

קהל=בני אדם

AUDIENCE=Dev Humans קהל = בני אדם מקומיים

כאשר מופעל בהקשר המקומי, האמולטור טוען את משתני הסביבה כפי שמוצג:

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

סודות ואישורים באמולטור Cloud Functions

תפקידי ענן אמולטור תומך בשימוש סודות חנות ותצורת גישה רגישה . כברירת מחדל, אמולטור ינסה לגשת סודות הייצור באמצעות אישורי מחדל יישום . במצבים מסוימים כמו סביבות CI, האמולטור עלול להיכשל בגישה לערכים סודיים עקב הגבלות הרשאה.

בדומה תמיכת אמולטור פונקציות ענן עבור משתני סביבה, אתה יכול לעקוף ערכי סודות ידי הקמת .secret.local קובץ. זה מקל עליך לבדוק את הפונקציות שלך באופן מקומי, במיוחד אם אין לך גישה לערך הסודי.

מעבר מתצורת הסביבה

אם אתה כבר משתמש תצורה לסביבה עם functions.config , אתה יכול להעביר את התצורה הקיימת כפי משתני סביבה (ב dotenv פורמט). Firebase CLI מספק הפקודה הייצוא כי פלטי התצורה של כל כינוי או פרויקט הרשומים של המדריך שלך .firebaserc קובץ (בדוגמה להלן, local , dev , ו prod ) כמו .env קבצים.

כדי להעביר, לייצא תצורות בסביבה הקיימת שלך באמצעות firebase functions:config:export הפקודה:

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 קבצים ולאחסן אותם בבטחה מנהל החשאי במקום.

תצטרך גם לעדכן את קוד הפונקציות שלך. כול פונקציות כי השימוש functions.config יצטרך כעת לשימוש process.env במקום, כפי שמוצג משתנה סביבה .

תצורת סביבה

לפני תמיכה משתנה הסביבה שוחרר firebase-functions v3.18.0 , באמצעות functions.config() היה הגישה המומלצת עבור תצורת הסביבה. גישה זו עדיין נתמכת, אך אנו ממליצים לכל הפרויקטים החדשים להשתמש במשתני סביבה במקום זאת, מכיוון שהם פשוטים יותר לשימוש ומשפרים את הניידות של הקוד שלך.

הגדר תצורת סביבה עם ה-CLI

נתוני הסביבה בחנות, אתה יכול להשתמש firebase functions:config:set פיקודי Firebase CLI . כל מפתח יכול להיות מרווח שמות באמצעות נקודות כדי לקבץ תצורה קשורה יחד. זכור כי רק תווים לאותיות קטנות מתקבלים מפתחות; אסור להשתמש באותיות רישיות.

לדוגמה, כדי לאחסן את מזהה הלקוח ומפתח ה-API עבור "שירות כלשהו", תוכל להפעיל:

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

אחזר את תצורת הסביבה הנוכחית

כדי לבדוק מה יישמר כיום config הסביבה לפרויקט שלך, אתה יכול להשתמש firebase functions:config:get . זה יוציא JSON משהו כזה:

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

פונקציונליות זו מבוססת על ממשק API להגדרת Google Cloud Runtime .

השתמש 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}
  });
});

השתמש בתצורת סביבה כדי לאתחל מודול

חלק ממודולי ה-Node מוכנים ללא כל תצורה. מודולים אחרים זקוקים לתצורה נוספת כדי לאתחל כהלכה. אנו ממליצים לאחסן את התצורה הזו במשתני תצורת הסביבה במקום לקודד אותה. זה עוזר לך לשמור על הקוד שלך הרבה יותר נייד, מה שמאפשר לך לפתוח את היישום שלך בקוד קוד או לעבור בקלות בין גרסאות ייצור ל-Staging.

לדוגמה, כדי להשתמש ב- SDK צומת סלאק מודול, ייתכן לכתוב זה:

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

לפני הפריסה, להגדיר את slack.url משתנית config הסביבה:

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 : מספק מידע config פרויקט Firebase הבא:

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

תצורה זו מוחלת באופן אוטומטי כאשר אתה מאתחל את Firebase Admin SDK ללא ארגומנטים. אם אתה כותב פונקציות ב-JavaScript, אתחול כך:

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

אם אתה כותב פונקציות בכתב יד מודפס, לאתחל ככה:

import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
import 'firebase-functions';
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);