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:
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.
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 etkinliklerinsource
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, });
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: { // ... } });
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:
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
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. // ... });
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.