يحتوي ملف مواصفات إضافتك (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 قائمة السلاسل (اختيارية) |
علامات لمساعدة المستخدمين على اكتشاف إضافتك
ترتبط العلامات التالية بالفئات في "مركز الإضافات":
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 التي تستخدمها الإضافة. عندما يثبّت المستخدمون الإضافة، يمكنهم اختيار تمكين واجهات برمجة التطبيقات هذه تلقائيًا في مشروعاتهم.
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 يجب أن يتوافق مع حقل اسم الخدمة كما هو موضّح في صفحة النظرة العامة لكل واجهة برمجة تطبيقات (مثال) في مكتبة Google Cloud API |
reason سلسلة (مطلوبة) |
وصف موجز يوضِّح سبب احتياج الإضافة إلى استخدام واجهة برمجة التطبيقات هذه |
أدوار "إدارة الهوية وإمكانية الوصول"
تحدّد هذه الحقول أدوار 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 سلسلة (مطلوبة) |
اسم دور "إدارة الهوية وإمكانية الوصول" المطلوب لتشغيل الإضافة يجب أن يكون أحد الأدوار المتوافقة. |
reason سلسلة (مطلوبة) |
وصف موجز لسبب احتياج الإضافة إلى إذن الوصول الممنوح من هذا الدور |
resource سلسلة (اختيارية) |
حصر نطاق الدور على هذا المورد. وإذا تم حذفها، يتم ضبطها تلقائيًا على " |
الخدمات الخارجية
تحدّد هذه الحقول الخدمات غير التابعة لـ Firebase والخدمات غير التابعة لـ Google التي تستخدمها الإضافة (عادةً واجهات برمجة تطبيقات REST). لا يوفر نظام إضافات Firebase أي وسيلة لتفعيل التفويض أو تنفيذه تلقائيًا لهذه الخدمات.
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 سلسلة (اختيارية) |
وصف تفصيلي للمَعلمة يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة. يتيح استخدام Markdown. |
example سلسلة (اختيارية) |
مثال على قيمة المَعلمة |
default سلسلة (اختيارية) |
القيمة التلقائية للمَعلمة إذا ترك المستخدم قيمة المَعلمة فارغة |
validationRegex سلسلة (اختيارية) |
تمثّل هذه السمة تعبيرًا عاديًا للتحقّق من صحة القيمة التي ضبطها المستخدم للمعلَمة. بنية Google RE2: |
validationErrorMessage سلسلة (اختيارية) |
رسالة خطأ تظهر في حال تعذُّر التحقّق من صحة التعبير العادي. |
required المنطقي (اختياري) |
تحدِّد هذه السياسة ما إذا كان يمكن للمستخدم إرسال سلسلة فارغة عندما يُطلب منه إدخال قيمة المَعلمة. وتكون القيمة التلقائية هي true .
|
immutable المنطقي (اختياري) |
تحدِّد هذه السياسة ما إذا كان بإمكان المستخدم تغيير قيمة المَعلمة بعد
التثبيت (على سبيل المثال، في حال إعادة ضبط الإضافة). وتكون القيم التلقائية
ملاحظة: إذا حدّدت مَعلمة "location" للدوال المنشورة
في إضافتك، اضبط هذا الحقل على |
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 Storage حاليًا فقط واجهة مستخدم للخيارات (يتم عرض أنواع الموارد الأخرى كحقول إدخال نص ذات تصميم مرن). |
المعلمات السرية
يتم التعامل مع القيم السرية التي يقدّمها المستخدم (مثل مفاتيح واجهة برمجة التطبيقات) بشكل مختلف:
- يتم تخزين القيم السرية باستخدام Cloud Secret Manager. ويمكن للعملاء المصرح لهم فقط (مثل نسخة مثبَّتة لإحدى الإضافات) الوصول إلى هذه القيم.
- عندما يُطلب من المستخدمين تقديم هذه القيم، لا يتم عرض البيانات التي أدخلوها.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
حقول المَعلمات السرية | |
---|---|
سلسلة
type |
لتحديد أن المعلمة هي قيمة سرية |
موارد Cloud Function
توضّح هذه الحقول دوال السحابة الإلكترونية المضمَّنة في إحدى الإضافات. تبدو بنية تعريف الموارد مختلفة قليلاً بين دالتي الجيل الأول والجيل الثاني، والتي يمكن أن تتضمّن امتدادًا.
وظائف السحابة الإلكترونية من الجيل الأول
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 سلسلة (مطلوبة) |
اسم سهل الاستخدام للدالة التي تم تصديرها. إذا لم تحدّد السمة سيكون الاسم النهائي للدالة deployed بالتنسيق التالي:
|
||||||||||||||||
type سلسلة (مطلوبة) |
بالنسبة إلى مورد الدالة من الجيل الأول:
firebaseextensions.v1beta.function
|
||||||||||||||||
description سلسلة (مطلوبة) |
تمثّل هذه السمة وصفًا موجزًا للمهمة التي تؤديها الدالة مع الإضافة. |
||||||||||||||||
properties (مطلوب) |
مواقع الجيل الأول من Cloud Functions تم إدراج أهم السمات أدناه، ولكن يمكنك العثور على القائمة الكاملة في مرجع دوال Cloud.
|
وظائف السحابة الإلكترونية من الجيل الثاني
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 سلسلة (مطلوبة) |
اسم سهل الاستخدام للدالة التي تم تصديرها. إذا لم تحدّد السمة سيكون الاسم النهائي للدالة deployed بالتنسيق التالي:
|
||||||||||||||||||||||||||||
type سلسلة (مطلوبة) |
بالنسبة إلى مرجع الدالة من الجيل الثاني:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description سلسلة (مطلوبة) |
تمثّل هذه السمة وصفًا موجزًا للمهمة التي تؤديها الدالة مع الإضافة. |
||||||||||||||||||||||||||||
properties (مطلوب) |
مواقع الجيل الثاني من Cloud Functions تم إدراج أهم السمات أدناه، ولكن يمكنك العثور على القائمة الكاملة في مرجع دوال Cloud.
هناك أيضًا ثلاثة حقول من نوع الكائن لها خصائصها الخاصة:
|
أحداث مراحل النشاط
تتيح لك أحداث مراحل النشاط تحديد الوظائف التي سيتم تشغيلها عندما يثبّت أحد المستخدمين مثيلاً لإضافتك أو يعدِّله أو يضبطه. راجِع التعامل مع أحداث مراحل نشاط الإضافة.
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 سلسلة (مطلوبة) |
تمثّل هذه السمة وصف الفعالية. |