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

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

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

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

  • ใน extension.yaml และ POSTINSTALL.md ให้ใช้ ${param:PARAMETER_NAME}

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

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

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

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

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

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

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

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

DATABASE_URL URL ของอินสแตนซ์ default 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

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

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

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

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

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

รูปแบบทั่วไป
PROJECT_ID.firebasestorage.app

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

พารามิเตอร์ที่มีค่าเริ่มต้นจากการติดตั้งส่วนขยาย
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 สำหรับบริการของบุคคลที่สาม ระบบจะจัดเก็บค่าเหล่านี้ไว้ใน Secret Manager ของ Cloud

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

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

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

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

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

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

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

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

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

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

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

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

ระบบจะคอมไพล์นิพจน์ทั่วไปโดยใช้ไลบรารี 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 คอนโซลหรือ 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 การตั้งค่าขาเข้า ingressSettings ควบคุมว่าระบบจะยอมรับการรับส่งข้อมูลขาเข้าจากที่ใด
firebaseextensions.v1beta.function/labels ป้ายกำกับ labels ป้ายกำกับที่จะใช้กับทรัพยากรทั้งหมดในส่วนขยาย