กำหนดค่าสภาพแวดล้อมของคุณ

บ่อยครั้ง คุณจะต้องมีการกำหนดค่าเพิ่มเติมสำหรับฟังก์ชันของคุณ เช่น คีย์ API ของบริษัทอื่นหรือการตั้งค่าที่ปรับแต่งได้ Firebase SDK for Cloud Functions มีการกำหนดค่าสภาพแวดล้อมในตัวเพื่อให้ง่ายต่อการจัดเก็บและเรียกข้อมูลประเภทนี้สำหรับโปรเจ็กต์ของคุณ

คุณสามารถเลือกระหว่างการกำหนดค่าตามไฟล์ของ ตัวแปรสภาพแวดล้อม (แนะนำ) หรือ การกำหนดค่าสภาพแวดล้อม รันไทม์ด้วย Firebase CLI และ functions.config แนวทางทั้งสองมีอธิบายไว้ในคู่มือนี้

ตัวแปรสภาพแวดล้อม

Cloud Functions for 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 (เช่น staging vs production) ให้สร้าง .env. <project or alias > ไฟล์และเขียนตัวแปรสภาพแวดล้อมเฉพาะโปรเจ็กต์ของคุณที่นั่น ตัวแปรสภาพแวดล้อมจาก .env และไฟล์ .env เฉพาะโปรเจ็กต์ (หากมี) จะรวมอยู่ในฟังก์ชันที่ปรับใช้ทั้งหมด

ตัวอย่างเช่น โปรเจ็กต์อาจรวมไฟล์สามไฟล์นี้ที่มีค่าต่างกันเล็กน้อยสำหรับการพัฒนาและการผลิต:

.env .env.dev .env.prod
PLANET=โลก

ผู้ชม=มนุษย์

ผู้ชม = Dev Humans ผู้ชม = 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
  • ท่า
  • K_CONFIGURATION

จัดเก็บและเข้าถึงข้อมูลการกำหนดค่าที่ละเอียดอ่อน

ตัวแปรสภาพแวดล้อมที่เก็บไว้ในไฟล์ . .env สามารถใช้สำหรับการกำหนดค่าฟังก์ชันได้ แต่คุณไม่ควรพิจารณาว่าเป็นวิธีการที่ปลอดภัยในการจัดเก็บข้อมูลที่ละเอียดอ่อน เช่น ข้อมูลประจำตัวของฐานข้อมูลหรือคีย์ API สิ่งนี้สำคัญอย่างยิ่งหากคุณตรวจสอบไฟล์ .env ของคุณในการควบคุมแหล่งที่มา

เพื่อช่วยคุณจัดเก็บข้อมูลการกำหนดค่าที่ละเอียดอ่อน Cloud Functions for 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 อนุญาตให้มีการดำเนินการเข้าถึงข้อมูลลับที่ยังไม่ได้เรียกเก็บเงิน 10,000 รายการต่อเดือน อินสแตนซ์ของฟังก์ชันจะอ่านเฉพาะข้อมูลลับที่ระบุในพารามิเตอร์ runWith ทุกครั้งที่สตาร์ทแบบเย็น หากคุณมีอินสแตนซ์ของฟังก์ชันจำนวนมากที่อ่านความลับจำนวนมาก โปรเจ็กต์ของคุณอาจเกินค่าเผื่อนี้ ซึ่งคุณจะถูกเรียกเก็บเงิน 0.03 USD ต่อการดำเนินการเข้าถึง 10,000 รายการ

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ ราคาผู้จัดการลับ

รองรับโปรแกรมจำลอง

การกำหนดค่าสภาพแวดล้อมด้วย dotenv ออกแบบมาเพื่อทำงานร่วมกับ โปรแกรมจำลอง Cloud Functions ในเครื่อง

เมื่อใช้โปรแกรมจำลอง Cloud Functions ในเครื่อง คุณจะลบล้างตัวแปรสภาพแวดล้อมสำหรับโปรเจ็กต์ได้โดยการตั้งค่าไฟล์ . .env.local เนื้อหาของ .env.local มีความสำคัญเหนือกว่า .env และไฟล์ . .env เฉพาะโครงการ

ตัวอย่างเช่น โปรเจ็กต์อาจรวมไฟล์สามไฟล์นี้ที่มีค่าต่างกันเล็กน้อยสำหรับการพัฒนาและการทดสอบในเครื่อง:

.env .env.dev .env.local
PLANET=โลก

ผู้ชม=มนุษย์

ผู้ชม = Dev Humans ผู้ชม=คนในท้องถิ่น

เมื่อเริ่มต้นในบริบทโลคัล อีมูเลเตอร์จะโหลดตัวแปรสภาพแวดล้อมดังที่แสดง:

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

ความลับและข้อมูลประจำตัวในโปรแกรมจำลอง Cloud Functions

โปรแกรมจำลอง Cloud Functions รองรับการใช้ความลับในการ จัดเก็บและเข้าถึงข้อมูลการกำหนดค่าที่ละเอียดอ่อน โดยค่าเริ่มต้น โปรแกรมจำลองจะพยายามเข้าถึงความลับในการผลิตของคุณโดยใช้ ข้อมูลประจำตัวเริ่มต้นของแอปพลิเคชัน ในบางสถานการณ์ เช่น สภาพแวดล้อม CI โปรแกรมจำลองอาจไม่สามารถเข้าถึงค่าลับได้เนื่องจากข้อจำกัดการอนุญาต

เช่นเดียวกับการรองรับ Cloud Functions emulator สำหรับตัวแปรสภาพแวดล้อม คุณสามารถแทนที่ค่าความลับได้โดยการตั้งค่าไฟล์ . .secret.local ซึ่งทำให้ง่ายต่อการทดสอบฟังก์ชันของคุณภายในเครื่อง โดยเฉพาะอย่างยิ่งหากคุณไม่มีสิทธิ์เข้าถึงค่าลับ

การย้ายจากการกำหนดค่าสภาพแวดล้อม

หากคุณใช้การกำหนดค่าสภาพแวดล้อมด้วย functions.config คุณสามารถโอนย้ายการกำหนดค่าที่มีอยู่ของคุณเป็นตัวแปรสภาพแวดล้อม (ในรูปแบบ dotenv ) Firebase CLI จัดเตรียมคำสั่ง export ที่ส่งออกการกำหนดค่าของนามแฝงหรือโปรเจ็กต์แต่ละรายการที่แสดงอยู่ในไฟล์ .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 ของคุณและเก็บไว้อย่างปลอดภัยใน Secret Manager แทน

คุณจะต้องอัปเดตโค้ดฟังก์ชันของคุณด้วย ฟังก์ชันใดๆ ที่ใช้ functions.config จะต้องใช้ process.env แทน ดังที่แสดงใน ตัวแปร Environment

การกำหนดค่าสภาพแวดล้อม

ก่อนที่การสนับสนุนตัวแปรสภาพแวดล้อมจะเผยแพร่ใน 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"

ดึงข้อมูลการกำหนดค่าสภาพแวดล้อมปัจจุบัน

ในการตรวจสอบสิ่งที่จัดเก็บอยู่ในการกำหนดค่าสภาพแวดล้อมสำหรับโครงการของคุณในปัจจุบัน คุณสามารถใช้ firebase functions:config:get มันจะส่งออก JSON บางอย่างเช่นนี้:

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

ฟังก์ชันนี้อิงตาม Google Cloud Runtime Configuration API

ใช้ functions.config เพื่อเข้าถึงการกำหนดค่าสภาพแวดล้อมใน function

การกำหนดค่าบางอย่างมีให้โดยอัตโนมัติภายใต้เนมสเปซ 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);
,

บ่อยครั้ง คุณจะต้องมีการกำหนดค่าเพิ่มเติมสำหรับฟังก์ชันของคุณ เช่น คีย์ API ของบริษัทอื่นหรือการตั้งค่าที่ปรับแต่งได้ Firebase SDK for Cloud Functions มีการกำหนดค่าสภาพแวดล้อมในตัวเพื่อให้ง่ายต่อการจัดเก็บและเรียกข้อมูลประเภทนี้สำหรับโปรเจ็กต์ของคุณ

คุณสามารถเลือกระหว่างการกำหนดค่าตามไฟล์ของ ตัวแปรสภาพแวดล้อม (แนะนำ) หรือ การกำหนดค่าสภาพแวดล้อม รันไทม์ด้วย Firebase CLI และ functions.config แนวทางทั้งสองมีอธิบายไว้ในคู่มือนี้

ตัวแปรสภาพแวดล้อม

Cloud Functions for 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 (เช่น staging vs production) ให้สร้าง .env. <project or alias > ไฟล์และเขียนตัวแปรสภาพแวดล้อมเฉพาะโปรเจ็กต์ของคุณที่นั่น ตัวแปรสภาพแวดล้อมจาก .env และไฟล์ .env เฉพาะโปรเจ็กต์ (หากมี) จะรวมอยู่ในฟังก์ชันที่ปรับใช้ทั้งหมด

ตัวอย่างเช่น โปรเจ็กต์อาจรวมไฟล์สามไฟล์นี้ที่มีค่าต่างกันเล็กน้อยสำหรับการพัฒนาและการผลิต:

.env .env.dev .env.prod
PLANET=โลก

ผู้ชม=มนุษย์

ผู้ชม = Dev Humans ผู้ชม = 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
  • ท่า
  • K_CONFIGURATION

จัดเก็บและเข้าถึงข้อมูลการกำหนดค่าที่ละเอียดอ่อน

ตัวแปรสภาพแวดล้อมที่เก็บไว้ในไฟล์ . .env สามารถใช้สำหรับการกำหนดค่าฟังก์ชันได้ แต่คุณไม่ควรพิจารณาว่าเป็นวิธีการที่ปลอดภัยในการจัดเก็บข้อมูลที่ละเอียดอ่อน เช่น ข้อมูลประจำตัวของฐานข้อมูลหรือคีย์ API สิ่งนี้สำคัญอย่างยิ่งหากคุณตรวจสอบไฟล์ .env ของคุณในการควบคุมแหล่งที่มา

เพื่อช่วยคุณจัดเก็บข้อมูลการกำหนดค่าที่ละเอียดอ่อน Cloud Functions for 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 อนุญาตให้มีการดำเนินการเข้าถึงข้อมูลลับที่ยังไม่ได้เรียกเก็บเงิน 10,000 รายการต่อเดือน อินสแตนซ์ของฟังก์ชันจะอ่านเฉพาะข้อมูลลับที่ระบุในพารามิเตอร์ runWith ทุกครั้งที่สตาร์ทแบบเย็น หากคุณมีอินสแตนซ์ของฟังก์ชันจำนวนมากที่อ่านความลับจำนวนมาก โปรเจ็กต์ของคุณอาจเกินค่าเผื่อนี้ ซึ่งคุณจะถูกเรียกเก็บเงิน 0.03 USD ต่อการดำเนินการเข้าถึง 10,000 รายการ

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ ราคาผู้จัดการลับ

รองรับโปรแกรมจำลอง

การกำหนดค่าสภาพแวดล้อมด้วย dotenv ออกแบบมาเพื่อทำงานร่วมกับ โปรแกรมจำลอง Cloud Functions ในเครื่อง

เมื่อใช้โปรแกรมจำลอง Cloud Functions ในเครื่อง คุณจะลบล้างตัวแปรสภาพแวดล้อมสำหรับโปรเจ็กต์ได้โดยการตั้งค่าไฟล์ . .env.local เนื้อหาของ .env.local มีความสำคัญเหนือกว่า .env และไฟล์ . .env เฉพาะโครงการ

ตัวอย่างเช่น โปรเจ็กต์อาจรวมไฟล์สามไฟล์นี้ที่มีค่าต่างกันเล็กน้อยสำหรับการพัฒนาและการทดสอบในเครื่อง:

.env .env.dev .env.local
PLANET=โลก

ผู้ชม=มนุษย์

ผู้ชม = Dev Humans ผู้ชม=คนในท้องถิ่น

เมื่อเริ่มต้นในบริบทโลคัล อีมูเลเตอร์จะโหลดตัวแปรสภาพแวดล้อมดังที่แสดง:

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

ความลับและข้อมูลประจำตัวในโปรแกรมจำลอง Cloud Functions

โปรแกรมจำลอง Cloud Functions รองรับการใช้ความลับในการ จัดเก็บและเข้าถึงข้อมูลการกำหนดค่าที่ละเอียดอ่อน โดยค่าเริ่มต้น โปรแกรมจำลองจะพยายามเข้าถึงความลับในการผลิตของคุณโดยใช้ ข้อมูลประจำตัวเริ่มต้นของแอปพลิเคชัน ในบางสถานการณ์ เช่น สภาพแวดล้อม CI โปรแกรมจำลองอาจไม่สามารถเข้าถึงค่าลับได้เนื่องจากข้อจำกัดการอนุญาต

เช่นเดียวกับการรองรับ Cloud Functions emulator สำหรับตัวแปรสภาพแวดล้อม คุณสามารถแทนที่ค่าความลับได้โดยการตั้งค่าไฟล์ . .secret.local ซึ่งทำให้ง่ายต่อการทดสอบฟังก์ชันของคุณภายในเครื่อง โดยเฉพาะอย่างยิ่งหากคุณไม่มีสิทธิ์เข้าถึงค่าลับ

การย้ายจากการกำหนดค่าสภาพแวดล้อม

หากคุณใช้การกำหนดค่าสภาพแวดล้อมด้วย functions.config คุณสามารถโอนย้ายการกำหนดค่าที่มีอยู่ของคุณเป็นตัวแปรสภาพแวดล้อม (ในรูปแบบ dotenv ) Firebase CLI จัดเตรียมคำสั่ง export ที่ส่งออกการกำหนดค่าของนามแฝงหรือโปรเจ็กต์แต่ละรายการที่แสดงอยู่ในไฟล์ .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 ของคุณและเก็บไว้อย่างปลอดภัยใน Secret Manager แทน

คุณจะต้องอัปเดตโค้ดฟังก์ชันของคุณด้วย ฟังก์ชันใดๆ ที่ใช้ functions.config จะต้องใช้ process.env แทน ดังที่แสดงใน ตัวแปร Environment

การกำหนดค่าสภาพแวดล้อม

ก่อนที่การสนับสนุนตัวแปรสภาพแวดล้อมจะเผยแพร่ใน 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"

ดึงข้อมูลการกำหนดค่าสภาพแวดล้อมปัจจุบัน

ในการตรวจสอบสิ่งที่จัดเก็บอยู่ในการกำหนดค่าสภาพแวดล้อมสำหรับโครงการของคุณในปัจจุบัน คุณสามารถใช้ firebase functions:config:get มันจะส่งออก JSON บางอย่างเช่นนี้:

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

ฟังก์ชันนี้อิงตาม Google Cloud Runtime Configuration API

ใช้ functions.config เพื่อเข้าถึงการกำหนดค่าสภาพแวดล้อมใน function

การกำหนดค่าบางอย่างมีให้โดยอัตโนมัติภายใต้เนมสเปซ 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);