مرجع الإضافة.yaml

يحتوي ملف مواصفات الإضافة (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/

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/

واجهات برمجة التطبيقات 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

أدوار إدارة الهوية وإمكانية الوصول

تحدِّد هذه الحقول أدوار 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

الخدمات الخارجية

تحدِّد هذه الحقول الخدمات غير التابعة لشركة 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

المَعلمات التي يمكن للمستخدم ضبطها

تحدِّد هذه الحقول المَعلمات التي تتيحها الإضافة للمستخدمين لضبطها.

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

المَعلمات القابلة للاختيار والمَعلمات القابلة للاختيار من بين عدّة مَعلمات

تطلب المَعلمات القابلة للاختيار والمَعلمات القابلة للاختيار المتعدّدة من المستخدِمين الاختيار من قائمة الخيارات المحدّدة مسبقًا.

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

مَعلمات الموارد القابلة للاختيار

تطلب مَعلمات الموارد القابلة للاختيار من المستخدمين اختيار مورد (مثيل قاعدة بيانات أو حزمة تخزين أو غير ذلك) من مشروعهم.

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

المَعلمات السرية

يتم التعامل مع القيم السرية المقدَّمة من المستخدِم (مثل مفاتيح واجهة برمجة التطبيقات) بشكلٍ مختلف:

• يتم تخزين القيم السرية باستخدام أداة "إدارة الأسرار في السحابة الإلكترونية". لا يمكن الوصول إلى هذه القيم إلا من خلال العملاء المعتمَدين (مثل نسخة مثبَّتة من إضافة).
• وعندما يُطلب من المستخدمين تقديم هذه القيم، لا يتم عرض بياناتهم.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret

موارد وظائف السحابة الإلكترونية

تُعرِض هذه الحقول وظائف 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

وظائف 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

أحداث مراحل النشاط

تتيح لك أحداث دورة الحياة تحديد الدوالّ التي سيتم تنفيذها عندما يُثبِّت المستخدم مثيلًا من الإضافة أو يحدّثه أو يعدّله. اطّلِع على معالجة أحداث دورة حياة الإضافة.

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

الأحداث المخصّصة (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