ไฟล์ข้อกำหนดของส่วนขยายของคุณ ( 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 ตัว หมายเหตุ: ค่านี้ใช้เพื่อสร้าง ID อินสแตนซ์ของส่วนขยาย (ซึ่งจากนั้นจะใช้เพื่อสร้างชื่อบัญชีบริการของส่วนขยายและทรัพยากรเฉพาะของส่วนขยาย) | ||||||||
version เชือก (ที่จำเป็น) | เวอร์ชันของส่วนขยาย ต้องเป็นไปตามการกำหนดเวอร์ชันของ semver (เช่น 1.2.0) | ||||||||
specVersion เชือก (ที่จำเป็น) | เวอร์ชันของข้อกำหนดส่วนขยาย Firebase มูลค่าปัจจุบัน: | ||||||||
license เชือก (ไม่จำเป็น) | ใบอนุญาตสำหรับการขยายเวลา ส่วนขยายของคุณต้องได้รับอนุญาตโดยใช้ | ||||||||
billingRequired บูลีน (ไม่จำเป็น) | บริการที่ใช้โดยส่วนขยายนั้นจำเป็นต้องมีบัญชีการเรียกเก็บเงิน Firebase แบบชำระเงินหรือไม่ ตั้งค่าเป็น | ||||||||
displayName เชือก (ไม่จำเป็น) | ชื่อที่แสดงที่เป็นมิตรสำหรับส่วนขยาย (3-5 คำ) จำกัดจำนวนอักขระ 40 ตัว | ||||||||
description เชือก (ไม่จำเป็น) | คำอธิบายโดยย่อเกี่ยวกับงานที่ส่วนขยายของคุณดำเนินการ (ประมาณ 1 ประโยค) | ||||||||
icon เชือก (ไม่จำเป็น) | ไฟล์ที่จะใช้เป็นไอคอนส่วนขยายของคุณบน ไฟล์นี้ต้องเป็น PNG สี่เหลี่ยมจัตุรัสที่มีขนาดระหว่าง 512x512 ถึง 1024x1024 พิกเซล วางไฟล์ไว้ในไดเร็กทอรีเดียวกับ โปรดคำนึงถึงหลักเกณฑ์ต่อไปนี้เมื่อออกแบบไอคอนสำหรับส่วนขยายของคุณ:
| ||||||||
tags รายการสตริง (ไม่จำเป็น) | แท็กเพื่อช่วยให้ผู้ใช้ค้นพบส่วนขยายของคุณ แท็กต่อไปนี้แมปกับหมวดหมู่บน Extensions Hub: marketing , messaging , payments , search , shipping , social , utilities , ai | ||||||||
sourceUrl เชือก (ไม่จำเป็น) | URL สาธารณะที่สามารถเข้าถึงไดเร็กทอรีส่วนขยายได้ | ||||||||
releaseNotesUrl เชือก (ไม่จำเป็น) | URL สาธารณะที่สามารถเข้าถึงบันทึกประจำรุ่นสำหรับส่วนขยายได้ | ||||||||
author วัตถุผู้เขียนหนึ่งคน (ไม่จำเป็น) | ผู้เขียนหลักและผู้ติดต่อสำหรับส่วนขยาย 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 เชือก (ไม่จำเป็น) | ข้อความแสดงข้อผิดพลาดที่จะแสดงหากการตรวจสอบความถูกต้องของ regex ล้มเหลว |
required บูลีน (ไม่จำเป็น) | กำหนดว่าผู้ใช้สามารถส่งสตริงว่างได้หรือไม่ เมื่อได้รับพร้อมท์ให้ใส่ค่าของพารามิเตอร์ ค่าเริ่มต้นเป็น true |
immutable บูลีน (ไม่จำเป็น) | กำหนดว่าผู้ใช้สามารถเปลี่ยนค่าของพารามิเตอร์หลังการติดตั้งได้หรือไม่ (เช่น กำหนดค่าส่วนขยายใหม่หรือไม่) ค่าเริ่มต้นเป็น หมายเหตุ: หากคุณกำหนดพารามิเตอร์ "ตำแหน่ง" สำหรับฟังก์ชันที่ปรับใช้ของส่วนขยายของคุณ ให้ตั้งค่าฟิลด์นี้เป็น |
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 Functions ที่รวมอยู่ในส่วนขยาย ไวยากรณ์การประกาศทรัพยากรมีลักษณะแตกต่างกันเล็กน้อยระหว่างฟังก์ชันรุ่นที่ 1 และรุ่นที่ 2 ซึ่งสามารถอยู่ร่วมกันในส่วนขยายได้
ฟังก์ชั่นคลาวด์รุ่นที่ 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 (ที่จำเป็น) | คุณสมบัติฟังก์ชั่นคลาวด์รุ่นที่ 1 คุณสมบัติที่สำคัญที่สุดแสดงอยู่ด้านล่าง แต่คุณสามารถดูรายการทั้งหมดได้ใน ข้อมูลอ้างอิง 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 (ที่จำเป็น) | คุณสมบัติฟังก์ชันคลาวด์รุ่นที่ 2 คุณสมบัติที่สำคัญที่สุดแสดงอยู่ด้านล่าง แต่คุณสามารถดูรายการทั้งหมดได้ใน ข้อมูลอ้างอิง Cloud Functions
นอกจากนี้ยังมีฟิลด์ประเภทอ็อบเจ็กต์สามฟิลด์ที่มีคุณสมบัติของตัวเอง:
|
เหตุการณ์วงจรชีวิต
กิจกรรมวงจรการใช้งานช่วยให้คุณระบุฟังก์ชันที่จะทำงานเมื่อผู้ใช้ติดตั้ง อัปเดต หรือกำหนดค่าอินสแตนซ์ของส่วนขยายของคุณ ดู จัดการเหตุการณ์วงจรการใช้งานของส่วนขยายของคุณ
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 ใน Add user hooks to an extension
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 เชือก (ที่จำเป็น) | คำอธิบายของเหตุการณ์ |