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 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şlevlerini dağıtabilir veya kendi son işleme işlevlerini tanımlayabilir.

• Senkron kancalar: Kullanıcılara uzantınıza engelleme mantığı ekleme olanağı vermek için uzantının çalışmasındaki önceden tanımlanmış noktalara senkron kancalar ekleyebilirsiniz. Bu noktalarda, kullanıcı tarafından sağlanan bir işlevi çalıştırır ve yalnızca tamamlandıktan sonra devam edersiniz. Ön işleme görevleri genellikle bu kategoriye girer.

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

Eventarc etkinlikleri

Uzantıdan etkinlik 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ı, nokta ile ayrılmış çeşitli alanlardan 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 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üklediklerinde hangi etkinliklere abone olacaklarını seçebilir.

2. Uzantı işlevlerinizde, Eventarc API'yi Admin SDK içinden içe aktarın ve kullanıcının yükleme 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 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 Admin SDK, 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ına otomatik olarak geçirir. Genellikle bu değişkeni açıkça kullanmanız gerekmez.

   Etkinlikler yükleme sırasında etkinleştirilmediyse bu değişkenler tanımlanmamış olur. Bu bilgiyi, 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. Uzantınızda kullanıcılara göstermek istediğiniz noktalarda kanalda etkinlik 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 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ütülme koşulları

   Ayrıca, kullanıcıları etkinlik işleyicilerinde aynı uzantıyı tetikleyerek sonsuz döngüye yol açabilecek 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 örnek, yeniden boyutlandırıldıktan sonra orijinal resmi siler. Bu örnek işleyicinin, etkinliğin subject özelliğini kullandığını unutmayın. Bu örnekte bu özellik, 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.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

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

Örnek

Resmi Resize Images uzantısı, bir resmi yeniden boyutlandırdıktan sonra Eventarc'a yayınlayarak eşzamansız bir kanca sağlar.

Eşzamanlı kancalar

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

Senkron kanca, kullanıcı tanımlı bir HTTPS ile çağrılabilir Cloud Function'ı çağırır ve devam etmeden önce tamamlanmayı (döndürülen bir değerle birlikte olabilir) bekler. Kullanıcı tarafından sağlanan işlevdeki bir hata, uzantı işlevinde hataya neden oluyor.

Senkron bir kanca kullanıma sunmak için:

1. Uzantınıza, kullanıcıların uzantıyı özel Cloud Function'larının 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ızda kancayı kullanıma sunmak istediğiniz noktada, URL'sini kullanarak işlevi ç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. PREINSTALL veya POSTINSTALL dosyasında kullanıma sunduğunuz tüm kancaları belgeleyin.

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

   • Kullanım amacı
   • Uzantınızın mantığında çalıştığı nokta
   • Beklenen girişleri ve çıkışları
   • Koşulları (veya seçenekleri)

   Ayrıca, kullanıcıları aynı uzantıyı tetikleyerek sonsuz döngüye yol açabilecek işlemleri kanca işlevinde 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ğırmak için senkron bir kanca sağlar.