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 API'leri ve uzantının gerektirdiği 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ının kullandığı hizmetlerin ücretli katmanlı bir Firebase faturalandırma hesabı gerektirip gerektirmediği.

Her zaman true olarak ayarlanır.

displayName
string
(isteğe bağlı)

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

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

description
string
(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ız için 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, simgenizde gradyan kullanmayı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 zorluk yaşar.
  • Posterin görsel ve kalın olmasına dikkat edin. Küçük boyutlarda iyi görünmeyecek ince veya ayrıntılı resimler kullanmayın.
  • Uzantınızın işlevini 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. Şu etiketler, Extensions Hub'daki kategorilerle eşlenir: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
dize
(isteğe bağlı)
Uzantısı dizininin erişilebildiği herkese açık URL.
releaseNotesUrl
dize
(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ı.

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

email
dize
(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ı.

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

email
dize
(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ü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
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 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
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
string
(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'ler) 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ı. Bu adı, koddaki parametre değerine referans vermek için 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
dize
(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örüntülenecek 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
dize
(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ümleri inceleyin.

Seçilebilir ve çoklu seçim yapılabilir 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ç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 olur.

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 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
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
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 tam listeyi Cloud İşlevleri 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ü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
(önerilir)

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

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 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

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ı.

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 çı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. Belirtilmemişse varsayılan olarak işlevle aynı bölgeyi kullanı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ış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 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ı)

Kullanıcı uzantıyı güncellediğinde çalıştırılacak 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 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 kuyruğu tetikleme işlevinin 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 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 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
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ı.