Uzantıya kullanıcı kancaları ekleme

Uzantılarınızı yükleyen kullanıcılara, uzantınızın yürütülmesine kendi özel mantıklarını ekleme olanağı sunabilirsiniz. Bunu yapmanın iki yolu vardır:

Eventarc etkinlikleri: Kullanıcılara etkinliklere eşzamansız olarak tepki verme olanağı sunmak için Eventarc'ta yayınlayabilirsiniz. Kullanıcılar, örneğin uzun süren görevler tamamlandıktan sonra bildirim gönderen etkinlik işleyici işlevleri dağıtabilir veya kendi son işleme işlevlerini tanımlayabilir.
Senkron kancalar: Kullanıcılara uzantınıza engelleme mantığı ekleme olanağı sunmak için uzantının çalışmasında önceden tanımlanmış noktalara senkron kancalar ekleyebilirsiniz. Bu noktalarda bir kullanıcı sağlayıcı işlevi çalıştırır ve yalnızca işlev tamamlandıktan sonra devam edersiniz. Önceden işleme görevleri genellikle bu kategoriye girer.

Bir uzantı bu yöntemlerden birini veya ikisini birden kullanabilir.

Eventarc etkinlikleri

Bir uzantıdaki etkinlikleri yayınlamak için:

Yayınlayacağınız etkinlik türlerini extension.yaml dosyasında tanımlayın:
```
events:
  - type: publisher-id.extension-name.version.event-name
    description: event-description
  - type: publisher-id.extension-name.version.another-event-name
    description: another-event-description
```
type tanımlayıcısı, noktayla ayrılmış birkaç alandan oluşur. Yayıncı kimliği, uzantı adı ve etkinlik adı alanları gereklidir. 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.

Örneğin, storage-resize-images uzantısı tek bir etkinlik türünü tanımlar:
```
events:
  - type: firebase.extensions.storage-resize-images.v1.complete
    description: |
      Occurs when image resizing completes. The event will contain further
      details about specific formats and sizes.
```
Kullanıcılar, uzantıyı yüklerken hangi etkinliklere abone olacaklarını seçebilir.
Uzatma işlevlerinizde, Eventarc API'yi Admin SDK Bu ayarlar aşağıdaki ortam değişkenleri kullanılarak gösterilir:
- EVENTARC_CHANNEL: Kullanıcının etkinlik yayınlamayı seçtiği Eventarc kanalının tam nitelikli adı.
- EXT_SELECTED_EVENTS: Kullanıcının yayınlamayı seçtiği etkinlik türlerinin virgülle ayrılmış listesi. Bir kanalı bu değerle başlattığınızda Yönetici SDK'sı, kullanıcının seçmediği etkinlikleri otomatik olarak filtreler.
- EVENTARC_CLOUD_EVENT_SOURCE: Cloud Event kaynak tanımlayıcısı. Yönetici SDK'sı, bu değeri yayınlanan etkinliklerin source alanında otomatik olarak iletir. Genellikle bu değişkeni açıkça kullanmanız gerekmez.
Etkinlikler yükleme sırasında etkinleştirilmediyse bu değişkenler tanımlanmaz. Bu özelliği, yalnızca etkinlikler etkinleştirildiğinde bir etkinlik kanalını başlatmak için kullanabilirsiniz:
```
import * as admin from "firebase-admin";
import {getEventarc} from 'firebase-admin/eventarc';

admin.initializeApp();

// Set eventChannel to a newly-initialized channel, or `undefined` if events
// aren't enabled.
const eventChannel =
  process.env.EVENTARC_CHANNEL &&
  getEventarc().channel(process.env.EVENTARC_CHANNEL, {
    allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
  });
```

Etkinlikleri, uzantınızda kullanıcılara göstermek istediğiniz noktalarda kanala yayınlayın. Örneğin:

// If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel && eventChannel.publish({
    type: 'firebase.extensions.storage-resize-images.v1.complete',
    subject: filename,  // the name of the original file
    data: {
      // ...
    }
});

Yayınladığınız etkinlikleri PREINSTALL veya POSTINSTALL dosyasında belgeleyin.

Her etkinlik için aşağıdakileri belgeleyin:
- Amaçlanan kullanım alanı
- Uzantınızın mantığındaki çalıştırıldığı nokta
- İçerdiği çıkış verileri
- Yürütme koşulları
Ayrıca, kullanıcıları etkinlik işleyicilerinde aynı uzantıyı tetikleyebilecek ve sonsuz döngüye neden olabilecek işlemler yapmamaları konusunda uyarın.

Bir uzantıdan etkinlik yayınladığınızda kullanıcılar özel mantıkla yanıt vermek için etkinlik işleyicileri dağıtabilir.

Örneğin, aşağıdaki örnekte orijinal resim yeniden boyutlandırıldıktan sonra silinir. Bu örnek işleyicinin, etkinliğin subject mülkünü (bu durumda resmin orijinal dosya adı) kullandığını unutmayın.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

Daha fazla bilgi için Özel etkinlik tetikleyicileri başlıklı makaleyi inceleyin.

Örnek

Resmi Resimleri Yeniden Boyutlandır uzantısı, bir resmi yeniden boyutlandırdıktan sonra Eventarc'ta yayınlayarak asenkron bir kanca sağlar.

Eşzamanlı kanca

Kullanıcılara, uzantı işlevlerinizden birinin çalışması için başarıyla tamamlanması gereken bir kanca sağlamak istediğinizde eşzamanlı kancalar kullanın.

Senkronize kanca, kullanıcı tanımlı bir HTTPS çağrılabilir Cloud işlevini çağırır ve devam etmeden önce işlevin tamamlanmasını bekler (muhtemelen döndürülen bir değerle). Kullanıcı tarafından sağlanan işlevde bir hata olması, uzantı işlevinde de hata oluşmasına neden olur.

Senkronize bir kanca göstermek için:

Uzantınıza, kullanıcıların uzantıyı özel Cloud işlevlerinin URL'siyle yapılandırmasına olanak tanıyan bir parametre ekleyin. Örneğin:

- param: PREPROCESSING_FUNCTION
  label: Pre-processing function URL
  description: >
    An HTTPS callable function that will be called to transform the input data
    before it is processed by this function.
  type: string
  example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
  required: false

Uzantınızda kancayı göstermek istediğiniz noktada, işlevi URL'sini kullanarak çağırın. Örneğin:

const functions = require('firebase-functions/v1');
const fetch = require('node-fetch');

const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;

exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
    .onWrite((change, context) => {
      // PREPROCESSING_FUNCTION hook begins here.
      // If a preprocessing function is defined, call it before continuing.
      if (preprocessFunctionURL) {
        try {
          await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
        } catch (e) {
          // Preprocessing failure causes the function to fail.
          functions.logger.error("Preprocessor error:", e);
          return;
        }
      }
      // End of PREPROCESSING_FUNCTION hook.

      // Main function logic follows.
      // ...
    });

Kullanıma sunduğunuz tüm kancaları PREINSTALL veya POSTINSTALL dosyasında belgeleyin.

Her kanca için aşağıdakileri belgeleyin:
- Amaçlanan kullanım alanı
- Uzantınızın mantığındaki çalıştırıldığı nokta
- Beklenen girişleri ve çıkışları
- Yürütülmesi için gereken koşullar (veya seçenekler)
Ayrıca, kullanıcıları kanca işlevinde aynı uzantıyı tetikleyebilecek ve sonsuz döngüye neden olabilecek işlemler yapmamaları konusunda uyarın.

Örnek

Algolia Search uzantısı, Algolia'ya yazmadan önce kullanıcı tarafından sağlanan bir dönüştürme işlevini çağırmaya yönelik senkronize bir kanca sağlar.