يحتوي ملف مواصفات الامتداد الخاص بك ( extension.yaml
) على البيانات التعريفية لامتدادك، ويعلن عن الموارد التي تم إنشاؤها بواسطة الامتداد وواجهات برمجة التطبيقات والوصول الذي يتطلبه الامتداد، ويحدد أي معلمات تم تكوينها بواسطة المستخدم يوفرها الامتداد.
تصف الجداول الموجودة في هذه الصفحة الحقول المتاحة لملف 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 خيط (مطلوب) | نسخة الامتداد. يجب أن يتبع إصدارات semver (على سبيل المثال، 1.2.0). | ||||||||
specVersion خيط (مطلوب) | إصدار مواصفات ملحقات Firebase. القيمة الحالية: | ||||||||
license خيط (خياري) | ترخيص للتمديد. يجب أن يكون ملحقك مرخصًا باستخدام | ||||||||
billingRequired منطقية (خياري) | ما إذا كانت الخدمات التي يستخدمها الامتداد تتطلب حساب فوترة Firebase مدفوع المستوى. اضبط دائمًا على | ||||||||
displayName خيط (خياري) | اسم العرض المألوف للامتداد (3-5 كلمات). الحد الأقصى لعدد الأحرف هو 40 حرفًا. | ||||||||
description خيط (خياري) | وصف موجز للمهمة التي ينفذها الملحق الخاص بك (~جملة واحدة). | ||||||||
icon خيط (خياري) | ملف لاستخدامه كأيقونة لامتدادك على يجب أن يكون هذا الملف مربعًا بصيغة PNG بين 512 × 512 و1024 × 1024 بكسل. ضع الملف في نفس الدليل مثل ضع الإرشادات التالية في الاعتبار عند تصميم رمز لامتدادك:
| ||||||||
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 APIs
تحدد هذه الحقول واجهات برمجة تطبيقات Firebase وGoogle التي يستخدمها الامتداد. عندما يقوم المستخدمون بتثبيت الامتداد، يمكنهم اختيار تمكين واجهات برمجة التطبيقات هذه تلقائيًا في مشروعهم.
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
حقول واجهة برمجة التطبيقات | |
---|---|
apiName خيط (مطلوب) | اسم واجهة برمجة تطبيقات جوجل يجب أن يتوافق مع حقل اسم الخدمة كما هو مدرج في صفحة النظرة العامة لكل واجهة برمجة تطبيقات ( مثال ) في مكتبة Google Cloud API |
reason خيط (مطلوب) | وصف موجز لسبب حاجة الامتداد لاستخدام واجهة برمجة التطبيقات هذه |
أدوار 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 APIs). لا يوفر نظام 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 خيط (خياري) | تعبير عادي للتحقق من صحة القيمة التي قام المستخدم بتكوينها. بناء جملة جوجل RE2 . |
validationErrorMessage خيط (خياري) | رسالة خطأ يتم عرضها في حالة فشل التحقق من صحة التعبير العادي. |
required منطقية (خياري) | يحدد ما إذا كان يمكن للمستخدم إرسال سلسلة فارغة عند مطالبته بقيمة المعلمة. الافتراضيات إلى true . |
immutable منطقية (خياري) | يحدد ما إذا كان يمكن للمستخدم تغيير قيمة المعلمة بعد التثبيت (مثل إعادة تكوين الامتداد). الافتراضيات ملاحظة: إذا قمت بتحديد معلمة "موقع" للوظائف المنشورة لامتدادك، فاضبط هذا الحقل على |
type خيط (خياري) | نوع المعلمة. قد تحتوي أنواع المعلمات الخاصة على متطلبات إضافية أو عرض تقديمي مختلف لواجهة المستخدم. انظر الأقسام التالية. |
معلمات قابلة للتحديد ومتعددة التحديد
تطالب المعلمات القابلة للتحديد والمتعددة التحديد المستخدمين بالاختيار من قائمة الخيارات المحددة مسبقًا.
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 Secret Manager. يمكن فقط للعملاء المعتمدين (مثل المثيل المثبت للملحق) الوصول إلى هذه القيم.
- عندما يُطلب من المستخدمين تقديم هذه القيم، لا يتم عرض مدخلاتهم.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
حقول المعلمات السرية | |
---|---|
type خيط | يحدد أن المعلمة هي قيمة سرية |
موارد وظيفة السحابة
تعلن هذه الحقول عن وظائف السحابة المضمنة في الامتداد. يبدو بناء جملة إعلان المورد مختلفًا قليلاً بين وظائف الجيل الأول والثاني، والتي يمكن أن تتواجد معًا في الامتداد.
وظائف السحابة من الجيل الأول
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 خيط (مطلوب) | للحصول على مورد دالة من الجيل الأول: firebaseextensions.v1beta.function | ||||||||||||||||
description خيط (مطلوب) | وصف موجز للمهمة التي تؤديها الوظيفة للامتداد. | ||||||||||||||||
properties (مطلوب) | خصائص وظائف السحابة من الجيل الأول. تم إدراج أهم الخصائص أدناه، ولكن يمكنك العثور على القائمة الكاملة في مرجع وظائف السحابة .
|
وظائف السحابة من الجيل الثاني
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 خيط (مطلوب) | للحصول على مورد دالة من الجيل الثاني: firebaseextensions.v1beta.v2function | ||||||||||||||||||||||||||||
description خيط (مطلوب) | وصف موجز للمهمة التي تؤديها الوظيفة للامتداد. | ||||||||||||||||||||||||||||
properties (مطلوب) | خصائص وظائف السحابة من الجيل الثاني. تم إدراج أهم الخصائص أدناه، ولكن يمكنك العثور على القائمة الكاملة في مرجع وظائف السحابة .
هناك أيضًا ثلاثة حقول لنوع الكائن لها خصائصها الخاصة:
|
أحداث دورة الحياة
تتيح لك أحداث دورة الحياة تحديد الوظائف التي سيتم تشغيلها عندما يقوم المستخدم بتثبيت أو تحديث أو تكوين مثيل لامتدادك. راجع التعامل مع أحداث دورة حياة ملحقك .
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 خيط (مطلوب) | وصف الحدث. |