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

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

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

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

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