ไฟล์ข้อกำหนดของส่วนขยาย (extension.yaml
) ประกอบด้วยข้อมูลเมตาของส่วนขยาย ประกาศทรัพยากรที่ส่วนขยายสร้างขึ้นและ API และการเข้าถึงที่ส่วนขยายกำหนด รวมทั้งระบุพารามิเตอร์ที่ส่วนขยายกำหนดโดยผู้ใช้
ตารางในหน้านี้อธิบายช่องที่มีสำหรับไฟล์ extension.yaml
ข้อมูลพื้นฐานและการระบุตัวตน
name: your-extension-name
version: 1.0.0 # Semantic versioning (semver)
specVersion: v1beta # Always "v1beta"
license: Apache-2.0 # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true # Always "true"
displayName: Your extension name
description: >-
Description of the extension. (One or two
sentences.)
icon: icon.png
tags: [tag, anothertag]
sourceUrl: https://github.com/your-org/your-repo # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md
author:
authorName: Your Company
email: extensions@example.com
url: https://example.com/
contributors:
- authorName: Your Name
- authorName: Another Contributor
email: colleague@example.net
url: https://github.com/their-org/
ช่องพื้นฐาน | |||||||||
---|---|---|---|---|---|---|---|---|---|
name สตริง (ต้องระบุ) |
ตัวระบุส่วนขยาย มีได้เฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข และเครื่องหมายขีดกลาง โดยมีความยาวไม่เกิน 40 อักขระ หมายเหตุ: ค่านี้จะใช้ในการสร้างรหัสอินสแตนซ์ของส่วนขยาย (ซึ่งจะนำมาใช้สร้างชื่อบัญชีบริการของส่วนขยายและทรัพยากรเฉพาะส่วนขยาย) |
||||||||
version สตริง (ต้องระบุ) |
เวอร์ชันของส่วนขยาย ต้องเป็นไปตามการกำหนดเวอร์ชันเซมเวอร์ (เช่น 1.2.0) |
||||||||
specVersion สตริง (ต้องระบุ) |
เวอร์ชันของข้อกำหนดเฉพาะของ Firebase Extensions ค่าปัจจุบัน: |
||||||||
license สตริง (ไม่บังคับ) |
ใบอนุญาตสำหรับส่วนขยาย ส่วนขยายของคุณต้องได้รับอนุญาตโดยใช้ |
||||||||
billingRequired บูลีน (ไม่บังคับ) |
บริการที่ส่วนขยายใช้ต้องมีบัญชีสำหรับการเรียกเก็บเงิน Firebase ระดับแบบชำระเงินหรือไม่ ตั้งค่าเป็น |
||||||||
displayName สตริง (ไม่บังคับ) |
ชื่อที่แสดงของส่วนขยายที่สะดวก (3-5 คำ) จำนวนอักขระสูงสุด 40 ตัว |
||||||||
description สตริง (ไม่บังคับ) |
คำอธิบายสั้นๆ เกี่ยวกับงานที่ส่วนขยายทำ (ประมาณ 1 ประโยค) | ||||||||
icon สตริง (ไม่บังคับ) |
ไฟล์ที่จะใช้เป็นไอคอนของส่วนขยายใน ไฟล์นี้ต้องเป็นไฟล์สี่เหลี่ยมจัตุรัส PNG ขนาดระหว่าง 512x512 ถึง 1024x1024 พิกเซล
ย้ายไฟล์ไว้ในไดเรกทอรีเดียวกับ โปรดคำนึงถึงหลักเกณฑ์ต่อไปนี้เมื่อออกแบบไอคอนสำหรับส่วนขยาย
|
||||||||
tags รายการสตริง (ไม่บังคับ) |
แท็กเพื่อช่วยให้ผู้ใช้ค้นพบส่วนขยายของคุณ
แท็กต่อไปนี้แมปกับหมวดหมู่ในฮับส่วนขยาย ซึ่งได้แก่
marketing ,
messaging ,
payments ,
search ,
shipping ,
social ,
utilities ,
ai
|
||||||||
sourceUrl สตริง (ไม่บังคับ) |
URL สาธารณะที่เข้าถึงไดเรกทอรีส่วนขยายได้ | ||||||||
releaseNotesUrl สตริง (ไม่บังคับ) |
URL สาธารณะที่สามารถเข้าถึงบันทึกประจำรุ่นของส่วนขยาย | ||||||||
author ออบเจ็กต์ผู้เขียน 1 รายการ (ไม่บังคับ) |
ผู้เขียนหลักและผู้ติดต่อสำหรับส่วนขยาย author: authorName: Your Company email: extensions@example.com url: https://example.com/
|
||||||||
contributors รายการออบเจ็กต์ผู้เขียน (ไม่บังคับ) |
ผู้เขียนที่ร่วมให้ข้อมูลเพิ่มเติมสำหรับส่วนขยาย contributors: - authorName: Your Name - authorName: Another Contributor email: colleague@example.net url: https://github.com/their-org/
|
Firebase และ Google Cloud API
ช่องเหล่านี้ระบุ Firebase และ Google API ที่ส่วนขยายใช้ เมื่อผู้ใช้ติดตั้งส่วนขยาย คุณเลือกที่จะเปิดใช้ API เหล่านี้ในโปรเจ็กต์ได้โดยอัตโนมัติ
apis:
- apiName: apiname.googleapis.com
reason: Explanation of why the extension uses this API
- apiName: anotherapiname.googleapis.com
reason: Explanation of why the extension uses this API
ช่อง API | |
---|---|
apiName สตริง (ต้องระบุ) |
ชื่อ Google API ต้องสอดคล้องกับช่องชื่อบริการตามที่แสดงในหน้าภาพรวมของ API แต่ละรายการ (ตัวอย่าง) ในไลบรารี Google Cloud API |
reason สตริง (ต้องระบุ) |
คำอธิบายสั้นๆ ถึงเหตุผลที่ส่วนขยายต้องใช้ API นี้ |
บทบาท IAM
ช่องเหล่านี้ระบุบทบาท Cloud IAM ที่ส่วนขยายต้องการ บัญชีบริการที่จัดสรรสำหรับส่วนขยายจะได้รับบทบาทเหล่านี้
คุณจะระบุบทบาทที่รองรับได้เพียงบทบาทเดียวเท่านั้น
roles:
- role: product.role
reason: Explanation of why the extension needs this level of access
- role: anotherproduct.role
resource: projects/${project_id}/resource_type/*
reason: Explanation of why the extension needs this level of access
ช่องบทบาท | |
---|---|
role สตริง (ต้องระบุ) |
ชื่อของบทบาท IAM ที่จำเป็นสำหรับการดำเนินการของส่วนขยาย ต้องเป็นบทบาทที่รองรับ |
reason สตริง (ต้องระบุ) |
คำอธิบายสั้นๆ ถึงเหตุผลที่ส่วนขยายต้องการสิทธิ์เข้าถึงที่ได้รับจากบทบาทนี้ |
resource สตริง (ไม่บังคับ) |
จำกัดขอบเขตของบทบาทสำหรับทรัพยากรนี้ หากไม่ระบุ จะมีค่าเริ่มต้นเป็น |
บริการภายนอก
ช่องเหล่านี้จะระบุบริการที่ไม่ใช่ Firebase และบริการที่ไม่ใช่ของ Google ที่ส่วนขยายใช้ (โดยทั่วไปคือ REST API) แพลตฟอร์ม Firebase Extensions ไม่ได้หมายถึงการเปิดใช้หรือดำเนินการให้สิทธิ์สำหรับบริการเหล่านี้โดยอัตโนมัติ
externalServices:
- name: Example API
pricingUri: https://developers.example.com/pricing
- name: Another Example API
pricingUri: https://developers.example.com/pricing
ช่องบริการภายนอก | |
---|---|
name สตริง (ต้องระบุ) |
ชื่อบริการภายนอกที่จำเป็นสำหรับการดำเนินการของส่วนขยาย |
pricingUri สตริง (ต้องระบุ) |
URI ของข้อมูลการกำหนดราคาสำหรับบริการ |
พารามิเตอร์ที่ผู้ใช้กำหนดค่าได้
ช่องเหล่านี้จะกำหนดพารามิเตอร์ที่ส่วนขยายทำให้ผู้ใช้กำหนดค่าได้
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What do you want to set PARAM_ID to?
This is a longer description of the parameter, often phrased as a prompt
to the user.
- param: ANOTHER_PARAM_ID
label: Short description of the parameter
description: >
What do you want to set ANOTHER_PARAM_ID to?
This is a longer description of the parameter.
example: example-input
validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
validationErrorMessage:
Must be a hyphen-delimited string of alphabetic characters
default: default-value
required: false
immutable: true
ช่องพารามิเตอร์ | |
---|---|
param สตริง (ต้องระบุ) |
ชื่อพารามิเตอร์ คุณใช้ชื่อนี้เพื่ออ้างอิงค่าพารามิเตอร์ในโค้ดได้ |
label สตริง (ต้องระบุ) |
คำอธิบายสั้นๆ สำหรับพารามิเตอร์ แสดงต่อผู้ใช้เมื่อได้รับแจ้งให้ใส่ค่าของพารามิเตอร์ |
description สตริง (ไม่บังคับ) |
คำอธิบายโดยละเอียดสำหรับพารามิเตอร์ แสดงต่อผู้ใช้เมื่อได้รับแจ้งให้ใส่ค่าของพารามิเตอร์ รองรับมาร์กดาวน์ |
example สตริง (ไม่บังคับ) |
ค่าตัวอย่างสำหรับพารามิเตอร์ |
default สตริง (ไม่บังคับ) |
ค่าเริ่มต้นสำหรับพารามิเตอร์หากผู้ใช้ไม่ป้อนค่าของพารามิเตอร์ |
validationRegex สตริง (ไม่บังคับ) |
นิพจน์ทั่วไปสำหรับการตรวจสอบค่าที่ผู้ใช้กำหนดค่าของพารามิเตอร์ ไวยากรณ์ Google RE2 |
validationErrorMessage สตริง (ไม่บังคับ) |
ข้อความแสดงข้อผิดพลาดที่จะแสดงเมื่อตรวจสอบนิพจน์ทั่วไปไม่สำเร็จ |
required บูลีน (ไม่บังคับ) |
กำหนดว่าผู้ใช้จะส่งสตริงว่างได้หรือไม่เมื่อได้รับแจ้งให้ใส่ค่าของพารามิเตอร์ ค่าเริ่มต้นคือ true
|
immutable บูลีน (ไม่บังคับ) |
กำหนดว่าผู้ใช้จะเปลี่ยนค่าของพารามิเตอร์หลังการติดตั้งได้หรือไม่ (เช่น กำหนดค่าส่วนขยายใหม่) ค่าเริ่มต้นคือ หมายเหตุ: หากคุณกำหนดพารามิเตอร์ "location" สำหรับฟังก์ชันที่ทำให้ใช้งานได้ของส่วนขยาย ให้ตั้งค่าช่องนี้เป็น |
type สตริง (ไม่บังคับ) |
ประเภทพารามิเตอร์ ประเภทพารามิเตอร์พิเศษอาจมีข้อกำหนดเพิ่มเติมหรือการแสดง UI ที่แตกต่างออกไป โปรดดูส่วนต่อไปนี้ |
พารามิเตอร์แบบเลือกได้และเลือกหลายรายการได้
พารามิเตอร์แบบเลือกได้และเลือกได้หลายรายการจะแจ้งให้ผู้ใช้เลือกจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
Do you want to enable the option?
type: select
options:
- label: Yes
value: true
- label: No
value: false
- param: ANOTHER_PARAM_ID
label: Short description of the parameter
description: >-
Which options do you want to enable?
type: multiselect
options:
- value: red
- value: green
- value: blue
ช่องพารามิเตอร์แบบหลายตัวเลือก | |||||||
---|---|---|---|---|---|---|---|
สตริง type |
ระบุว่าพารามิเตอร์อาจเป็นค่าเดียว ( |
||||||
options รายการตัวเลือก (ต้องระบุ) |
ตัวเลือกที่ผู้ใช้สามารถเลือกได้
|
พารามิเตอร์ทรัพยากรที่เลือกได้
พารามิเตอร์ทรัพยากรที่เลือกได้จะแจ้งให้ผู้ใช้เลือกทรัพยากร (อินสแตนซ์ฐานข้อมูล ที่เก็บข้อมูลของพื้นที่เก็บข้อมูล ฯลฯ) จากโปรเจ็กต์ของตน
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
Which resource do you want to use?
type: selectresource
resourceType: product.googleapis.com/ResourceType
ช่องพารามิเตอร์ทรัพยากร | |
---|---|
สตริง type |
ระบุว่าพารามิเตอร์แสดงถึงทรัพยากรโปรเจ็กต์ |
resourceType สตริง (ต้องระบุ) |
ประเภทของทรัพยากรที่แจ้งให้ผู้ใช้เลือก ค่าที่ถูกต้อง:
อย่างไรก็ตาม ขณะนี้ที่เก็บข้อมูล Cloud Storage เท่านั้นที่มี UI การเลือก (ทรัพยากรประเภทอื่นๆ จะแสดงเป็นช่องป้อนข้อความรูปแบบอิสระ) |
พารามิเตอร์ลับ
ระบบจะจัดการค่าข้อมูลลับที่ผู้ใช้ระบุ (เช่น คีย์ API) ด้วยวิธีที่ต่างออกไป
- ค่าข้อมูลลับจะจัดเก็บโดยใช้ Cloud Secret Manager เฉพาะไคลเอ็นต์ที่ได้รับอนุญาต (เช่น อินสแตนซ์ที่ติดตั้งของส่วนขยาย) เท่านั้นที่เข้าถึงค่าเหล่านี้ได้
- เมื่อระบบแจ้งให้ผู้ใช้ระบุค่าเหล่านี้ ระบบจะไม่แสดงอินพุต
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
ช่องพารามิเตอร์ลับ | |
---|---|
สตริง type |
ระบุว่าพารามิเตอร์เป็นค่าลับ |
ทรัพยากร Cloud Function
ช่องเหล่านี้แจ้ง Cloud Functions ที่รวมอยู่ในส่วนขยาย ไวยากรณ์การประกาศทรัพยากรจะมีความแตกต่างเล็กน้อยระหว่างฟังก์ชันของรุ่นที่ 1 และ 2 ซึ่งจะอยู่ร่วมกันในส่วนขยายได้
Cloud Functions รุ่นที่ 1
resources:
- name: functionName
type: firebaseextensions.v1beta.function
description: >-
Description of what the function does. (One or two
sentences.)
properties:
runtime: runtime-version
eventTrigger:
eventType: google.product.event
resource: projects/_/resource/specifier
ช่องแหล่งข้อมูล | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name สตริง (ต้องระบุ) |
ชื่อที่เข้าใจง่ายสำหรับฟังก์ชันที่ส่งออก หากไม่ระบุพร็อพเพอร์ตี้ ชื่อสุดท้ายของฟังก์ชันทำให้ใช้งานได้แล้วจะอยู่ในรูปแบบต่อไปนี้ |
||||||||||||||||
type สตริง (ต้องระบุ) |
สำหรับทรัพยากรฟังก์ชันรุ่นที่ 1:
firebaseextensions.v1beta.function
|
||||||||||||||||
description สตริง (ต้องระบุ) |
คำอธิบายสั้นๆ เกี่ยวกับการทำงานของฟังก์ชันสำหรับส่วนขยาย |
||||||||||||||||
properties (ต้องระบุ) |
พร็อพเพอร์ตี้ Cloud Functions รุ่นที่ 1 พร็อพเพอร์ตี้ที่สำคัญที่สุดแสดงอยู่ด้านล่าง แต่คุณดูรายการทั้งหมดได้ในข้อมูลอ้างอิง Cloud Functions
|
Cloud Functions รุ่นที่ 2
resources:
- name: functionName
type: firebaseextensions.v1beta.v2function
description: >-
Description of what the function does. (One or two
sentences.)
properties:
buildConfig:
runtime: nodejs16
serviceConfig:
availableMemory: 512M
eventTrigger:
eventType: google.firebase.firebasealerts.alerts.v1.published
triggerRegion: global
eventFilters:
- attribute: alerttype
value: crashlytics.newFatalIssue
ช่องแหล่งข้อมูล | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name สตริง (ต้องระบุ) |
ชื่อที่เข้าใจง่ายสำหรับฟังก์ชันที่ส่งออก หากไม่ระบุพร็อพเพอร์ตี้ ชื่อสุดท้ายของฟังก์ชันทำให้ใช้งานได้แล้วจะอยู่ในรูปแบบต่อไปนี้ |
||||||||||||||||||||||||||||
type สตริง (ต้องระบุ) |
สำหรับทรัพยากรฟังก์ชันรุ่นที่ 2:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description สตริง (ต้องระบุ) |
คำอธิบายสั้นๆ เกี่ยวกับการทำงานของฟังก์ชันสำหรับส่วนขยาย |
||||||||||||||||||||||||||||
properties (ต้องระบุ) |
พร็อพเพอร์ตี้ Cloud Functions รุ่นที่ 2 พร็อพเพอร์ตี้ที่สำคัญที่สุดแสดงอยู่ด้านล่าง แต่คุณดูรายการทั้งหมดได้ในข้อมูลอ้างอิง Cloud Functions
นอกจากนี้ ยังมีช่องประเภทออบเจ็กต์ 3 ช่องที่มีพร็อพเพอร์ตี้ของตัวเองด้วย ดังนี้
|
เหตุการณ์ในวงจร
เหตุการณ์เกี่ยวกับวงจรให้คุณระบุฟังก์ชันที่จะทำงานเมื่อผู้ใช้ติดตั้ง อัปเดต หรือกำหนดค่าอินสแตนซ์ของส่วนขยาย โปรดดูหัวข้อจัดการเหตุการณ์ในวงจรของส่วนขยาย
lifecycleEvents:
onInstall:
function: myTaskFunction
processingMessage: Describes the task being completed
onUpdate:
function: myOtherTaskFunction
processingMessage: Describes the task being completed
onConfigure:
function: myOtherTaskFunction
processingMessage: Describes the task being completed
ช่องเหตุการณ์อายุการใช้งาน | |||||||
---|---|---|---|---|---|---|---|
onInstall (ไม่บังคับ) |
ระบุฟังก์ชันที่เรียกใช้เมื่อผู้ใช้ติดตั้งส่วนขยาย
|
||||||
onUpdate (ไม่บังคับ) |
ระบุฟังก์ชันที่เรียกใช้เมื่อผู้ใช้อัปเดตส่วนขยาย
|
||||||
onConfigure (ไม่บังคับ) |
ระบุฟังก์ชันที่เรียกใช้เมื่อผู้ใช้กำหนดค่าส่วนขยายอีกครั้ง
|
เหตุการณ์ที่กำหนดเอง (Eventarc)
เหตุการณ์ที่กำหนดเองคือเหตุการณ์ที่ส่วนขยายสร้างขึ้นเพื่อให้ผู้ใช้แทรกตรรกะของตนเองลงในส่วนขยายได้ ดูส่วน Eventarc ในเพิ่มฮุกผู้ใช้ลงในส่วนขยาย
events:
- type: publisher-id.extension-name.version.event-name
description: Description of the event
- type: publisher-id.extension-name.version.another-event-name
description: Description of the other event
ช่องเหตุการณ์ที่กำหนดเอง | |
---|---|
type สตริง (ต้องระบุ) |
ตัวระบุประเภทเหตุการณ์ สร้างตัวระบุจากช่องที่คั่นด้วยจุด 3-4 ช่อง โดยคุณต้องกรอกข้อมูลในช่องรหัสผู้เผยแพร่โฆษณา ชื่อส่วนขยาย และชื่อเหตุการณ์ โดยแนะนำให้กรอกข้อมูลในช่องเวอร์ชัน เลือกชื่อเหตุการณ์ที่ไม่ซ้ำกันและสื่อความหมายสําหรับเหตุการณ์แต่ละประเภทที่คุณเผยแพร่ |
description สตริง (ต้องระบุ) |
คำอธิบายของกิจกรรม |