يحتوي ملف مواصفات الإضافة (extension.yaml
) على metadata الإضافة، ويوضّح الموارد التي أنشأتها الإضافة وواجهات برمجة التطبيقات وعمليات الوصول التي تتطلّبها الإضافة، ويحدّد أي مَعلمات يضبطها المستخدم ويقدّمها الإضافة.
توضّح الجداول في هذه الصفحة الحقول المتاحة لملف 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 string (مطلوب) |
معرّف الإضافة لا يمكن أن يحتوي إلا على أحرف صغيرة وأرقام وشُرط، ويجب ألا يزيد عن 40 حرفًا. ملاحظة: تُستخدَم هذه القيمة لإنشاء رقم تعريف مثيل الإضافة (الذي يُستخدَم بعد ذلك لإنشاء أسماء حساب الخدمة الخاص بالإضافة والموارد الخاصة بالإضافة). |
||||||||
version string (مطلوب) |
إصدار الإضافة يجب أن يتّبع نظام ترقيم الإصدارات semver (مثلاً، 1.2.0). |
||||||||
specVersion string (مطلوب) |
إصدار مواصفات إضافات Firebase القيمة الحالية: |
||||||||
license سلسلة (اختيارية) |
ترخيص الإضافة يجب أن تكون الإضافة مرخّصة باستخدام |
||||||||
billingRequired منطقي (اختياري) |
ما إذا كانت الخدمات التي تستخدمها الإضافة تتطلّب حساب فوترة في Firebase لإصدار مدفوع يتم ضبطه دائمًا على |
||||||||
displayName string (اختياري) |
اسم معروض سهل للإضافة (من 3 إلى 5 كلمات). عدد الأحرف المسموح به هو 40. |
||||||||
description string (اختياري) |
وصف موجز للمهمة التي تؤديها الإضافة (جملة واحدة تقريبًا) | ||||||||
icon string (اختياري) |
الملف الذي تريد استخدامه كرمز للإضافة على يجب أن يكون هذا الملف بتنسيق PNG مربعًا بحجم يتراوح بين 512×512 و1024×1024 بكسل.
ضَع الملف في الدليل نفسه الذي يتضمّن يُرجى مراعاة الإرشادات التالية عند تصميم رمز لإضافة Chrome:
|
||||||||
tags قائمة السلاسل (اختيارية) |
علامات لمساعدة المستخدمين في العثور على إضافتك
تتمّ ربط العلامات التالية بالفئات في "مركز الإضافات":
marketing ،
messaging ،
payments ،
search ،
shipping ،
social ،
utilities ،
ai
|
||||||||
sourceUrl سلسلة (اختيارية) |
عنوان URL العام الذي يمكن الوصول من خلاله إلى دليل الإضافات. | ||||||||
releaseNotesUrl string (اختياري) |
عنوان 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 يجب أن يتوافق مع حقل اسم الخدمة كما هو موضّح في صفحة النظرة العامة لكل واجهة برمجة تطبيقات (مثال) في مكتبة Google Cloud API |
reason string (مطلوب) |
وصف موجز لسبب حاجة الإضافة إلى استخدام واجهة برمجة التطبيقات هذه |
أدوار إدارة الهوية وإمكانية الوصول
تحدِّد هذه الحقول أدوار 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 string (مطلوب) |
وصف موجز لسبب احتياج الإضافة إلى إذن الوصول الممنوح من هذا الدور |
resource string (اختياري) |
يمكنك حصر نطاق الدور بهذا المورد. وإذا تم حذفها، يتم ضبطها تلقائيًا على " |
الخدمات الخارجية
تحدِّد هذه الحقول الخدمات غير التابعة لشركة Firebase وGoogle التي تستخدمها الإضافة (عادةً واجهات برمجة تطبيقات REST). لا توفّر منصة Firebase Extensions أي وسيلة لتفعيل هذه الخدمات أو تنفيذ التفويض لها تلقائيًا.
externalServices:
- name: Example API
pricingUri: https://developers.example.com/pricing
- name: Another Example API
pricingUri: https://developers.example.com/pricing
حقول الخدمات الخارجية | |
---|---|
name string (مطلوب) |
اسم الخدمة الخارجية اللازمة لتشغيل الإضافة |
pricingUri string (مطلوب) |
معرّف الموارد المنتظم (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 string (مطلوب) |
وصف موجز للمَعلمة يتم عرضها للمستخدم عندما يتم طلب قيمة المَعلمة منه. |
description string (اختياري) |
وصف تفصيلي للمَعلمة يتم عرضها للمستخدم عندما يُطلب منه إدخال قيمة المَعلمة. تتوافق مع Markdown. |
example سلسلة (اختيارية) |
مثال على قيمة للمَعلمة |
default سلسلة (اختيارية) |
القيمة التلقائية للمَعلمة إذا ترك المستخدم قيمة المَعلمة فارغة |
validationRegex string (اختياري) |
تعبير عادي للتحقّق من صحة قيمة المَعلمة التي ضبطها المستخدِم بنية Google RE2: |
validationErrorMessage string (اختياري) |
رسالة الخطأ التي يتم عرضها في حال تعذّر التحقّق من التعبير العادي |
required منطقي (اختياري) |
يحدّد ما إذا كان بإمكان المستخدم إرسال سلسلة فارغة عند طلب
قيمة المَعلمة منه. الإعداد التلقائي هو true .
|
immutable منطقي (اختياري) |
تحدِّد هذه السياسة ما إذا كان يمكن للمستخدم تغيير قيمة المَعلمة بعد
التثبيت (على سبيل المثال، في حال إعادة ضبط الإضافة). الإعداد التلقائي هو
ملاحظة: في حال تحديد مَعلمة "الموقع الجغرافي" للدوالّ
التي تم نشرها في الإضافة، اضبط هذا الحقل على |
type string (اختياري) |
نوع المَعلمة قد يكون لأنواع المَعلمات الخاصة متطلبات إضافية أو عرض مختلف لواجهة المستخدم. راجِع الأقسام التالية. |
المَعلمات القابلة للاختيار والمَعلمات القابلة للاختيار من بين عدّة مَعلمات
تطلب المَعلمات القابلة للاختيار والمَعلمات القابلة للاختيار المتعدّد من المستخدِمين الاختيار من قائمة الخيارات المحدّدة مسبقًا.
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 string (مطلوب) |
نوع المورد الذي يجب أن يختار المستخدمه قيم صالحة:
ومع ذلك، لا تتوفّر حاليًا واجهة مستخدم للاختيار إلا في حِزم Cloud Storage (يتم عرض أنواع الموارد الأخرى كحقول إدخال نص بتنسيق حر). |
المَعلمات السرية
يتم التعامل مع القيم السرية المقدَّمة من المستخدِم (مثل مفاتيح واجهة برمجة التطبيقات) بشكلٍ مختلف:
- يتم تخزين القيم السرية باستخدام أداة "إدارة الأسرار في السحابة الإلكترونية". لا يمكن الوصول إلى هذه القيم إلا من خلال العملاء المعتمَدين (مثل نسخة مثبَّتة من إضافة).
- وعندما يُطلب من المستخدمين تقديم هذه القيم، لا يتم عرض بياناتهم.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
حقول المَعلمات السرية | |
---|---|
type سلسلة |
لتحديد أن المعلمة هي قيمة سرية |
موارد وظائف السحابة الإلكترونية
تُعرِض هذه الحقول وظائف Cloud Functions المضمّنة في إضافة. تختلف بنية ملف تعريف الموارد قليلاً بين الدوالّ من الجيل الأول والجيل الثاني، والتي يمكن أن تتعايش في إضافة.
وظائف Cloud من الجيل الأول
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 string (مطلوب) |
اسم سهل الاستخدام للدالة التي تم تصديرها في حال عدم تحديد سمة سيكون الاسم النهائي للدالة المُنشرة بالتنسيق التالي:
|
||||||||||||||||
type string (مطلوب) |
لمورد دالة من الجيل الأول:
firebaseextensions.v1beta.function
|
||||||||||||||||
description سلسلة (مطلوبة) |
وصف موجز للمهمة التي تؤديها الدالة لإضافة |
||||||||||||||||
properties (مطلوب) |
مواقع Cloud Functions من الجيل الأول في ما يلي أهم السمات ، ولكن يمكنك العثور على القائمة الكاملة في مرجع الدوالّ في السحابة الإلكترونية.
|
وظائف السحابة الإلكترونية من الجيل الثاني
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 string (مطلوب) |
اسم سهل الاستخدام للدالة التي تم تصديرها في حال عدم تحديد سمة سيكون الاسم النهائي للدالة المُنشرة بالتنسيق التالي:
|
||||||||||||||||||||||||||||
type string (مطلوب) |
للحصول على مرجع للدوالّ من الجيل الثاني:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description string (مطلوب) |
وصف موجز للمهمة التي تؤديها الدالة لإضافة |
||||||||||||||||||||||||||||
properties (مطلوب) |
مواقع الجيل الثاني من 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
حقول الأحداث المخصّصة | |
---|---|
type string (مطلوب) |
معرّف نوع الحدث. يجب إنشاء المعرّف من 3 إلى 4 حقول مُحدَّدة بنقاط: يجب ملء حقول معرّف الناشر واسم الإضافة واسم الحدث ، ويُنصح بملء حقل الإصدار. اختَر اسمًا فريدة ووصفيًا للحدث لكل نوع حدث تنشره. |
description string (مطلوب) |
تمثّل هذه السمة وصف الفعالية. |