Uzantıya kullanıcı kancaları ekleme

Uzantınızı yükleyen kullanıcılara kendi uzantılarını ekleme olanağı sağlayabilirsiniz. özel bir mantık yürütmeniz gerekir. 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.

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

Eventarc etkinlikleri

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

  1. 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. İlgili içeriği oluşturmak için kullanılan 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, abone olduklarında hangi etkinliklere abone olacaklarını seçebilirler uzantıyı yükleyin.

  2. Uzantı işlevlerinizde, Admin SDK içinden 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 etkinlikleri yayınlamayı tercih ettiği.
    • EXT_SELECTED_EVENTS: Kullanıcının etkinlik türlerinin virgülle ayrılmış listesi yayınlamayı seçti. 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ı. İlgili içeriği oluşturmak için kullanılan Admin SDK, bu değeri otomatik olarak source alanına iletir. yayınlanmış etkinlik olabilir. 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,
      });
    
  3. 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: {
          // ...
        }
    });
    
  4. Yayınladığınız etkinlikleri PREINSTALL veya POSTINSTALL görünümünde kaydedin. dosyası olarak kaydedebilirsiniz.

    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, resim yüklendikten sonra yeniden boyutlandırıldı. Bu örnek işleyicinin, subject Bu etkinlik, bu örnekte resmin 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 etkinlik tetikleyicileri bölümüne bakın ekleyebilirsiniz.

Ö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 başarıyla tamamlanması gereken bir kanca sağlamak istediğinizde Uzantı işlevlerinden birinin çalışması için eşzamanlı kancalar kullanın.

Eşzamanlı bir kanca, kullanıcı tanımlı bir HTTPS çağrılabilir Cloud işlevi gerektirir ve tamamlanmayı bekler (muhtemelen bir değer döndürdüğü için) bakın. 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:

  1. Uzantınıza, kullanıcıların uzantısıyla birlikte özel Cloud Functions işlevine de yönlendirir. Ö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ı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.
          // ...
        });
    
  3. ÖN YÜKLEME veya ÖN YÜKLEME içinde kullanıma sunduğunuz kancaları belgeleyin. POSTINSTALL dosyası.

    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ş ve çıkışları
    • Yürütülmesi için gereken koşullar (veya seçenekler)

    Ayrıca, kullanıcıları kancada herhangi bir işlem yapmamaları konusunda uyarın aynı uzantıyı tetikleyebilecek ve sonuç olarak sonsuz döngüde bulabilirsiniz.

Örnek

Algolia Arama uzantısı Kullanıcı tarafından sağlanan bir dönüştürme işlevini çağırmak için eşzamanlı bir kanca sağlar. cevaplamaya çalıştım.