您可以依據上傳、更新或刪除 Cloud Storage 中的檔案和資料夾來觸發函式。
本頁範例是以在圖片檔上傳至 Cloud Storage 時觸發的範例函式為基礎。這個範例函式示範如何存取事件屬性、如何將檔案下載至 Cloud Functions 執行個體,以及處理 Cloud Storage 事件的其他基礎知識。
匯入必要模組
如要開始使用,請匯入處理 Cloud Storage 事件所需的模組:
Node.js
const {onObjectFinalized} = require("firebase-functions/v2/storage");
Python
from firebase_functions import storage_fn
如要建構完整範例,請一併新增 Firebase Admin SDK 和圖片處理工具的依附元件:
Node.js
const {initializeApp} = require("firebase-admin/app");
const {getStorage} = require("firebase-admin/storage");
const logger = require("firebase-functions/logger");
const path = require("path");
// library for image resizing
const sharp = require("sharp");
initializeApp();
Python
import io
import pathlib
from PIL import Image
from firebase_admin import initialize_app
initialize_app()
from firebase_admin import storage
設定 Cloud Storage 函式的範圍
請使用以下模式,將函式範圍限定在特定 Cloud Storage 值區,並設定任何想要的選項:
Node.js
// scope handler to a specific bucket, using storage options parameter
export archivedopts = onObjectArchived({ bucket: "myBucket" }, (event) => {
//…
});
Python
# Scope handler to a specific bucket using storage options parameter
@storage_fn.on_object_archived(bucket="myBucket")
def archived_bucket(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
# ...
相反地,範例縮圖產生器函式的範圍僅限於專案的預設值區:
Node.js
exports.generateThumbnail = onObjectFinalized({cpu: 2}, async (event) => { // ... });
Python
@storage_fn.on_object_archived()
def generatethumbnail(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
# ...
設定函式位置
位置之間如果不相符,可能會導致部署失敗。此外,Cloud Storage 值區位置與函式位置之間的距離,可能會導致網路延遲很大。為避免發生這些情況,請指定函式位置,使其透過下列任一方式比對值區/觸發條件位置:
- 函式位置與觸發位置相同
- 函式位置位於觸發位置 (當觸發區域為雙區域/多區域時)
- 如果觸發條件區域設為「
us-central1
」,函式可能會在任何位置執行
處理 Cloud Storage 事件
您可以利用下列處理常式來回應 Cloud Storage 事件:
Node.js
onObjectArchived
只有在值區已啟用物件版本管理時,才會傳送此訊息。這個事件表示物件的使用中版本已變為封存版本,原因可能是該物件已經封存,或是已由同名物件的上傳覆寫。onObjectDeleted
在永久刪除物件時傳送。這包含值區生命週期設定其中覆寫或刪除的物件。如果值區已啟用物件版本管理功能,則在物件封存時,系統不會傳送事件 (請參閱onArchive
),即使封存作業是透過storage.objects.delete
方法亦然。onObjectFinalized
當在值區中成功建立新物件 (或現有物件的新版本) 時,會傳送這個事件。包括複製或重寫現有物件。上傳失敗不會觸發這個事件。onMetadataUpdated
在現有物件的中繼資料變更時傳送。
Python
on_object_archived
只有在值區已啟用物件版本管理時,才會傳送此訊息。這個事件表示物件的使用中版本已變為封存版本,原因可能是該物件已經封存,或是已由同名物件的上傳覆寫。on_object_deleted
在永久刪除物件時傳送。這包含值區生命週期設定其中覆寫或刪除的物件。如果值區已啟用物件版本管理功能,則在物件封存時,系統不會傳送事件 (請參閱onArchive
),即使封存作業是透過storage.objects.delete
方法亦然。on_object_finalized
當在值區中成功建立新物件 (或現有物件的新版本) 時,會傳送這個事件。包括複製或重寫現有物件。上傳失敗不會觸發這個事件。on_metadata_updated
在現有物件的中繼資料變更時傳送。
存取 Cloud Storage 物件屬性
Cloud Functions 會顯示一些 Cloud Storage 物件屬性,例如更新檔案的物件大小和內容類型。只要物件中繼資料發生變更,metageneration
屬性就會遞增。如果是新物件,metageneration
的值則為 1
。
Node.js
const fileBucket = event.data.bucket; // Storage bucket containing the file. const filePath = event.data.name; // File path in the bucket. const contentType = event.data.contentType; // File content type.
Python
bucket_name = event.data.bucket
file_path = pathlib.PurePath(event.data.name)
content_type = event.data.content_type
縮圖產生範例會使用下列部分屬性來偵測函式傳回的結束情況:
Node.js
// Exit if this is triggered on a file that is not an image. if (!contentType.startsWith("image/")) { return logger.log("This is not an image."); } // Exit if the image is already a thumbnail. const fileName = path.basename(filePath); if (fileName.startsWith("thumb_")) { return logger.log("Already a Thumbnail."); }
Python
# Exit if this is triggered on a file that is not an image.
if not content_type or not content_type.startswith("image/"):
print(f"This is not an image. ({content_type})")
return
# Exit if the image is already a thumbnail.
if file_path.name.startswith("thumb_"):
print("Already a thumbnail.")
return
下載、轉換及上傳檔案
在某些情況下,可能不需要從 Cloud Storage 下載檔案。不過,如要執行密集的工作,例如從儲存在 Cloud Storage 的檔案產生縮圖圖片,您需要將檔案下載到函式執行個體,也就是執行程式碼的虛擬機器。
您可以將 Cloud Functions 與圖片處理程式搭配使用,例如 Node.js 適用的 sharp
和 Python 適用的 Pillow,以便對圖形圖片檔執行操作。以下範例說明如何為上傳的圖片檔建立縮圖:
Node.js
/**
* When an image is uploaded in the Storage bucket,
* generate a thumbnail automatically using sharp.
*/
exports.generateThumbnail = onObjectFinalized({cpu: 2}, async (event) => {
const fileBucket = event.data.bucket; // Storage bucket containing the file.
const filePath = event.data.name; // File path in the bucket.
const contentType = event.data.contentType; // File content type.
// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith("image/")) {
return logger.log("This is not an image.");
}
// Exit if the image is already a thumbnail.
const fileName = path.basename(filePath);
if (fileName.startsWith("thumb_")) {
return logger.log("Already a Thumbnail.");
}
// Download file into memory from bucket.
const bucket = getStorage().bucket(fileBucket);
const downloadResponse = await bucket.file(filePath).download();
const imageBuffer = downloadResponse[0];
logger.log("Image downloaded!");
// Generate a thumbnail using sharp.
const thumbnailBuffer = await sharp(imageBuffer).resize({
width: 200,
height: 200,
withoutEnlargement: true,
}).toBuffer();
logger.log("Thumbnail created");
// Prefix 'thumb_' to file name.
const thumbFileName = `thumb_${fileName}`;
const thumbFilePath = path.join(path.dirname(filePath), thumbFileName);
// Upload the thumbnail.
const metadata = {contentType: contentType};
await bucket.file(thumbFilePath).save(thumbnailBuffer, {
metadata: metadata,
});
return logger.log("Thumbnail uploaded!");
});
將檔案下載至 Cloud Functions 執行個體的臨時目錄。在這個位置,您可以視需要處理檔案,然後再上傳至 Cloud Storage。執行非同步工作時,請務必在回呼中傳回 JavaScript 承諾。
Python
@storage_fn.on_object_finalized()
def generatethumbnail(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
"""When an image is uploaded in the Storage bucket, generate a thumbnail
automatically using Pillow."""
bucket_name = event.data.bucket
file_path = pathlib.PurePath(event.data.name)
content_type = event.data.content_type
# Exit if this is triggered on a file that is not an image.
if not content_type or not content_type.startswith("image/"):
print(f"This is not an image. ({content_type})")
return
# Exit if the image is already a thumbnail.
if file_path.name.startswith("thumb_"):
print("Already a thumbnail.")
return
bucket = storage.bucket(bucket_name)
image_blob = bucket.blob(str(file_path))
image_bytes = image_blob.download_as_bytes()
image = Image.open(io.BytesIO(image_bytes))
image.thumbnail((200, 200))
thumbnail_io = io.BytesIO()
image.save(thumbnail_io, format="png")
thumbnail_path = file_path.parent / pathlib.PurePath(f"thumb_{file_path.stem}.png")
thumbnail_blob = bucket.blob(str(thumbnail_path))
thumbnail_blob.upload_from_string(thumbnail_io.getvalue(), content_type="image/png")
此程式碼會為儲存在臨時目錄中的圖片建立 200x200 縮圖,然後再上傳至 Cloud Storage。