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

พารามิเตอร์คือกลไกที่ผู้ใช้ปรับแต่งอินสแตนซ์ที่ติดตั้งของส่วนขยายแต่ละรายการ พารามิเตอร์เป็นเหมือนตัวแปรสภาพแวดล้อมสำหรับส่วนขยาย ค่าของพารามิเตอร์จะเป็นป้อนข้อมูลอัตโนมัติ (ได้มาจาก 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 (เช่น ที่เก็บข้อมูล เริ่มต้น) หรือเป็นค่าเฉพาะส่วนขยาย (เช่น รหัสอินสแตนซ์ของส่วนขยาย)

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

เคล็ดลับ: ทั้ง Realtime Database และ Cloud Storage อนุญาตให้มีอินสแตนซ์ฐานข้อมูลและที่เก็บข้อมูลหลายรายการในโปรเจ็กต์ 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 ตัวอย่างไวยากรณ์ options: - label: value: - label: value: - 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	ป้ายกำกับที่จะใช้กับทรัพยากรทั้งหมดในส่วนขยาย