ตั้งค่าและใช้พารามิเตอร์ในส่วนขยาย

พารามิเตอร์คือกลไกที่ผู้ใช้ปรับแต่งอินสแตนซ์ที่ติดตั้งของส่วนขยายแต่ละรายการ พารามิเตอร์เป็นเหมือนตัวแปรสภาพแวดล้อมสำหรับส่วนขยาย ค่าของพารามิเตอร์จะเป็นป้อนข้อมูลอัตโนมัติ (ได้มาจาก Firebase หลังจากการติดตั้ง) หรือกำหนดค่าโดยผู้ใช้ (ผู้ใช้ระบุไว้ระหว่างการติดตั้ง) ก็ได้

คุณสามารถใช้พารามิเตอร์เหล่านี้ในการอ้างอิงในซอร์สโค้ดของฟังก์ชันของส่วนขยาย ไฟล์ extension.yaml และไฟล์ POSTINSTALL.md ไวยากรณ์สำหรับวิธีอ้างอิงพารามิเตอร์ที่ชื่อ PARAMETER_NAME มีดังนี้

  • ในซอร์สโค้ดของฟังก์ชัน ให้ใช้โมดูล params (เช่น params.defineInt("PARAMETER_NAME")) หรือ process.env.PARAMETER_NAME

  • ใช้ ${param:PARAMETER_NAME} ภายใน extension.yaml ถึง POSTINSTALL.md

    หลังจากการติดตั้งแล้ว คอนโซล Firebase จะแสดงเนื้อหาของไฟล์ POSTINSTALL.md และป้อนข้อมูลการอ้างอิงพารามิเตอร์ด้วยค่าจริงสําหรับอินสแตนซ์ที่ติดตั้ง

พารามิเตอร์ที่ป้อนข้อมูลโดยอัตโนมัติ

อินสแตนซ์ที่ติดตั้งไว้แต่ละรายการของส่วนขยายจะมีสิทธิ์เข้าถึงพารามิเตอร์เริ่มต้นหลายรายการที่ Firebase สร้างขึ้นโดยอัตโนมัติโดยอัตโนมัติ (ดูตารางด้านล่าง) ค่าพารามิเตอร์เหล่านี้อาจเป็นค่าเริ่มต้นสำหรับโปรเจ็กต์ Firebase (เช่น ที่เก็บข้อมูล เริ่มต้น) หรือเป็นค่าเฉพาะส่วนขยาย (เช่น รหัสอินสแตนซ์ของส่วนขยาย)

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

แม้ว่า Firebase จะป้อนค่าพารามิเตอร์เหล่านี้โดยอัตโนมัติสําหรับส่วนขยาย แต่Firebase จะไม่จัดสรรผลิตภัณฑ์ที่เกี่ยวข้องให้ผู้ใช้โดยอัตโนมัติในระหว่างการติดตั้ง ผู้ใช้ที่ติดตั้งส่วนขยายต้องเปิดใช้ผลิตภัณฑ์ที่เกี่ยวข้องและเกี่ยวข้องในโปรเจ็กต์ก่อนติดตั้ง เช่น หากส่วนขยายของคุณเกี่ยวข้องกับ Cloud Firestore ผู้ใช้จะต้องตั้งค่า Cloud Firestore ในโปรเจ็กต์ เราขอแนะนำให้แจ้งให้ผู้ใช้ทราบเกี่ยวกับข้อกำหนดเหล่านี้ในPREINSTALL.md ไฟล์

ข้อมูลอ้างอิงสําหรับพารามิเตอร์ที่ระบบป้อนข้อมูลอัตโนมัติ คำอธิบาย ค่าพารามิเตอร์ (Firebase เป็นผู้ระบุ)
พารามิเตอร์ที่มีค่าเริ่มต้นจากโปรเจ็กต์ Firebase
PROJECT_ID ตัวระบุที่ไม่ซ้ำกันสำหรับโปรเจ็กต์ Firebase ที่ติดตั้งส่วนขยาย

รูปแบบทั่วไป:
project-id

ค่าตัวอย่าง:
project-123

DATABASE_URL URL อินสแตนซ์ Realtime Database เริ่มต้นของโปรเจ็กต์ Firebase

รูปแบบทั่วไป:
https://project-id-default-rtdb.firebaseio.com
(อินสแตนซ์ในสหรัฐอเมริกา)
หรือ
https://project-id-default-rtdb.region-code.firebasedatabase.app
(อินสแตนซ์นอกสหรัฐอเมริกา)

ค่าตัวอย่าง ได้แก่
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

ชื่ออินสแตนซ์ Realtime Database เริ่มต้นของโปรเจ็กต์ Firebase

โดยปกติแล้วค่านี้จะเหมือนกับรหัสโปรเจ็กต์ หรือลงท้ายด้วย -default-rtdb

รูปแบบทั่วไป:
project-id

ค่าตัวอย่าง:
project-123

STORAGE_BUCKET ชื่อที่เก็บข้อมูล Cloud Storage เริ่มต้นของโปรเจ็กต์ Firebase

รูปแบบทั่วไป:
project-id.appspot.com

ค่าตัวอย่าง:
project-123.appspot.com

พารามิเตอร์ที่มีค่าเริ่มต้นจากการติดตั้งส่วนขยาย
EXT_INSTANCE_ID

ตัวระบุที่ไม่ซ้ำกันสำหรับอินสแตนซ์ส่วนขยายที่ติดตั้ง

ค่านี้สร้างขึ้นจากช่อง name ที่ระบุในไฟล์ extension.yaml

รูปแบบทั่วไปของอินสแตนซ์ที่ติดตั้งครั้งแรก (Firebase กำหนดโดยอัตโนมัติ แก้ไขโดยผู้ใช้ระหว่างการติดตั้งไม่ได้) ดังนี้
name-from-extension.yaml

ค่าตัวอย่าง:
my-awesome-extension


รูปแบบทั่วไปสำหรับอินสแตนซ์ที่ติดตั้งครั้งที่ 2 ขึ้นไป (Firebase จะกำหนดโดยอัตโนมัติ ผู้ใช้สามารถแก้ไขได้ในระหว่างการติดตั้ง)
name-from-extension.yaml-4-digit-alphanumeric-hash

ค่าตัวอย่าง ได้แก่
my-awesome-extension-6m31

พารามิเตอร์ที่ผู้ใช้กําหนดค่า

หากต้องการให้ผู้ใช้ปรับแต่งอินสแตนซ์ที่ติดตั้งไว้แต่ละรายการของส่วนขยาย คุณสามารถขอให้ผู้ใช้ระบุค่าพารามิเตอร์ระหว่างการติดตั้งได้ หากต้องการขอค่าเหล่านี้ ให้ตั้งค่าพรอมต์ในส่วน params ของไฟล์ extension.yaml

ต่อไปนี้คือตัวอย่างส่วน params ตามด้วยตารางที่อธิบายช่องพารามิเตอร์ที่มีอยู่ทั้งหมด

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

ในส่วน params ของไฟล์ extension.yaml ให้ใช้ช่องต่อไปนี้เพื่อกําหนดพารามิเตอร์ที่ผู้ใช้กําหนดค่า

ฟิลด์ ประเภท คำอธิบาย
param
(ต้องระบุ) 		สตริง ชื่อพารามิเตอร์
label
(ต้องระบุ) 		สตริง

คําอธิบายสั้นๆ สําหรับพารามิเตอร์

แสดงต่อผู้ใช้เมื่อระบบแจ้งให้ป้อนค่าของพารามิเตอร์

description
(ไม่บังคับ) 		สตริง

คําอธิบายโดยละเอียดสําหรับพารามิเตอร์

แสดงต่อผู้ใช้เมื่อระบบแจ้งให้ป้อนค่าของพารามิเตอร์

รองรับมาร์กดาวน์

type
(ไม่บังคับ) 		สตริง

กลไกการป้อนข้อมูลสำหรับวิธีที่ผู้ใช้ตั้งค่าของพารามิเตอร์ (เช่น ป้อนข้อความโดยตรงหรือเลือกจากรายการแบบเลื่อนลง)

ค่าที่ใช้ได้มีดังนี้

  • string: อนุญาตให้ป้อนข้อความรูปแบบอิสระ (ตามข้อจำกัดของvalidationRegex)
  • select: อนุญาตให้เลือก 1 รายการจากตัวเลือกที่กำหนดไว้ล่วงหน้า หากระบุค่านี้ คุณต้องกำหนดช่อง options ด้วย
  • multiSelect: อนุญาตให้เลือกรายการอย่างน้อย 1 รายการจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า หากระบุค่านี้ คุณต้องกำหนดช่อง options ด้วย
  • selectResource: อนุญาตให้เลือกทรัพยากร Firebase บางประเภท (เช่น ที่เก็บข้อมูล Cloud Storage) จากโปรเจ็กต์ของผู้ใช้

    เมื่อคุณระบุพารามิเตอร์ประเภทนี้ ผู้ใช้จะได้รับวิดเจ็ตการเลือกที่ใช้งานง่ายขึ้นใน UI การติดตั้ง ดังนั้นให้ใช้พารามิเตอร์ selectResource ทุกครั้งที่เป็นไปได้

    หากระบุค่านี้ คุณต้องกำหนดช่อง resourceType ด้วย

  • secret: อนุญาตให้จัดเก็บสตริงที่ละเอียดอ่อน เช่น คีย์ API สำหรับบริการของบุคคลที่สาม ระบบจะจัดเก็บค่าเหล่านี้ไว้ในเครื่องมือจัดการข้อมูลลับของ Cloud

    Cloud Secret Manager เป็นบริการที่มีค่าใช้จ่าย การใช้งานดังกล่าวอาจส่งผลให้มีการเรียกเก็บเงินสำหรับผู้ใช้ที่ติดตั้งส่วนขยาย หากคุณใช้ประเภทพารามิเตอร์ secret โปรดบันทึกไว้ในไฟล์ PREINSTALL ว่าส่วนขยายของคุณใช้ Cloud Secret Manager

หากเว้นช่องนี้ไว้ พารามิเตอร์จะมีค่าเริ่มต้นเป็น type ของ string

options
(ต้องระบุหากพารามิเตอร์ type เป็น select หรือ multiSelect) 		list

รายการค่าที่ผู้ใช้เลือกได้

รวมช่อง label และ value ไว้ในช่อง options ดังนี้

  • label (สตริง): คำอธิบายสั้นๆ ของตัวเลือกที่เลือกได้
  • value (สตริง): ค่าจริงของตัวเลือกที่เลือกได้

ต้องกรอกข้อมูลในช่อง value สำหรับช่อง options
หากไม่ใส่ label ตัวเลือกรายการจะมีค่าเริ่มต้นเป็นการแสดง value
resourceType
(ต้องระบุหากพารามิเตอร์ type เป็น selectResource) 		สตริง

ประเภททรัพยากร Firebase ที่แจ้งให้ผู้ใช้เลือก ปัจจุบันมีเพียงที่เก็บข้อมูล Cloud Storage เท่านั้นที่รองรับตัวเลือกทรัพยากร

ประเภททรัพยากร รหัสประเภท
ที่เก็บข้อมูล Cloud Storage รายการ storage.googleapis.com/Bucket

ระบบจะไม่สนใจค่า resourceType ที่ไม่รู้จัก และ UI จะแสดงผลพารามิเตอร์เป็นช่องป้อนข้อมูล string รูปแบบอิสระ
example
(ไม่บังคับ) 		สตริง

ตัวอย่างค่าสําหรับพารามิเตอร์
validationRegex
(ไม่บังคับ)
(ใช้ได้เฉพาะเมื่อพารามิเตอร์ type เป็น string) 		สตริง

สตริงนิพจน์ทั่วไปสำหรับการตรวจสอบค่าที่ผู้ใช้กําหนดค่าไว้ของพารามิเตอร์

นิพจน์ทั่วไปจะคอมไพล์โดยใช้ไลบรารี go: RE2

ดูรายละเอียดเกี่ยวกับการตรวจสอบได้ที่ข้อความยืนยันและข้อผิดพลาดด้านล่าง

validationErrorMessage
(ไม่บังคับ) 		สตริง

ข้อความแสดงข้อผิดพลาดที่จะแสดงหาก validationRegex ดำเนินการไม่สำเร็จ

ดูรายละเอียดเกี่ยวกับข้อความแสดงข้อผิดพลาดได้ที่การตรวจสอบและข้อความแสดงข้อผิดพลาดด้านล่าง

default
(ไม่บังคับ) 		สตริง

ค่าเริ่มต้นสำหรับพารามิเตอร์ในกรณีที่ผู้ใช้ปล่อยค่าของพารามิเตอร์ว่างไว้

คุณระบุค่าของพารามิเตอร์ที่สร้างโดยอัตโนมัติให้กับค่า default ได้ (เช่น ดูพารามิเตอร์ IMG_BUCKET ของส่วนขยายปรับขนาดรูปภาพ)

required
(ไม่บังคับ) 		boolean

กำหนดว่าผู้ใช้จะส่งสตริงว่างได้หรือไม่เมื่อระบบแจ้งให้ป้อนค่าพารามิเตอร์

หากไม่ใส่ required ค่าเริ่มต้นของค่านี้จะมีค่าเป็น true (นั่นคือพารามิเตอร์ที่ต้องระบุ)

immutable
(ไม่บังคับ) 		boolean

กําหนดว่าผู้ใช้จะเปลี่ยนค่าของพารามิเตอร์ได้หรือไม่หลังจากการติดตั้ง (เช่น หากผู้ใช้กําหนดค่าใหม่ส่วนขยาย)

หากไม่ระบุ immutable ค่าเริ่มต้นจะเป็น false

หมายเหตุ: หากคุณกําหนดพารามิเตอร์ "location" สําหรับฟังก์ชันที่ติดตั้งใช้งานของส่วนขยาย คุณควรใส่ช่อง immutable นี้ไว้ในออบเจ็กต์ param

การตรวจสอบความถูกต้องและข้อความแสดงข้อผิดพลาดสำหรับค่าที่ผู้ใช้กำหนดค่า

เมื่อตั้งค่าพารามิเตอร์ด้วย type เป็น string คุณต้องกำหนดการตรวจสอบนิพจน์ทั่วไปที่เหมาะสมผ่านช่อง validationRegex ของพารามิเตอร์

นอกจากนี้ สําหรับส่วนขยายจํานวนมาก ค่าพารามิเตอร์ที่ขอกันโดยทั่วไปคือเส้นทางฐานข้อมูลหรือที่เก็บข้อมูล Cloud Storage โปรดทราบว่าในระหว่างการติดตั้ง การกำหนดค่าใหม่ หรืออัปเดต บริการ Extensions จะไม่ตรวจสอบรายการต่อไปนี้เมื่อป้อนค่าพารามิเตอร์

  • มีการตั้งค่าฐานข้อมูลหรือที่เก็บข้อมูล Cloud Storage ที่ระบุภายในโปรเจ็กต์ Firebase ของผู้ใช้หรือไม่
  • เส้นทางฐานข้อมูลที่ระบุอยู่ในฐานข้อมูลของผู้ใช้หรือไม่

อย่างไรก็ตาม เมื่อส่วนขยายกำลังทำให้ทรัพยากรใช้งานได้จริง Firebase Console หรือ Firebase CLI จะแสดงข้อความแสดงข้อผิดพลาดหากยังไม่ได้ตั้งค่าฐานข้อมูลที่อ้างอิงหรือที่เก็บข้อมูล Cloud Storage ในโปรเจ็กต์

เราขอแนะนําอย่างยิ่งให้คุณแจ้งผู้ใช้ในไฟล์ PREINSTALLเกี่ยวกับข้อกําหนดเหล่านี้ เพื่อให้การติดตั้งส่วนขยายสําเร็จและทํางานตามที่คาดไว้เมื่อผู้ใช้ติดตั้ง

พารามิเตอร์ของระบบ

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

ปกติแล้วคุณไม่จำเป็นต้องประกาศพารามิเตอร์เหล่านี้ใน extension.yaml ระบบจะกําหนดค่าเหล่านี้โดยอัตโนมัติสําหรับอินสแตนซ์ส่วนขยายทุกรายการ และผู้ใช้มีโอกาสที่จะตั้งค่าที่กำหนดเองเมื่อติดตั้งส่วนขยาย

อย่างไรก็ตาม หากส่วนขยายมีข้อกำหนดพิเศษเกี่ยวกับทรัพยากร คุณสามารถกําหนดค่าที่เฉพาะเจาะจงในระดับทรัพยากรแต่ละรายการใน extension.yaml การตั้งค่าการกําหนดค่าต่อทรัพยากรเหล่านี้จะลบล้างการตั้งค่าส่วนขยายของผู้ใช้ทั่วทั้งอินสแตนซ์ เช่น

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

พารามิเตอร์ของระบบที่ใช้ได้มีดังนี้

ชื่อ ป้ายกํากับ (ใช้งานง่าย) ฟิลด์ที่เกี่ยวข้องใน properties คำอธิบาย
firebaseextensions.v1beta.function/location ตำแหน่ง location ควรทำให้ Cloud Functions ใช้งานได้ในภูมิภาคใด
firebaseextensions.v1beta.function/memory หน่วยความจำของฟังก์ชัน memory ควรจัดสรรหน่วยความจําให้กับแต่ละฟังก์ชันเป็นจํานวนเท่าใดเมกะไบต์
firebaseextensions.v1beta.function/timeoutSeconds หมดเวลาของฟังก์ชัน timeout ฟังก์ชันควรทำงานก่อนหมดเวลาเป็นเวลากี่วินาที
firebaseextensions.v1beta.function/vpcConnectorEgressSettings ขาออกของเครื่องมือเชื่อมต่อ VPC vpcConnectorEgressSettings ควบคุมการรับส่งข้อมูลขาออกเมื่อกำหนดค่าเครื่องมือเชื่อมต่อ VPC แล้ว
firebaseextensions.v1beta.function/vpcConnector เครื่องมือเชื่อมต่อ VPC vpcConnector เชื่อมต่อ Cloud Functions กับเครื่องมือเชื่อมต่อ VPC ที่ระบุ
firebaseextensions.v1beta.function/minInstances อินสแตนซ์ของฟังก์ชันขั้นต่ำ minInstances จำนวนอินสแตนซ์ขั้นต่ำของฟังก์ชันนี้ที่จะเรียกใช้พร้อมกัน
firebaseextensions.v1beta.function/maxInstances อินสแตนซ์ของฟังก์ชันสูงสุด maxInstances จำนวนอินสแตนซ์สูงสุดของฟังก์ชันนี้ที่จะทํางานพร้อมกัน
firebaseextensions.v1beta.function/ingressSettings การตั้งค่า Ingress ingressSettings ควบคุมว่ายอมรับการรับส่งข้อมูลขาเข้าจากที่ไหน
firebaseextensions.v1beta.function/labels ป้ายกำกับ labels ป้ายกำกับที่จะใช้กับทรัพยากรทั้งหมดในส่วนขยาย