extensions.yaml referansı

Uzantınızı belirtme dosyanız (extension.yaml), uzantınızın meta verilerini içerir, uzantı tarafından oluşturulan kaynakları ve uzantının ihtiyaç duyduğu API'leri ve erişimi tanımlar ve uzantı tarafından sağlanan, kullanıcı tarafından yapılandırılmış tüm parametreleri tanımlar.

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

Temel ve kimliği tanımlayabilecek 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
string
(zorunlu)

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

Yalnızca küçük harf, sayı ve kısa çizgi 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 (bu kimlik daha sonra uzantının hizmet hesabının ve uzantıya özgü kaynakların adlarını oluşturmak için kullanılır).

version
string
(zorunlu)

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

Semver sürümlendirmesine uymalıdır (ör. 1.2.0).

specVersion
string
(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
boolean
(isteğe bağlı)

Uzantı tarafından kullanılan hizmetlerin ücretli katman Firebase faturalandırma hesabı gerektirip gerektirmediği.

Her zaman true olarak ayarlanır.

displayName
string
(isteğe bağlı)

Uzantının kolay görüntülenebilir 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
string
(isteğe bağlı)

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

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

Uzantınıza yönelik bir simge tasarlarken aşağıdaki yönergeleri göz önünde bulundurun:

  • Markanıza uygun arka plan ve poster renkleri seçin.
  • Simge renklerinizi basit tutun ve yalnızca 2 renk kullanın. Birden fazla renk kullanmak, simgenizin görsel açıdan göz korkutucu olmasına neden olabilir.
  • Aynı nedenle, simgenizdeki gradyanlardan da kaçının. Küçük boyutlarda gradyanların ayırt edilmesi zordur ve simgeyi görsel açıdan karmaşık hale getirir.
  • Uzantınızın işlevini anlatan basit ve benzersiz resimler kullanın.
  • Şirketiniz birden fazla uzantı oluşturuyorsa simge olarak logonuzu kullanmayın. Kullanıcılar uzantılarınızı birbirinden ayırt etmekte zorlanabilir.
  • Posteri görsel ve cesur hale getirin. Küçük boyutlarda iyi görünmeyecek ince veya ayrıntılı resimler kullanmayın.
  • Uzantılarınızın ne yaptığını açıklayan kelimeler eklemeyin. Metin genellikle daha küçük boyutlarda okunamaz.
tags
dize listesi
(isteğe bağlı)
Kullanıcıların uzantınızı keşfetmesine yardımcı olacak etiketler. Aşağıdaki etiketler, Uzantılar Merkezi'ndeki kategorilerle eşlenir: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
string
(isteğe bağlı)
Uzantısı dizininin erişilebildiği herkese açık URL.
releaseNotesUrl
string
(isteğe bağlı)
Uzantının sürüm notlarına erişilebilen herkese açık URL.
author
bir yazar nesnesi
(isteğe bağlı)

Uzantının birincil yazarı ve iletişim sorumlusu.

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

Yazarın adı.

Kişi, şirket, kuruluş vb. olabilir.

email
string
(isteğe bağlı)
Yazarın e-posta adresi.
url
string
(isteğe bağlı)
Yazar hakkında bilgilere erişilebilen herkese açık URL.
contributors
yazar nesnelerinin 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ı.

Kişi, şirket, kuruluş vb. olabilir.

email
string
(isteğe bağlı)
Yazarın e-posta adresi.
url
string
(isteğe bağlı)
Yazar hakkında bilgilere erişilebilen 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üklediğinde bu API'leri projelerinde otomatik olarak etkinleştirmeyi seçebilirler.

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
string
(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
string
(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 temel hazırlığı yapılan hizmet hesabına bu roller verilir.

Yalnızca desteklenen rollerden 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
Roller alanları
role
string
(zorunlu)

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

Desteklenen rollerden birinde olmalıdır.

reason
string
(zorunlu)
Uzantının bu rol tarafından verilen erişime neden ihtiyaç duyduğuna dair kısa açıklama
resource
dize
(isteğe bağlı)

Rolün kapsamını bu kaynakla sınırlayın.

Atlanırsa varsayılan olarak projects/${project_id} olur. Rollerin kapsamını azaltma bölümüne bakın.

Harici hizmetler

Bu alanlar, uzantının kullandığı Firebase ve Google dışı hizmetleri (genellikle REST API'leri) belirtir. Firebase uzantıları platformu, bu hizmetleri otomatik olarak etkinleştirme veya yetkilendirme yapmanın herhangi bir yolunu 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
string
(zorunlu)
Uzantının çalışması için gereken harici hizmetin adı
pricingUri
string
(zorunlu)
Hizmetin fiyatlandırma bilgilerinin URI'si

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

Bu alanlar, uzantının kullanıcıların yapılandırabileceği 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
string
(zorunlu)
Parametrenin adı. Kodda parametre değerine referans vermek için bu adı kullanırsınız.
label
string
(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'u destekler.

example
string
(isteğe bağlı)
Parametre için örnek değer.
default
dize
(isteğe bağlı)
Kullanıcı parametrenin 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ılmış değerinin doğrulanması için normal ifade. Google RE2 söz dizimi.
validationErrorMessage
string
(isteğe bağlı)
Normal ifade doğrulaması başarısız olursa gösterilecek hata mesajı.
required
boolean
(isteğe bağlı)
Kullanıcıdan parametrenin değeri istendiğinde kullanıcının boş bir dize gönderip gönderemeyeceğini belirler. Varsayılan olarak true değerine ayarlanır.
immutable
boolean
(isteğe bağlı)

Kullanıcının, yükleme sonrasında parametrenin değerini değiştirip değiştiremeyeceğini (ör. uzantıyı yeniden yapılandırırsa) 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
string
(isteğe bağlı)
Parametre türü. Özel parametre türleri için ek şartlar veya farklı kullanıcı arayüzü sunumu olabilir. Aşağıdaki bölümlere bakın.

Seçilebilir ve çoklu seçim yapılabilir parametreler

Seçilebilir ve çoklu seçilebilir parametreler, kullanıcılardan önceden tanımlanmış seçenekler 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
dize

select veya multiselect

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

options
seçenekler listesi
(zorunlu)

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

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

Seçilebilir kaynak parametreleri

Seçilebilir kaynak parametreleri, kullanıcılardan projelerinden bir kaynak (veritabanı örneği, depolama alanı paketi vb.) seçmesini 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
dize

selectresource

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

resourceType
string
(zorunlu)

Kullanıcıdan seçmesini isteyeceğiniz kaynak 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çim kullanıcı arayüzü vardır (diğer kaynak türleri, serbest biçimli metin giriş alanları olarak sunulur).

Gizli anahtar parametreleri

Kullanıcı tarafından sağlanan gizli değerler (API anahtarları gibi) farklı şekilde ele alınır:

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

secret

Parametrenin gizli bir değer olduğunu belirtir

Cloud Functions kaynakları

Bu alanlar, bir uzantıya dahil edilen Cloud Functions'ı tanımlar. Kaynak beyanı söz dizimi, bir uzantı içinde birlikte bulunabilen 1. nesil ve 2. nesil işlevler arasında biraz farklıdır.

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
string
(zorunlu)

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

entryPoint mülkünü belirtmezseniz (aşağıya bakın) bu değer, işlevlerin kaynak kodunuzdaki işlevin adıyla eşleşmelidir.

Yayınlanan işlevin nihai adı şu biçimde olacaktır: ext-extension-instance-id-name.

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

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

properties
(zorunlu)

1. nesil Cloud Functions mülkleri. En önemli özellikler aşağıda listelenmiştir ancak tam listeyi Cloud İşlevleri referansında bulabilirsiniz.

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

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

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

Kökünde package.json dosyanızı içeren dizin. İşlevlerinizin kaynak kodunun dosyası bu dizinde olmalıdır. Varsayılan olarak functions değerine ayarlanır.

Not: package.json öğesinin main alanı, işlevlerinizin kaynak kodunun dosyasını belirtir (index.js gibi).

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ılabilen MB cinsinden bellek miktarı.

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

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

  • Varsayılan olarak, Cloud Functions tarafından şu anda desteklenen Node.js sürümlerinin en yenisi kullanılır.
  • Geçerli değerler: nodejs14, nodejs16, nodejs18
httpsTrigger
veya
eventTrigger
veya
scheduleTrigger
veya
taskQueueTrigger
(bu işlev tetikleyici türlerinden biri gereklidir)
Her tetikleyici türü hakkında özel bilgi edinmek için Uzantı için Cloud Functions yazma başlıklı makaleyi inceleyin.

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
string
(zorunlu)

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

entryPoint mülkünü belirtmezseniz (aşağıya bakın) bu değer, işlevlerin kaynak kodunuzdaki işlevin adıyla eşleşmelidir.

Yayınlanan işlevin nihai adı şu biçimde olacaktır: ext-extension-instance-id-name.

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

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

properties
(zorunlu)

2. nesil Cloud Functions mülkleri. En önemli özellikler aşağıda listelenmiştir ancak tam listeyi Cloud İşlevleri referansında bulabilirsiniz.

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

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

sourceDirectory
(isteğe bağlı)

Kökünde package.json dosyanızı içeren dizin. İşlevlerinizin kaynak kodunun dosyası bu dizinde olmalıdır. Varsayılan olarak functions değerine ayarlanır.

Not: package.json öğesinin main alanı, işlevlerinizin kaynak kodunun dosyasını belirtir (index.js gibi).

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

buildConfig özellikleri
buildConfig.runtime
(önerilen)

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

  • Varsayılan olarak, Cloud Functions tarafından şu anda desteklenen Node.js sürümlerinin en yenisi kullanılır.
  • Geçerli değerler: nodejs14, nodejs16, nodejs18
buildConfig.entryPoint
(isteğe bağlı)
İşlevlerinizin kaynak kodunda dışa aktarılan ve uzantının araması gereken 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. Birim sağlanmazsa değer bayt olarak yorumlanır.
eventTrigger özellikleri
eventTrigger.eventType
(zorunlu)
Dinlenecek etkinlik türü. Her ürün için kullanılabilen etkinlik türleri için Bir uzantı için Cloud işlevleri 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 Uzantı için Cloud Functions yazma başlıklı makaleyi inceleyin.
eventTrigger.channel
(isteğe bağlı)
Tetikleyiciyle ilişkili kanalın adı (projects/{project}/locations/{location}/channels/{channel} biçiminde). Bu özelliği atlarsanız işlev, projenin varsayılan kanalındaki etkinlikleri dinler.
eventTrigger.triggerRegion
(isteğe bağlı)
Tetikleyici yalnızca bu bölgeden gelen etkinlikleri alır. Bu, işlevle aynı bölge, farklı bir bölge, çoklu bölge veya global bölge olabilir. Belirtilmemişse varsayılan olarak işlevle aynı bölgeyi kullanır.

Yaşam döngüsü etkinlikleri

Yaşam döngüsü etkinlikleri, 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ü etkinliklerini işleme başlıklı makaleyi inceleyin.

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ıştırılacak bir işlevi belirtir.

İşlev spesifikasyonu
function
dize
(zorunlu)

Etkinliği işleyecek görev kuyruğu tetikleme işlevinin adı.

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

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

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

İşlev spesifikasyonu
function
dize
(zorunlu)

Etkinliği işleyecek görev kuyruğu tetikleme işlevinin adı.

Bu işlev resources bölümünde tanımlanmalı ve taskQueue 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 kuyruğu tetikleme işlevinin adı.

Bu işlev resources bölümünde tanımlanmalı ve taskQueue 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 uzantınıza kendi mantıklarını eklemelerine olanak tanımak için uzantınızın yayınladığı etkinliklerdir. Bir uzantıya kullanıcı kancaları ekleme başlıklı makalenin Eventarc bölümünü inceleyin.

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
string
(zorunlu)
Etkinliğin tür tanımlayıcısıdır. 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ı önerilir. Yayınladığınız her etkinlik türü için benzersiz ve açıklayıcı bir etkinlik adı seçin.
description
string
(zorunlu)
Etkinliğin açıklaması.