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 etkinlikleri: Kullanıcılara etkinliklere eşzamansız olarak tepki vermeleri için bir yöntem sunmak için Eventarc'ta yayınlayabilirsiniz. Kullanıcılar, örneğin uzun süreli görevler tamamlandıktan sonra bildirim gönderen etkinlik işleyici işlevlerini dağıtabilir veya kendi işleme sonrası işlevlerini tanımlayabilir.

  • Eşzamanlı kancalar: Kullanıcılara, uzantınıza engelleme mantığı eklemeleri için bir yöntem vermek amacıyla, uzantının işleminde önceden tanımlanmış noktalara eşzamanlı kancalar ekleyebilirsiniz. Bu noktalarda bir kullanıcı sağlayıcı işlevi yürütür ve yalnızca bu işlev tamamlandıktan sonra devam edersiniz. Ön işleme görevleri genellikle bu kategoriye girer.

Uzantılar, bu yöntemlerden birini veya her ikisini birden kullanabilir.

Eventarc etkinlikleri

Bir uzantıdan etkinlik yayınlamak için:

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

    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ının doldurulması ö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ü 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üklerken hangi etkinliklere abone olacaklarını seçebilir.

  2. Uzantı işlevlerinizde, Admin SDK'dan Eventarc API'yi içe aktarın ve kullanıcının yükleme ayarlarını kullanarak bir etkinlik kanalını başlatın. 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 adı.
    • EXT_SELECTED_EVENTS: Kullanıcının yayınlamayı seçtiği etkinlik türlerinin virgülle ayrılmış listesi. Bu değere sahip bir kanalı başlattığınızda Admin SDK otomatik olarak kullanıcının seçmediği etkinlikleri filtreler.
    • EVENTARC_CLOUD_EVENT_SOURCE: Bulut Etkinliği kaynağı tanımlayıcısı. Admin SDK, bu değeri yayınlanan etkinliklerin source alanına otomatik olarak iletir. Genellikle bu değişkeni açık bir şekilde kullanmanız gerekmez.

    Etkinlikler yükleme sırasında etkinleştirilmemişse bu değişkenler tanımsız olur. Bir etkinlik kanalını yalnızca etkinlikler etkin olduğunda başlatmak için bu bilgiyi 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. Kanalda, uzantınızın kullanıcılara göstermek istediğiniz noktalarda etkinlik yayınlayın. Örnek:

    // 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ıyla kaydedin.

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

    • Kullanım amacı
    • Uzantınızın mantığında çalıştığı 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 herhangi bir işlem 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 özelliğini (bu örnekte 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 bölümüne bakın.

Örnek

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

Eşzamanlı kancalar

Uzantı işlevlerinizden birinin çalışması için kullanıcılara 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 Cloud Functions işlevini çağırır ve devam etmeden önce tamamlanmayı (muhtemelen döndürülen bir değerle) bekler. Kullanıcı tarafından sağlanan işlevde bir hata, uzantı işlevinde hataya neden olur.

Eşzamanlı bir kancayı göstermek için:

  1. Uzantınıza, kullanıcıların uzantıyı özel Cloud Functions işlevi URL'si ile yapılandırmasına olanak tanıyan bir parametre ekleyin. Örnek:

    - 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ızda kancayı göstermek istediğiniz noktada URL'sini kullanarak işlevi çağırın. Örnek:

    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ı ÖN YÜKLEME veya POSTINSTALL dosyasında belgeleyin.

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

    • Kullanım amacı
    • Uzantınızın mantığında çalıştığı nokta
    • Beklenen giriş ve çıkışları
    • Yürütme koşulları (veya seçenekleri)

    Ayrıca kullanıcıları, kanca işlevinde aynı uzantıyı tetikleyerek sonsuz döngüye neden olabilecek herhangi bir işlem yapmamaları konusunda uyarın.

Örnek

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