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

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

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

เคล็ดลับ: ทั้ง 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.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: อนุญาตให้เลือกรายการเดียวจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า หากระบุค่านี้ คุณต้องกำหนดช่อง options ด้วย multiSelect: อนุญาตให้เลือกรายการอย่างน้อย 1 รายการจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า หากระบุค่านี้ คุณต้องกำหนดช่อง options ด้วย selectResource: อนุญาตให้เลือกทรัพยากร Firebase บางประเภท (เช่น บัケット Cloud Storage) จากโปรเจ็กต์ของผู้ใช้ เมื่อคุณระบุพารามิเตอร์ประเภทนี้ ผู้ใช้จะได้รับวิดเจ็ตการเลือกที่ใช้ง่ายขึ้นใน UI การติดตั้ง ด้วยเหตุนี้ ให้ใช้พารามิเตอร์ selectResource ทุกครั้งที่ทำได้ หากระบุค่านี้ คุณต้องกำหนดช่อง resourceType ด้วย secret: อนุญาตให้จัดเก็บสตริงที่ละเอียดอ่อน เช่น คีย์ API สำหรับบริการของบุคคลที่สาม ระบบจะจัดเก็บค่าเหล่านี้ไว้ใน Cloud Secret Manager 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 เป็นค่าเริ่มต้น ตัวอย่างไวยากรณ์ options: - label: value: - label: value: - label: value:
resourceType (ต้องระบุหากพารามิเตอร์ type เป็น selectResource)	สตริง	ประเภทของทรัพยากร Firebase ที่จะแจ้งให้ผู้ใช้เลือก ปัจจุบันมีเพียงที่เก็บข้อมูล Cloud Storage เท่านั้นที่รองรับตัวเลือกทรัพยากร ดังนี้ ประเภททรัพยากร รหัสประเภท Bucket 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 หรือ CLI Firebase จะแสดงข้อความแสดงข้อผิดพลาดหากยังไม่ได้ตั้งค่าฐานข้อมูลหรือบักเก็ต 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	ป้ายกำกับที่จะใช้กับทรัพยากรทั้งหมดในส่วนขยาย