適用于 Azure Functions 的 Azure Blob 儲存體觸發程式

偵測到新的或已更新的 Blob 時,Blob 儲存體觸發程序會啟動函式。 Blob 內容會提供給函式的 輸入

Azure Blob 儲存體觸發程式需要一般用途的儲存體帳戶。 儲存體也支援具有階層命名空間的 V2 帳戶。 若要使用僅限 blob 的帳戶,或如果您的應用程式有特殊需求,請參閱使用此觸發程式的替代方案。

如需安裝和設定詳細資料的相關資訊,請參閱概觀

輪詢

輪詢會以混合方式在檢查記錄和執行定期容器掃描之間運作。 Blob 會以10000的群組一次掃描,而且間隔之間會使用接續 token。

警告

此外,會以「最大努力」建立儲存體記錄。 並不保證會擷取所有事件。 在某些情況下可能會遺失記錄。

如果您需要更快或更可靠的 blob 處理,請考慮在建立 blob 時建立佇列訊息。 然後,使用佇列觸發程序 (而不是 Blob 觸發程序) 處理該 Blob。 另一個選項是使用 Event Grid;請參閱教學課程使用 Event Grid 自動調整已上傳映像的大小

替代方案

事件方格觸發程式

注意

使用儲存體 Extensions 5.x 和更新版本時,Blob 觸發程式具有事件方格型 Blob 觸發程式的內建支援。 如需詳細資訊,請參閱下方的儲存體 extension 5.x 和更新版本一節。

事件方格觸發程式也有blob 事件的內建支援。 請使用 Event Grid 來因應以下情節的需求,避免使用 Blob 儲存體觸發程序:

  • 僅限 blob 的儲存體帳戶: blob 輸入和輸出系結支援 僅限 blob 的儲存體帳戶 ,但不適用於 blob 觸發程式。

  • 高規模:高擴充功能可以鬆散定義為在其中有超過100000個 blob 的容器,或每秒擁有超過100個 blob 更新的儲存體帳戶。

  • 現有的 blob:當您設定觸發程式時,blob 觸發程式會處理容器中的所有現有 blob。 如果您的容器有許多現有的 blob,而且只想要觸發新的 blob,請使用 Event Grid 觸發程式。

  • 延遲降至最低:如果函式應用程式在取用方案上,則處理新 blob 時最多會有10分鐘的延遲,如果函式應用程式已進入閒置狀態。 若要避免這類延遲,可以切換到 App Service 方案並啟用 Always On。 您也可以透過 Blob 儲存體帳戶使用 Event Grid 觸發程序。 如需範例,請參閱 Event Grid 教學課程

請參閱事件方格範例的事件方格教學課程的 影像調整大小

儲存體副檔名5.x 和更新版本

使用預覽儲存體擴充功能時,Blob 觸發程式中會有事件方格的內建支援,需要將參數設定 source 為現有 Blob 觸發程式中的事件方格。

如需有關如何使用以事件方格為基礎之 Blob 觸發程式的詳細資訊,請參閱 事件方格 Blob 觸發程式指南

佇列儲存體觸發程序

處理 blob 的另一個方法是撰寫對應至所建立或修改之 blob 的佇列訊息,然後使用 佇列儲存體觸發 程式來開始處理。

範例

下列範例示範在 samples-workitems 容器中新增或更新 Blob 時,寫入記錄的 C# 函式

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

Blob 觸發程序路徑 samples-workitems/{name} 中的字串 {name} 會建立繫結運算式,您可以在函式程式碼中用來存取觸發 Blob 的檔案名稱。 如需詳細資訊,請參閱本文稍後的 Blob 名稱模式

如需屬性的詳細資訊 BlobTrigger ,請參閱 屬性和批註

屬性和註釋

C# 類別庫中,使用下列屬性以設定 Blob 觸發程序:

  • BlobTriggerAttribute

    該屬性的建構函式採用路徑字串,指示要監看的容器以及可選的 Blob 名稱模式。 以下為範例:

    [FunctionName("ResizeImage")]
    public static void Run(
        [BlobTrigger("sample-images/{name}")] Stream image,
        [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
    {
        ....
    }
    

    您可以設定 Connection 屬性來指定要使用的儲存體帳戶,如下列範例所示:

    [FunctionName("ResizeImage")]
    public static void Run(
        [BlobTrigger("sample-images/{name}", Connection = "StorageConnectionAppSetting")] Stream image,
        [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
    {
        ....
    }
    

    如需完整範例,請參閱 觸發程式範例

  • StorageAccountAttribute

    提供另一種方式來指定要使用的儲存體帳戶。 建構函式採用的是內含儲存體連接字串的應用程式設定名稱。 屬性可以套用在參數、方法或類別層級。 下列範例所示範的是類別層級與方法層級:

    [StorageAccount("ClassLevelStorageAppSetting")]
    public static class AzureFunctions
    {
        [FunctionName("BlobTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ....
    }
    

要使用的儲存體帳戶按以下順序決定:

  • BlobTrigger 屬性的 Connection 內容。
  • StorageAccount 屬性套用至與 BlobTrigger 屬性相同的參數。
  • StorageAccount 屬性套用至該函式。
  • StorageAccount 屬性套用至該類別。
  • 函數應用程式 (「AzureWebJobsStorage」應用程式設定) 的預設儲存體帳戶。

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 BlobTrigger 屬性。

function.json 屬性 屬性內容 描述
type n/a 必須設為 blobTrigger。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。
direction n/a 必須設為 in。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。 例外狀況在使用方式一節中會加以說明。
name n/a 表示函式程式碼中 Blob 的變數名稱。
path BlobPath 要監視的 容器 。 可能是 Blob 名稱模式
connection [連接] 指定如何連線至 Azure Blob 的應用程式設定或設定集合的名稱。 請參閱 連接

當您要在本機開發時,應用程式設定會進入 local.settings.json 檔案

連接

connection屬性是環境設定的參考,可指定應用程式應如何連線至 Azure blob。 它可能會指定:

如果設定的值完全符合單一設定和其他設定的前置詞相符項,則會使用完全相符的。

連接字串

若要取得連接字串,請遵循「 管理儲存體帳戶存取金鑰」中顯示的步驟。 連接字串必須是用於一般用途的儲存體帳戶,而不是Blob 儲存體帳戶

此連接字串應儲存在應用程式設定中,其名稱符合系結設定之屬性所指定的值 connection

如果應用程式設定名稱是以「AzureWebJobs」開頭,於此僅能指定名稱的其餘部分。 例如,如果您將 connection 設定為「MyStorage」,則函式執行階段會尋找名稱為「AzureWebJobsMyStorage」的應用程式設定。 如果您將 connection 保留空白,則函式執行階段會使用應用程式設定中名稱為 AzureWebJobsStorage 的預設儲存體連接字串。

以身分識別為基礎的連接

如果您使用版本5.x 或更高版本的擴充功能,而不是使用具有秘密的連接字串,您可以讓應用程式使用 Azure Active Directory 身分識別。 若要這樣做,您可以在與觸發程式和系結設定中的屬性對應的通用前置詞下定義設定 connection

在此模式中,擴充功能需要下列屬性:

屬性 環境變數範本 Description 範例值
Blob 服務 URI <CONNECTION_NAME_PREFIX>__blobServiceUri1 您要連接之 blob 服務的資料平面 URI。 <storage_account_name>. blob.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri 可以當做別名使用。 如果同時提供這兩個別名, blobServiceUri 將會使用表單。 serviceUri當整個連接設定要跨 blob、佇列及/或資料表使用時,無法使用表單。

注意

根據預設,blob 觸發程式會在內部使用 Azure 佇列。 <CONNECTION_NAME_PREFIX>__queueServiceUri 您也可以指定,但是沒有它的預設行為是使用 "AzureWebJobsStorage" 定義的連接。 此觸發程式會在要用於這些佇列的任何連接上,需要儲存體佇列資料參與者

您可以設定其他屬性來自訂連接。 請參閱 以身分識別為基礎的連接的通用屬性

在 Azure Functions 服務中裝載時,以身分識別為基礎的連接會使用 受控識別。 預設會使用系統指派的身分識別,雖然您可以使用和屬性指定使用者指派的身分識別 credential clientID 。 當您在其他內容(例如本機開發)中執行時,會改為使用您的開發人員身分識別,雖然可以自訂。 請參閱 使用以身分識別為基礎的連線進行本機開發

授與身分識別的許可權

無論使用何種身分識別,都必須擁有執行所需動作的許可權。 您將需要使用可提供這些許可權的內建或自訂角色, 在 AZURE RBAC 中指派角色

重要

某些許可權可能會由目標服務公開,而不是所有內容所需的許可權。 可能的話,請遵循 最低許可權的原則,只授與身分識別所需的許可權。 例如,如果應用程式只需要能夠從資料來源讀取,請使用僅具有讀取權限的角色。 指派也允許寫入至該服務的角色並不適當,因為這會對讀取作業產生過多的許可權。 同樣地,您會想要確定角色指派的範圍僅限於需要讀取的資源。

您將需要建立可在執行時間提供 blob 容器存取權的角色指派。 擁有者之類的管理角色並不足夠。 下表顯示在正常操作中使用 Blob 儲存體擴充功能時,建議使用的內建角色。 您的應用程式可能需要以您撰寫的程式碼為基礎的其他許可權。

繫結類型 內建角色範例
觸發程序 [儲存體 Blob 資料擁有]者1
輸入系結 儲存體 Blob 資料讀者
輸出系結 儲存體 Blob 資料擁有者

1在某些設定中,blob 觸發程式可能還需要儲存體佇列資料參與者

使用量

預設

您可以針對觸發 Blob 使用下列參數類型:

  • Stream
  • TextReader
  • string
  • Byte[]
  • ICloudBlob1
  • CloudBlockBlob1
  • CloudPageBlob1
  • CloudAppendBlob1

1function.jsonFileAccess.ReadWrite C# 類別庫中需要 "inout" 繫結 direction

如果您嘗試繫結至其中一個儲存體 SDK 類型,並出現錯誤訊息,請確定您已參考正確的儲存體 SDK 版本

由於會將整個 blob 內容載入記憶體中,因此只有在 Blob 大小很小時才建議繫結至 stringByte[]。 一般而言,最好使用 StreamCloudBlockBlob 類型。 如需詳細資訊,請參閱本文稍後的並行存取和記憶體使用量

其他類型

使用5.0.0 或更高版本的儲存體擴充功能的應用程式,也可以使用Azure SDK for .net中的類型。 此版本支援舊版 ICloudBlobCloudBlockBlobCloudPageBlob 和類型,以支援 CloudAppendBlob 下列類型:

1function.jsonFileAccess.ReadWrite C# 類別庫中需要 "inout" 繫結 direction

如需使用這些類型的範例,請參閱擴充功能的 GitHub 存放庫。 深入瞭解這些新類型是不同的,以及如何從 Azure 遷移至這些新類型。儲存體Blob 遷移指南

Blob 名稱模式

您可以在 function.json 中的 path 屬性或 BlobTrigger 屬性建構函式中,指定 Blob 名稱模式。 名稱模式可以是篩選條件或繫結運算式。 下列各節提供相關範例。

提示

容器名稱不能包含名稱模式中的解析程式。

取得檔案名稱和副檔名

下列範例示範如何分別繫結至 Blob 檔案名稱和副檔名:

"path": "input/{blobname}.{blobextension}",

如果 Blob 名稱為 original-Blob1.txt,則函式程式碼中的 blobnameblobextension 變數值為 original-Blob1txt

Blob 名稱上的篩選條件

下列範例只會觸發 input 容器中以字串 "original-" 開頭的 Blob:

"path": "input/original-{name}",

如果 Blob 名稱為 original-Blob1.txt,則函式程式碼中 name 變數的值為 Blob1.txt

檔案類型上的篩選條件

下列範例只會在 .png 檔案上觸發:

"path": "samples/{name}.png",

檔案名稱中大括號上的篩選條件

若要尋找檔案名稱中的大括號,請使用兩個括號逸出括號。 下列範例篩選名稱中有大括號的 Blob:

"path": "images/{{20140101}}-{name}",

如果 blob 命名為 {20140101} -soundfile.mp3,則會soundfile.mp3函式程式 name 代碼中的變數值。

中繼資料

Blob 觸發程序提供數個中繼資料屬性。 這些屬性可作為其他繫結中繫結運算式的一部分或程式碼中的參數使用。 這些值的語意與 CloudBlob 類型相同。

屬性 類型 描述
BlobTrigger string 觸發 Blob 的路徑。
Uri System.Uri Blob 的主要位置 URI。
Properties BlobProperties Blob 的系統屬性。
Metadata IDictionary<string,string> Blob 的使用者定義中繼資料。

例如,下列 C# 指令碼和 JavaScript 範例會記錄觸發 Blob 的路徑,包括容器在內:

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

Blob 回條

Azure Functions 執行階段可確保不會針對一樣新或更新的 blob 多次呼叫 blob 觸發程序函式。 為了判斷指定的 blob 版本是否已處理過,它會維護 blob 回條

Azure Functions 會將 blob 回條儲存在您函數應用程式 (AzureWebJobsStorage 應用程式設定所定義) 的 Azure 儲存體帳戶中名為 azure-webjobs-hosts 的容器中。 Blob 回條具有下列資訊:

  • 觸發的函式 (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME> ,例如: MyFunctionApp.Functions.CopyBlob)
  • 容器名稱
  • Blob 類型 (BlockBlobPageBlob)
  • Blob 名稱
  • ETag (blob 版本識別碼,例如: 0x8D1DC6E70A277EF)

要強制重新處理某個 Blob,可以從 azure-webjobs-hosts 容器中手動刪除該 Blob 的 Blob 回條。 雖然重新處理可能不會立即發生,但保證會在稍後的時間點發生。 若要立即重新處理,可以更新 azure 中的 scaninfo blob -webjob-hosts/blobscaninfo 。 在屬性之後,任何具有上次修改時間戳記的 blob LatestScan 都會再次掃描。

有害 blob

當指定 blob 的 blob 觸發程序函式失敗時,Azure Functions 預設一共會重試該函式 5 次。

如果 5 次嘗試全都失敗,Azure Functions 會將訊息新增至名為 webjobs-blobtrigger-poison 的儲存體佇列。 您可以設定重試次數上限。 相同的 MaxDequeueCount 設定可用於處理有害的 Blob 和處理有害的佇列訊息。 適用於有害 Blob 的佇列訊息是一個 JSON 物件,其中包含下列屬性:

  • FunctionId (格式 <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
  • BlobType (BlockBlobPageBlob)
  • ContainerName
  • BlobName
  • ETag (blob 版本識別碼,例如: 0x8D1DC6E70A277EF)

平行存取和記憶體使用量

Blob 觸發程序會在內部使用佇列,因此並行函式叫用數上限由 host.json 中的佇列組態所控制。 預設設定會將並行存取限制為 24 個叫用。 這項限制會個別套用至使用 Blob 觸發程序的每個函式。

注意

若是使用第5.0.0 版或更高版本的儲存體擴充功能的應用程式,則在主機中的佇列設定只適用于佇列觸發程式。 Blob 觸發程式並行處理會改由 裝載于 json 中的 blob設定來控制。

取用方案會將一部虛擬機器上的函式應用程式限制 (VM) 至 1.5 GB 的記憶體。 每個並行執行的函式執行個體和函式執行階段本身都會使用記憶體。 如果 Blob 觸發的函式將整個 Blob 載入記憶體中,則該函式用於 Blob 的記憶體上限為 24 * Blob 大小上限。 例如,若某個函式應用程式有三個 Blob 觸發的函式,則預設的每一 VM 並行存取上限將是 3 * 24 = 72 個函式叫用。

JavaScript 和 JAVA 函式會將整個 blob 載入記憶體中,而 c # 函式則會在您系結至或時,執行此工作 string Byte[]

host.json 屬性

主機 json檔案包含控制 blob 觸發程式列為的設定。 如需可用設定的詳細資訊,請參閱 [host] 設定 一節。

下一步