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ü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.

• 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 yürütür ve yalnızca bu 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. extension.yaml dosyasında yayınlayacağınız etkinlik türlerini 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.

2. Uzatma işlevlerinizde, Eventarc API'yi Admin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin SDKAdmin 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ı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ıların görmesini istediğiniz noktalarda 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:

   • Amaçlanan kullanım alanı
   • 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 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

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.

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:

1. 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
   

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. 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.