extensions.yaml referansı

Uzantınızın spesifikasyon dosyası (extension.yaml) uzantınızın meta verilerini içerir, uzantı tarafından oluşturulan kaynakları ve uzantının gerektirdiği API'leri ve erişimi tanımlar, ayrıca uzantının sağladığı, kullanıcı tarafından yapılandırılmış tüm parametreleri tanımlar.

Bu sayfadaki tablolarda, bir extension.yaml dosyası için kullanılabilen alanlar açıklanmaktadır.

Temel ve tanımlayıcı bilgiler

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/
Temel alanlar
name
dize
(zorunlu)

Uzantının tanımlayıcısı.

Yalnızca küçük harf, sayı ve tire içerebilir. 40 karakterle sınırlıdır.

Not: Bu değer, uzantının örnek kimliğini oluşturmak için kullanılır (daha sonra, uzantının hizmet hesabının ve uzantıya özel kaynakların adlarını oluşturmak için kullanılır).

version
dize
(zorunlu)

Uzantının sürümü.

Semver sürümü kullanılmalıdır (örneğin, 1.2.0).

specVersion
dize
(zorunlu)

Firebase Extensions spesifikasyonunun sürümü.

Geçerli değer: v1beta

license
dize
(isteğe bağlı)

Uzantının lisansı.

Uzantınız Apache-2.0 kullanılarak lisanslanmalıdır.

billingRequired
boole
(isteğe bağlı)

Uzantının kullandığı hizmetlerin ücretli katmanda Firebase faturalandırma hesabı gerektirip gerektirmediği.

Her zaman true seçeneğine ayarla.

displayName
dize
(isteğe bağlı)

Uzantının kolayca görünen adı (3-5 kelime).

40 karakterle sınırlıdır.

description
dize
(isteğe bağlı)
Uzantınızın gerçekleştirdiği görevin kısa açıklaması (~1 cümle).
icon
dize
(isteğe bağlı)

extensions.dev ve Firebase konsolunda uzantı simgesi olarak kullanılacak dosya.

Bu dosya, 512x512 ila 1024x1024 piksel arasında kare bir PNG dosyası olmalıdır. Dosyayı extension.yaml ile aynı dizine yerleştirin. Alt dizin belirtemezsiniz.

Uzantınız için simge tasarlarken aşağıdaki yönergeleri göz önünde bulundurun:

  • Markanıza uygun arka plan ve poster renklerini seçin.
  • Yalnızca 2 renk kullanarak simge renklerinizi basit tutun. Birden fazla renk, simgenizi görsel olarak boğuklaştırabilir.
  • Aynı nedenle, simgenizde gradyan kullanmayın. Renk geçişleri, küçük boyutlarda kolayca ayırt edilebilir ve simgeyi görsel olarak karmaşık hale getirir.
  • Uzantınızın işlevini yansıtan basit ve benzersiz görüntüler kullanın.
  • Şirketiniz birden fazla uzantı oluşturuyorsa simge olarak logonuzu kullanmayın. Kullanıcılar uzantılarınızı birbirinden ayırt etmekte zorluk yaşar.
  • Posterin görsel ve kalın olmasına dikkat edin. Daha küçük boyutlarda iyi gösterilemeyecek kadar ince veya ayrıntılı görseller kullanmayın.
  • Uzantınızın işlevini açıklayan kelimeler eklemeyin. Metinler, daha küçük boyutlarda genellikle okunamaz.
tags
dize listesi
(isteğe bağlı)
Kullanıcıların uzantınızı keşfetmesine yardımcı olan etiketler. Şu etiketler Extensions Hub'daki kategorilerle eşlenir: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
dize
(isteğe bağlı)
Uzantı dizinine erişilebileceği herkese açık URL.
releaseNotesUrl
dize
(isteğe bağlı)
Uzantının sürüm notlarına erişilebileceği herkese açık URL.
author
bir yazar nesnesi
(isteğe bağlı)

Uzantının asıl yazarı ve ilgili kişisi.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Yazar alanları
authorName
dize
(zorunlu)

Yazarın adı.

Bir kişi, şirket, kuruluş vb. olabilir.

email
dize
(isteğe bağlı)
Yazarın e-posta adresi.
url
dize
(isteğe bağlı)
Yazar hakkındaki bilgilere erişilebildiği herkese açık URL.
contributors
yazar nesneleri listesi
(isteğe bağlı)

Uzantıya katkıda bulunan diğer yazarlar.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Yazar alanları
authorName
dize
(zorunlu)

Yazarın adı.

Bir kişi, şirket, kuruluş vb. olabilir.

email
dize
(isteğe bağlı)
Yazarın e-posta adresi.
url
dize
(isteğe bağlı)
Yazar hakkındaki bilgilere erişilebildiği herkese açık URL.

Firebase ve Google Cloud API'leri

Bu alanlar, uzantının kullandığı Firebase ve Google API'lerini belirtir. Kullanıcılar uzantıyı yüklerken bu API'leri projelerinde otomatik olarak etkinleştirmeyi seçebilir.

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
API alanları
apiName
dize
(zorunlu)

Google API'nin adı

Google Cloud API Kitaplığı'ndaki her API'nin genel bakış sayfasında (örnek) listelenen Hizmet adı alanına karşılık gelmelidir

reason
dize
(zorunlu)
Uzantının neden bu API'yi kullanması gerektiğine dair kısa açıklama

IAM rolleri

Bu alanlar, uzantının gerektirdiği Cloud IAM rollerini belirtir. Uzantı için sağlanan hizmet hesabına bu roller verilir.

Desteklenen rollerden yalnızca birini belirtebilirsiniz.

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
Rol alanları
role
dize
(zorunlu)

Uzantının çalışması için gereken IAM rolünün adı

Desteklenen rollerden biri olmalıdır

reason
dize
(zorunlu)
Uzantının neden bu rolün verdiği erişime ihtiyacı olduğuna dair kısa açıklama
resource
dize
(isteğe bağlı)

Rolün kapsamını bu kaynakla sınırlandırın.

Atlanırsa varsayılan olarak projects/${project_id} değerine ayarlanır. Rollerin kapsamını azaltma bölümünü inceleyin.

Harici hizmetler

Bu alanlar, uzantının kullandığı Firebase ve Google dışı hizmetleri (genellikle REST API'ler) belirtir. Firebase Extensions platformu, bu hizmetler için yetkilendirmeyi otomatik olarak etkinleştirmek veya gerçekleştirmek için herhangi bir yöntem sağlamaz.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Harici hizmet alanları
name
dize
(zorunlu)
Uzantının çalışması için gereken harici hizmetin adı
pricingUri
dize
(zorunlu)
Hizmete ilişkin fiyatlandırma bilgilerinin URI'si

Kullanıcı tarafından yapılandırılabilen parametreler

Bu alanlar, uzantının kullanıcılar tarafından yapılandırılması için sağladığı parametreleri tanımlar.

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
Parametre alanları
param
dize
(zorunlu)
Parametrenin adı. Bu adı, koddaki parametre değerine referans vermek için kullanırsınız.
label
dize
(zorunlu)
Parametrenin kısa açıklaması. Parametrenin değeri istendiğinde kullanıcıya gösterilir.
description
dize
(isteğe bağlı)

Parametrenin ayrıntılı açıklaması. Parametrenin değeri istendiğinde kullanıcıya gösterilir.

Markdown'ı destekler.

example
dize
(isteğe bağlı)
Parametre için örnek değer.
default
dize
(isteğe bağlı)
Kullanıcı, parametre değerini boş bırakırsa parametrenin varsayılan değeri.
validationRegex
dize
(isteğe bağlı)
Parametrenin kullanıcı tarafından yapılandırılan değerinin doğrulanması için kullanılan normal ifade. Google RE2 söz dizimi.
validationErrorMessage
dize
(isteğe bağlı)
Normal ifade doğrulaması başarısız olursa görüntülenecek hata mesajı.
required
boole
(isteğe bağlı)
Kullanıcının parametre değeri istendiğinde boş bir dize gönderip gönderemeyeceğini tanımlar. Varsayılan olarak true değerine ayarlanır.
immutable
boole
(isteğe bağlı)

Kullanıcının yükleme sonrasında parametre değerini değiştirip değiştiremeyeceğini (ör. uzantıyı yeniden yapılandırıp yapılandıramayacağını) tanımlar. Varsayılan olarak false değerine ayarlanır.

Not: Uzantınızın dağıtılan işlevleri için bir "location" parametresi tanımlarsanız bu alanı true olarak ayarlayın.

type
dize
(isteğe bağlı)
Parametre türü. Özel parametre türlerinin ek şartları veya farklı kullanıcı arayüzü sunumları olabilir. Aşağıdaki bölümleri inceleyin.

Seçilebilir ve çoklu seçilebilir parametreler

Seçilebilir ve çoklu seçilebilir parametreler, kullanıcılardan önceden tanımlanmış bir seçenek listesinden seçim yapmalarını ister.

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
Çoktan seçmeli parametre alanları
type
dizesi

select veya multiselect

Parametrenin, önceden tanımlanmış bir seçim grubundan seçilmiş tek bir değer (select) veya birkaç değer (multiselect) olabileceğini belirtir

options
seçenek listesi
(zorunlu)

Kullanıcının belirleyebileceği seçenekler

Seçenek alanları
value
dize
(zorunlu)
Kullanıcının seçebileceği değerlerden biri. Bu, koddaki parametre değerini okuduğunuzda elde ettiğiniz değerdir.
label
dize
(isteğe bağlı)
Seçilebilir seçeneğin kısa açıklaması. Atlanırsa varsayılan olarak value olur.

Seçilebilir kaynak parametreleri

Seçilebilir kaynak parametreleri, kullanıcılardan projelerinden kaynak (veri tabanı örneği, depolama paketi vb.) seçmelerini ister.

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
Kaynak parametresi alanları
type
dizesi

selectresource

Parametrenin bir proje kaynağını temsil ettiğini belirtir

resourceType
dize
(zorunlu)

Kullanıcının seçmesini istenecek kaynağın türü.

Geçerli değerler:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

Ancak şu anda yalnızca Cloud Storage paketlerinde seçili kullanıcı arayüzü bulunmaktadır (diğer kaynak türleri, serbest biçimli metin giriş alanları olarak sunulur).

Gizli anahtar parametreleri

Kullanıcı tarafından sağlanan gizli anahtar değerleri (ör. API anahtarları) farklı şekilde ele alınır:

  • Gizli anahtar değerleri, Cloud Secret Manager kullanılarak depolanır. Bu değerlere yalnızca yetkili istemciler (ör. bir uzantının yüklü örneği) erişebilir.
  • Kullanıcılardan bu değerleri girmeleri istendiğinde, girişleri gösterilmez.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Gizli parametre alanları
type
dizesi

secret

Parametrenin bir gizli anahtar değeri olduğunu belirtir

Cloud Functions işlevi kaynakları

Bu alanlar, bir uzantıya dahil olan Cloud Functions işlevlerini bildirir. Kaynak bildirimi söz dizimi, 1. nesil ve 2. nesil işlevler arasında biraz farklı görünür. Bunlar, uzantılarda bir arada olabilir.

1. Nesil 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
Kaynak alanları
name
dize
(zorunlu)

Dışa aktarılan işlevin kullanıcı dostu adı.

entryPoint özelliğini belirtmezseniz (aşağıya bakın) bu değer, işlevlerin kaynak kodundaki işlevin adıyla eşleşmelidir.

Dağıtılan işlevinin son adı şu biçimde olur: ext-extension-instance-id-name.

type
dize
(zorunlu)
1. nesil işlev kaynağı için: firebaseextensions.v1beta.function
description
dize
(zorunlu)

İşlevin uzantı için gerçekleştirdiği görevin kısa açıklaması.

properties
(zorunlu)

1. nesil Cloud Functions özellikleri. En önemli özellikler aşağıda listelenmiştir ancak bunların tam listesini Cloud Functions referansında bulabilirsiniz.

Mülkler
location
(isteğe bağlı)

İşlevin dağıtılacağı konum. Varsayılan olarak us-central1 değerine ayarlanır

entryPoint
(isteğe bağlı)
İşlevler kaynak kodunuzda, uzantının araması gereken dışa aktarılan işlevin adı. Varsayılan olarak yukarıdaki name değerine ayarlanır.
sourceDirectory
(isteğe bağlı)

Kök dizininde package.json öğenizi içeren dizin. İşlevlerinizin kaynak kodu bu dizinde olmalıdır. Varsayılan olarak functions değerine ayarlanır

Not: package.json öğesinin main alanı, işlevlerinizin kaynak koduna (ör. index.js) ait dosyayı belirtir.

timeout
(isteğe bağlı)

İşlevin maksimum yürütme süresi.

  • Varsayılan: 60s
  • Maksimum değer: 540s
availableMemoryMb
(isteğe bağlı)

İşlev için kullanılabilir MB cinsinden bellek miktarı.

  • Varsayılan: 256
  • Geçerli değerler: 128, 256, 512, 1024 ve 2048
runtime
(önerilir)

İşlevin çalışma zamanı ortamı.

httpsTrigger
veya
eventTrigger
veya
scheduleTrigger
veya
taskQueueTrigger
(bu işlev tetikleyicisi türlerinden biri gereklidir)
Her tetikleyici türü hakkında spesifik bilgiler almak için Cloud Functions'ı uzantı için yazma bölümüne bakın.

2. Nesil 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

Kaynak alanları
name
dize
(zorunlu)

Dışa aktarılan işlevin kullanıcı dostu adı.

entryPoint özelliğini belirtmezseniz (aşağıya bakın) bu değer, işlevlerin kaynak kodundaki işlevin adıyla eşleşmelidir.

Dağıtılan işlevinin son adı şu biçimde olur: ext-extension-instance-id-name.

type
dize
(zorunlu)
2. nesil işlev kaynağı için: firebaseextensions.v1beta.v2function
description
dize
(zorunlu)

İşlevin uzantı için gerçekleştirdiği görevin kısa açıklaması.

properties
(zorunlu)

2. nesil Cloud Functions özellikleri. En önemli özellikler aşağıda listelenmiştir ancak bunların tam listesini Cloud Functions referansında bulabilirsiniz.

Mülkler
location
(isteğe bağlı)

İşlevin dağıtılacağı konum. Varsayılan olarak us-central1 değerine ayarlanır

sourceDirectory
(isteğe bağlı)

Kök dizininde package.json öğenizi içeren dizin. İşlevlerinizin kaynak kodu bu dizinde olmalıdır. Varsayılan olarak functions değerine ayarlanır

Not: package.json öğesinin main alanı, işlevlerinizin kaynak koduna (ör. index.js) ait dosyayı belirtir.

Ayrıca, kendi özelliklerine sahip üç nesne türü alanı vardır:

buildConfig özellikleri
buildConfig.runtime
(önerilir)

İşlevin çalışma zamanı ortamı.

buildConfig.entryPoint
(isteğe bağlı)
İşlevler kaynak kodunuzda, uzantının araması gereken dışa aktarılan işlevin adı. Varsayılan olarak yukarıdaki name değerine ayarlanır.
serviceConfig özellikleri
serviceConfig.timeoutSeconds
(isteğe bağlı)

İşlevin maksimum yürütme süresi.

  • Varsayılan: 60
  • Maksimum değer: 540
serviceConfig.availableMemory
(isteğe bağlı)
Bir işlev için kullanılabilen bellek miktarı. Varsayılan olarak 256M değerine ayarlanır. Desteklenen birimler k, M, G, Mi, Gi şeklindedir. Herhangi bir birim sağlanmazsa değer bayt olarak yorumlanır.
eventTrigger özellikleri
eventTrigger.eventType
(zorunlu)
Dinlenecek etkinlik türü. Her bir ürünle ilgili kullanılabilir etkinlik türleri için Cloud Functions'ı uzantı için yazma bölümüne bakın.
eventTrigger.eventFilters
(isteğe bağlı)
Dinlenecek etkinlikleri daha da sınırlayan filtreler. Örneğin, yalnızca belirli bir kaynak kalıbıyla eşleşen etkinlikleri dinleyebilirsiniz. Her etkinlik türünü filtreleme hakkında bilgi edinmek için Cloud Functions'ı uzantı için yazma bölümüne bakın.
eventTrigger.channel
(isteğe bağlı)
Tetikleyiciyle ilişkilendirilen kanalın projects/{project}/locations/{location}/channels/{channel} biçimindeki adı. Bu özelliği çıkarırsanız işlev, projenin varsayılan kanalındaki etkinlikleri işler.
eventTrigger.triggerRegion
(isteğe bağlı)
Tetikleyici, yalnızca bu bölgeden gelen etkinlikleri alır. İşlevle aynı bölge, farklı bir bölge veya çoklu bölge ya da küresel olabilir. Sağlanmazsa varsayılan olarak işlevle aynı bölgeye ayarlanır.

Yaşam döngüsü etkinlikleri

Yaşam döngüsü etkinlikleri, bir kullanıcı uzantınızın bir örneğini yüklediğinde, güncellediğinde veya yapılandırdığında çalışacak işlevleri belirtmenize olanak tanır. Uzantınızın yaşam döngüsü olaylarını yönetme bölümüne göz atın.

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
Yaşam döngüsü etkinliği alanları
onInstall
(isteğe bağlı)

Kullanıcı uzantıyı yüklediğinde çalışan bir işlevi belirtir.

İşlev spesifikasyonu
function
dize
(zorunlu)

Etkinliği işleyecek görev sırası tarafından tetiklenen işlevin adı.

Bu işlev resources bölümünde bildirilmeli ve taskQueue tarafından tanımlanmış olmalıdır.

processingMessage
dize
(zorunlu)
Görev devam ederken Firebase konsolunda gösterilecek mesaj.
onUpdate
(isteğe bağlı)

Bir kullanıcı uzantıyı güncellediğinde çalışan bir işlevi belirtir.

İşlev spesifikasyonu
function
dize
(zorunlu)

Etkinliği işleyecek görev sırası tarafından tetiklenen işlevin adı.

Bu işlev resources bölümünde bildirilmeli ve taskQueue tarafından tanımlanmış olmalıdır.

processingMessage
dize
(zorunlu)
Görev devam ederken Firebase konsolunda gösterilecek mesaj.
onConfigure
(isteğe bağlı)

Kullanıcı uzantıyı yeniden yapılandırdığında çalışan bir işlevi belirtir.

İşlev spesifikasyonu
function
dize
(zorunlu)

Etkinliği işleyecek görev sırası tarafından tetiklenen işlevin adı.

Bu işlev resources bölümünde bildirilmeli ve taskQueue tarafından tanımlanmış olmalıdır.

processingMessage
dize
(zorunlu)
Görev devam ederken Firebase konsolunda gösterilecek mesaj.

Özel etkinlikler (Eventarc)

Özel etkinlikler, kullanıcıların kendi mantığını uzantınıza eklemelerine olanak tanımak için uzantınızın yayınladığı etkinliklerdir. Bir uzantıya kullanıcı kancaları ekleme konusundaki Eventarc bölümüne bakın.

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
Özel etkinlik alanları
type
dize
(zorunlu)
Etkinliğin tür tanımlayıcısı. Tanımlayıcıyı noktayla ayrılmış 3-4 alandan oluşturun: Yayıncı kimliği, uzantı adı ve etkinlik adı alanları zorunludur, Sürüm alanının doldurulması önerilir. Yayınladığınız her etkinlik türü için benzersiz ve açıklayıcı bir etkinlik adı seçin.
description
dize
(zorunlu)
Etkinliğin açıklaması.