يحتوي ملف مواصفات الإضافة (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/
| الحقول الأساسية | |||||||||
|---|---|---|---|---|---|---|---|---|---|
namestring (مطلوب) |
معرّف الإضافة يمكن أن يحتوي على أحرف صغيرة وأرقام وواصلات فقط، وبحدّ أقصى 40 حرفًا. ملاحظة: تُستخدَم هذه القيمة لإنشاء رقم تعريف مثيل الإضافة (الذي يُستخدَم بعد ذلك لإنشاء أسماء حساب خدمة الإضافة والموارد الخاصة بالإضافة). |
||||||||
versionstring (مطلوب) |
إصدار الإضافة يجب أن يتّبع الإصدار نظام semver (على سبيل المثال، 1.2.0). |
||||||||
specVersionstring (مطلوب) |
إصدار مواصفات إضافات Firebase القيمة الحالية: |
||||||||
licensestring (اختياري) |
ترخيص الإضافة يجب ترخيص الإضافة باستخدام |
||||||||
billingRequiredboolean (اختياري) |
ما إذا كانت الخدمات التي تستخدمها الإضافة تتطلّب حساب فوترة Firebase من فئة مدفوعة يتم ضبطها دائمًا على |
||||||||
displayNamestring (اختياري) |
الاسم المعروض للإضافة (من 3 إلى 5 كلمات) الحد الأقصى المسموح به هو 40 حرفًا. |
||||||||
descriptionstring (اختياري) |
وصف موجز للمهمة التي تؤديها الإضافة (جملة واحدة تقريبًا) | ||||||||
iconstring (اختياري) |
الملف الذي سيتم استخدامه كرمز للإضافة على
يجب أن يكون هذا الملف بتنسيق PNG مربّع الشكل وبدقة تتراوح بين 512×512 و1024×1024 بكسل.
ضع الملف في الدليل نفسه الذي يتضمّن يُرجى مراعاة الإرشادات التالية عند تصميم رمز لإضافتك:
|
||||||||
tagsقائمة سلاسل (اختيارية) |
علامات لمساعدة المستخدمين في العثور على الإضافة
تتوافق العلامات التالية مع الفئات في Extensions Hub:
marketing،
messaging،
payments،
search،
shipping،
social،
utilities،
ai
|
||||||||
sourceUrlstring (اختياري) |
عنوان URL متاح للجميع يمكن من خلاله الوصول إلى دليل الإضافة | ||||||||
releaseNotesUrlstring (اختياري) |
عنوان 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
تحدّد هذه الحقول واجهات برمجة التطبيقات في 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
| حقول واجهة برمجة التطبيقات | |
|---|---|
apiNamestring (مطلوب) |
اسم Google API يجب أن يتطابق مع حقل اسم الخدمة كما هو مُدرَج في صفحة النظرة العامة لكل واجهة برمجة تطبيقات (مثال) في مكتبة Google Cloud API |
reasonstring (مطلوب) |
وصف موجز لسبب حاجة الإضافة إلى استخدام واجهة برمجة التطبيقات هذه |
أدوار "إدارة الهوية وإمكانية الوصول"
تحدّد هذه الحقول أدوار 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
| حقول الأدوار | |
|---|---|
rolestring (مطلوب) |
اسم دور "إدارة الهوية وإمكانية الوصول" اللازم لتشغيل الإضافة يجب أن يكون أحد الأدوار المتوافقة |
reasonstring (مطلوب) |
وصف موجز لسبب حاجة الإضافة إلى الوصول الممنوح من خلال هذا الدور |
resourcestring (اختياري) |
يمكنك حصر نطاق الدور في هذا المورد. في حال عدم إدخال قيمة، يتم استخدام |
الخدمات الخارجية
تحدّد هذه الحقول الخدمات غير التابعة لـ Firebase وغير التابعة لـ Google التي تستخدمها الإضافة (عادةً واجهات برمجة تطبيقات REST). لا توفّر منصة "إضافات Firebase" أي وسيلة لتفعيل هذه الخدمات أو إجراء التفويض لها تلقائيًا.
externalServices:
- name: Example API
pricingUri: https://developers.example.com/pricing
- name: Another Example API
pricingUri: https://developers.example.com/pricing
| حقول الخدمات الخارجية | |
|---|---|
namestring (مطلوب) |
اسم الخدمة الخارجية اللازمة لتشغيل الإضافة |
pricingUristring (مطلوب) |
معرّف الموارد المنتظم (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
| حقول المَعلمات | |
|---|---|
paramstring (مطلوب) |
اسم المَعلمة يمكنك استخدام هذا الاسم للإشارة إلى قيمة المَعلمة في الرمز البرمجي. |
labelstring (مطلوب) |
وصف موجز للمَعلمة يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة. |
descriptionstring (اختياري) |
وصف تفصيلي للمَعلمة يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة. يتيح استخدام Markdown. |
examplestring (اختياري) |
مثال على قيمة المَعلمة |
defaultstring (اختياري) |
القيمة التلقائية للمَعلمة إذا ترك المستخدم قيمة المَعلمة فارغة. |
validationRegexstring (اختياري) |
تعبير عادي للتحقّق من صحة القيمة التي ضبطها المستخدم للمَعلمة بنية التعبير العادي حسب مواصفات Google RE2 |
validationErrorMessagestring (اختياري) |
رسالة الخطأ التي تظهر في حال تعذّر التحقّق من التعبير النمطي |
requiredboolean (اختياري) |
تحدّد ما إذا كان بإمكان المستخدم إرسال سلسلة فارغة عندما يُطلب منه إدخال قيمة المَعلمة. القيمة التلقائية هي true.
|
immutableboolean (اختياري) |
تحدّد ما إذا كان بإمكان المستخدم تغيير قيمة المَعلمة بعد
التثبيت (مثلاً، في حال إعادة ضبط الإضافة). القيمة التلقائية هي
ملاحظة: إذا حدّدت مَعلمة "location" للدوال المنشورة في الإضافة، اضبط هذا الحقل على |
typestring (اختياري) |
نوع المَعلمة قد تتطلّب أنواع المَعلمات الخاصة متطلبات إضافية أو عرضًا مختلفًا لواجهة المستخدم. يُرجى الاطّلاع على الأقسام التالية. |
المَعلمات القابلة للاختيار والمتعدّدة الاختيار
تطلب المَعلمات القابلة للاختيار والمتعدّدة الاختيار من المستخدمين الاختيار من قائمة الخيارات المحدّدة مسبقًا.
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
| حقول المَعلمات ذات الخيارات المتعدّدة | |||||||
|---|---|---|---|---|---|---|---|
typestring |
تحدّد هذه السمة أنّ المَعلمة يمكن أن تكون قيمة واحدة ( |
||||||
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
| حقول معلّمات المرجع | |
|---|---|
typestring |
تحدّد أنّ المَعلمة تمثّل مورد مشروع |
resourceTypestring (مطلوب) |
نوع المرجع الذي سيُطلب من المستخدم اختياره قيم صالحة:
ومع ذلك، تتوفّر حاليًا واجهة مستخدم للاختيار في حِزم Cloud Storage فقط (يتم عرض أنواع الموارد الأخرى كحقول إدخال نصية بتصميم مرن). |
المَعلمات السرية
يتم التعامل مع القيم السرية التي يقدّمها المستخدم (مثل مفاتيح واجهة برمجة التطبيقات) بشكل مختلف:
- يتم تخزين قيم المفاتيح السرية باستخدام Cloud Secret Manager. يمكن فقط للعملاء المصرّح لهم (مثل نسخة مثبّتة من إضافة) الوصول إلى هذه القيم.
- عندما يُطلب من المستخدمين تقديم هذه القيم، لا يتم عرض ما أدخلوه.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
| حقول المَعلمات السرية | |
|---|---|
typestring |
تحدّد أنّ المَعلمة هي قيمة سرية |
موارد Cloud Function
تُعرِّف هذه الحقول دوال Cloud Functions المضمّنة في الإضافة. تختلف بنية تعريف الموارد قليلاً بين دوال الجيل الأول والجيل الثاني، والتي يمكن أن تتواجد معًا في إضافة.
الجيل الأول من Cloud Functions
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
| حقول الموارد | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namestring (مطلوب) |
اسم سهل الاستخدام للدالة التي تم تصديرها إذا لم تحدّد السمة سيكون الاسم النهائي للدالة المنشورة بالتنسيق التالي:
|
||||||||||||||||
typestring (مطلوب) |
بالنسبة إلى مرجع دالة من الجيل الأول:
firebaseextensions.v1beta.function
|
||||||||||||||||
descriptionstring (مطلوب) |
وصف موجز للمهمة التي تؤديها الدالة للإضافة |
||||||||||||||||
properties(مطلوب) |
سمات الجيل الأول من Cloud Functions في ما يلي أهم السمات، ولكن يمكنك العثور على القائمة الكاملة في مرجع 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
| حقول الموارد | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namestring (مطلوب) |
اسم سهل الاستخدام للدالة التي تم تصديرها إذا لم تحدّد السمة سيكون الاسم النهائي للدالة المنشورة بالتنسيق التالي:
|
||||||||||||||||||||||||||||
typestring (مطلوب) |
بالنسبة إلى مورد دالة من الجيل الثاني:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
descriptionstring (مطلوب) |
وصف موجز للمهمة التي تؤديها الدالة للإضافة |
||||||||||||||||||||||||||||
properties(مطلوب) |
خصائص الجيل الثاني من Cloud Functions في ما يلي أهم السمات، ولكن يمكنك العثور على القائمة الكاملة في مرجع 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 في إضافة عناصر جذب المستخدمين إلى إضافة.
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
| حقول الأحداث المخصّصة | |
|---|---|
typestring (مطلوب) |
معرّف نوع الحدث أنشئ المعرّف من 3 إلى 4 حقول مفصولة بنقاط: حقول الرقم التعريفي للناشر واسم الإضافة واسم الحدث مطلوبة، ويُنصح باستخدام حقل الإصدار. اختَر اسم حدث فريدًا ووصفًا لكل نوع حدث تنشره. |
descriptionstring (مطلوب) |
وصف الحدث |