Bir uzantıya kullanıcı kancaları ekleme

Uzantınızı yükleyen kullanıcılara, uzantınızın yürütülmesine kendi özel mantıklarını ekleme olanağı sağlayabilirsiniz. Bunu başarmanın iki yolu vardır:

  • Eventarc olayları : Kullanıcılara olaylara eşzamansız olarak tepki vermeleri için bir yol sağlamak için Eventarc'ta yayınlayabilirsiniz. Kullanıcılar, örneğin uzun süren görevler tamamlandıktan sonra bildirim gönderen olay işleyici işlevlerini dağıtabilir veya kendi işlem sonrası işlevlerini tanımlayabilir.

  • Eşzamanlı kancalar : Kullanıcılara uzantınıza engelleme mantığı ekleme olanağı sağlamak için, uzantının işleminde önceden tanımlanmış noktalara eşzamanlı kancalar ekleyebilirsiniz. Bu noktalarda bir kullanıcı-sağlayıcı işlevi çalıştırırsınız ve ancak tamamlandıktan sonra devam edersiniz. Ön işleme görevleri genellikle bu kategoriye girer.

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

Eventarc etkinlikleri

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

  1. extension.yaml dosyasında yayınlayacağınız etkinlik türlerini belirtin:

    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ı birkaç noktayla ayrılmış alandan oluşur. 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.

    Örneğin, storage-resize-images uzantısı tek bir olay türü bildirir:

    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üklediklerinde hangi etkinliklere abone olacaklarını seçebilecekler.

  2. Uzantı işlevlerinizde, Admin SDK'dan Eventarc API'sini içe aktarın ve kullanıcının kurulum ayarlarını kullanarak bir etkinlik kanalı başlatın. Bu ayarlar aşağıdaki ortam değişkenleri kullanılarak gösterilir:

    • EVENTARC_CHANNEL : Kullanıcının etkinlikleri yayınlamayı seçtiği Eventarc kanalının tam 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 : Bulut Etkinliği kaynak tanımlayıcısı. Yönetici SDK'sı bu değeri, yayınlanan etkinliklerin source alanına otomatik olarak iletir. Genellikle bu değişkeni açıkça kullanmanıza gerek yoktur.

    Kurulum sırasında olaylar etkinleştirilmemişse bu değişkenler tanımsız olacaktır. Bu gerçeği yalnızca olaylar etkinleştirildiğinde bir olay 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,
  });

  3. Uzantınızın kullanıcılara gösterilmesini istediğiniz noktalarda etkinlikleri kanalda 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: {
      // ...
    }
});

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

    Her olay için aşağıdakileri belgeleyin:

    • Amaçlanan amacı
    • Uzantınızın mantığında çalıştığı nokta
    • İçerdiği çıktı verileri
    • Yürütülmesi için koşullar

    Ayrıca kullanıcıları, olay işleyicilerinde aynı uzantıyı tetikleyebilecek ve sonsuz döngüye neden olabilecek herhangi bir eylem gerçekleştirmemeleri konusunda uyarın.

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

Örneğin, aşağıdaki örnek, yeniden boyutlandırıldıktan sonra orijinal görüntüyü siler. Bu örnek işleyicinin, olayın subject özelliğini kullandığını unutmayın; bu durumda bu, görüntünün orijinal dosya adıdır.

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 olay tetikleyicileri konusuna bakın.

Örnek

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

Senkron kancalar

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.

Eşzamanlı bir kanca, kullanıcı tanımlı bir HTTPS çağrılabilir Bulut İşlevini çağırır ve devam etmeden önce tamamlanmasını (muhtemelen döndürülen bir değerle) bekler. Kullanıcı tarafından sağlanan işlevdeki bir hata, uzantı işlevinde bir hataya neden olur.

Senkronize bir kancayı açığa çıkarmak için:

  1. Uzantınıza, kullanıcıların uzantıyı kendi özel Bulut İş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

  2. Uzantınızın kancayı ortaya çıkarmak istediğiniz noktasında, URL'sini kullanarak işlevi çağırın. Örneğin:

    const functions = require('firebase-functions');
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.
      // ...
    });

  3. Kullanılabilir hale getirdiğiniz tüm kancaları PREINSTALL veya POSTINSTALL dosyasında belgeleyin.

    Her kanca için aşağıdakileri belgeleyin:

    • Amaçlanan amacı
    • Uzantınızın mantığında çalıştığı nokta
    • Beklenen girdiler ve çıktılar
    • Yürütülmesi için koşullar (veya seçenekler)

    Ek olarak, kullanıcıları kanca işlevinde aynı uzantıyı tetikleyebilecek ve sonsuz döngüye neden olabilecek herhangi bir eylem gerçekleştirmemeleri konusunda uyarın.

Örnek

Algolia Arama uzantısı, Algolia'ya yazmadan önce kullanıcı tarafından sağlanan bir dönüştürme işlevini çağırmak için eşzamanlı bir kanca sağlar.