Dokumentacja rozszerzeniaextension.yaml

Plik specyfikacji rozszerzenia (extension.yaml) zawiera metadane rozszerzenia, deklaruje zasoby utworzone przez rozszerzenie, interfejsy API i dostęp wymagane przez rozszerzenie oraz definiuje wszelkie parametry skonfigurowane przez użytkownika udostępniane przez rozszerzenie.

W tabelach na tej stronie opisujemy pola dostępne w przypadku pliku extension.yaml.

Podstawowe informacje umożliwiające identyfikację

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/

Interfejsy API Firebase i Google Cloud

Te pola określają interfejsy API Firebase i Google używane przez rozszerzenie. Gdy użytkownicy instalują to rozszerzenie, mogą automatycznie włączać te interfejsy API w swoim projekcie.

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

Role uprawnień

Te pola określają role Cloud IAM wymagane przez rozszerzenie. Te role zostaną przypisane kontu usługi udostępnionemu rozszerzeniu.

Możesz określić tylko jedną z obsługiwanych ról.

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

Usługi zewnętrzne

Te pola określają usługi spoza Firebase i Google, z których korzysta rozszerzenie (zwykle są to interfejsy API typu REST). Platforma Rozszerzenia w Firebase nie umożliwia automatycznego włączania tych usług ani przeprowadzania autoryzacji.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing

Parametry konfigurowane przez użytkownika

Pola te określają parametry, które rozszerzenie udostępnia użytkownikom do skonfigurowania.

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

Parametry, które można wybrać i w sposób umożliwiający ich wybór

Parametry do wyboru lub do wyboru informują użytkownika o wyborze z listy wstępnie zdefiniowanych opcji.

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

Parametry zasobu do wyboru

Parametry zasobu do wyboru wyświetlają użytkownikom prośbę o wybranie zasobu (instancji bazy danych, zasobnika na dane itp.) z projektu.

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

Parametry obiektu tajnego

Wartości obiektów tajnych podanych przez użytkownika (na przykład kluczy interfejsu API) są obsługiwane w inny sposób:

• Wartości obiektów tajnych są przechowywane przy użyciu usługi Cloud Secret Manager. Dostęp do tych wartości mają tylko autoryzowane klienty (takie jak zainstalowane wystąpienie rozszerzenia).
• Gdy użytkownicy są proszeni o ich podanie, dane wejściowe nie są wyświetlane.

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

Zasoby w Cloud Functions

Te pola deklarują funkcje w Cloud Functions dostępne w rozszerzeniu. Składnia deklaracji zasobów wygląda nieco inaczej w przypadku funkcji 1 generacji i 2 generacji, które mogą współistnieć w rozszerzeniu.

Funkcje w Cloud Functions pierwszej generacji

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

Funkcje w Cloud Functions drugiej generacji

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

Zdarzenia cyklu życia

Zdarzenia cyklu życia pozwalają określić funkcje, które będą uruchamiane, gdy użytkownik zainstaluje, zaktualizuje lub skonfiguruje instancję rozszerzenia. Zapoznaj się z sekcją Obsługa zdarzeń cyklu życia rozszerzenia.

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

Zdarzenia niestandardowe (Eventarc)

Zdarzenia niestandardowe to zdarzenia wysyłane przez rozszerzenie, które umożliwiają użytkownikom wstawianie do niego własnych reguł logicznych. Zapoznaj się z sekcją Eventarc w artykule Dodawanie do rozszerzenia elementów łączących użytkowników.

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