Azure Functions 的 Azure Blob 記憶體輸入系結

輸入系結可讓您將 Blob 記憶體資料讀取為 Azure 函式的輸入。

如需安裝和組態詳細數據的詳細資訊,請參閱概

重要

本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出,旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。 如需 v4 模型運作方式的詳細資訊,請參閱 Azure Functions Node.js開發人員指南。 若要深入瞭解 v3 與 v4 之間的差異,請參閱 移轉指南

Azure Functions 支援兩種適用於 Python 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊,請參閱 Python 開發人員指南

本文支援這兩種程序設計模型。

範例

您可以使用下列其中一種 C# 模式來建立 C# 函式:

  • 隔離的背景工作模型:在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程,才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。 隔離背景工作進程函式的延伸模組會使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
  • 同進程模型:在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中,函式可以使用 C# 腳本來執行,主要支援 C# 入口網站編輯。 進程內函式的延伸模組會使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

重要

支援將於 2026 年 11 月 10 日結束進程模型。 強烈建議您將 應用程式移轉至隔離的背景工作模型 ,以取得完整支援。

下列範例是 C# 函式 ,會在隔離的背景工作進程中執行,並使用 Blob 觸發程式搭配 Blob 輸入和 Blob 輸出 Blob 系結。 函式會藉由在test-samples-trigger容器中建立 Blob 來觸發。 它會從 test-samples-input 容器讀取文字檔,並根據觸發的檔名,在輸出容器中建立新的文本檔。

    public static class BlobFunction
    {
        [Function(nameof(BlobFunction))]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
            logger.LogInformation("Input Item = {myBlob}", myBlob);

            // Blob Output
            return "blob-output content";
        }
    }
}

本區段包含下列範例:

HTTP 觸發程式,從查詢字串查詢 Blob 名稱

下列範例顯示 Java 函式,該函式會使用 HttpTrigger 註釋接收包含 Blob 記憶體容器中檔案名稱的參數。 然後批 BlobInput 註會讀取檔案,並將其內容傳遞至 函式做為 byte[]

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

佇列觸發程式,從佇列訊息接收 Blob 名稱

下列範例顯示 Java 函式,該函式會使用 QueueTrigger 註釋來接收訊息,其中包含 Blob 記憶體容器中檔案的名稱。 然後批 BlobInput 註會讀取檔案,並將其內容傳遞至 函式做為 byte[]

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

Java 函式運行時間連結庫中,對 @BlobInput 值來自 Blob 的參數使用註釋。 此批注可以搭配原生 Java 類型、POJO 或使用 可為 Null 的值使用 Optional<T>

下列範例顯示佇列觸發的 TypeScript 函式 ,其會建立 Blob 複本。 此函式是由佇列訊息 (包含要複製的 Blob 名稱) 觸發。 新的 Blob 名稱為 {originalblobname}-Copy

import { app, input, InvocationContext, output } from '@azure/functions';

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

下列範例顯示佇列觸發的 JavaScript 函式 ,其會建立 Blob 複本。 此函式是由佇列訊息 (包含要複製的 Blob 名稱) 觸發。 新的 Blob 名稱為 {originalblobname}-Copy

const { app, input, output } = require('@azure/functions');

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

下列範例示範function.json檔案中定義的 Blob 輸入系結,讓傳入的 Blob 數據可供 PowerShell 函式使用。

以下是 json 組態:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

以下是函式程式碼:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

下列範例顯示 Blob 輸入和輸出系結。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型

程序代碼會建立 Blob 的複本。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

屬性

進程內隔離的背景工作進程 C# 連結庫都會使用屬性來定義函式。 C# 文稿會改用function.json組態檔,如 C# 腳本指南中所述

隔離的背景工作進程會使用 BlobInputAttribute 屬性來定義輸入系結,其採用下列參數:

參數 描述
BlobPath blob 的路徑。
[連接] 指定 Azure Blob 連線方式的應用程式設定或設定集合的名稱。 請參閱連線

當您在本機開發時,請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式,和 blob_output 裝飾專案上的blob_input下列屬性會定義 Blob 儲存體 觸發程式:

屬性 說明
arg_name 表示函式程式碼中 Blob 的變數名稱。
path Blob 的路徑 針對 blob_input 裝飾專案,它是 Blob 讀取。 blob_output針對裝飾專案,它是輸入 Blob 的輸出或複本。
connection 儲存體帳戶連接字串。
data_type 針對動態類型語言,指定基礎數據類型。 可能的值為 stringbinarystream。 如需詳細資訊,請參閱 觸發程式和系結概念

如需使用 function.json 定義的 Python 函式,請參閱組 一節。

註釋

屬性 @BlobInput 可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性,請將 設定 dataTypebinary。 如需詳細資訊, 請參閱輸入範例

組態

僅適用於 Python v1 程式設計模型。

下表說明您可以在傳遞至 input.storageBlob() 方法的物件options上設定的屬性。

屬性 說明
path blob 的路徑。
connection 指定 Azure Blob 連線方式的應用程式設定或設定集合的名稱。 請參閱連線

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

function.json 屬性 描述
type 必須設定為 blob
direction 必須設定為 in。 使用區段中會指出例外狀況。
name 表示函式程式碼中 Blob 的變數名稱。
path blob 的路徑。
connection 指定 Azure Blob 連線方式的應用程式設定或設定集合的名稱。 請參閱連線
dataType 針對動態類型語言,指定基礎數據類型。 可能的值為 stringbinarystream。 如需詳細資訊,請參閱 觸發程式和系結概念

如需完整範例, 請參閱範例一節

使用方式

Blob 輸入支援的系結類型取決於函式應用程式中所使用的擴充套件版本和 C# 形式。

當您想要讓函式處理單一 Blob 時,Blob 輸入系結可以繫結至下列類型:

類型 描述
string Blob 內容做為字串。 當 Blob 內容是簡單的文字時, 請使用 。
byte[] Blob 內容的位元組。
JSON 可序列化型別 當 Blob 包含 JSON 數據時,Functions 會嘗試將 JSON 數據還原串行化為一般舊的 CLR 物件 (POCO) 類型。
數據流1 Blob 內容的輸入數據流。
BlobClient1
BlockBlobClient1
PageBlobClient1
AppendBlobClient1
BlobBaseClient1
線上至 Blob 的用戶端。 此類型集提供處理 Blob 的最大控件,而且如果連線有足夠的許可權,則可以用來回寫它。

當您想要函式從容器處理多個 Blob 時,Blob 輸入系結可以繫結至下列類型:

類型 描述
T[]List<T> 其中 T 是其中一個單一 Blob 輸入系結類型 多個 Blob 的陣列或清單。 每個專案都代表容器中的一個 Blob。 您也可以繫結至這些類型所實作的任何介面,例如 IEnumerable<T>
BlobContainerClient1 線上至容器的用戶端。 此類型提供處理容器的最充分控制權,而且如果連接有足夠的許可權,則可以用來寫入容器。

1 若要使用這些類型,您必須參考 Microsoft.Azure.Functions.Worker.Extensions.儲存體。Blob 6.0.0 或更新版本,以及 SDK 類型系結的常見相依性。

只有在 Blob 大小很小時,才建議系結至 stringByte[] 。 這是建議的,因為整個 Blob 內容會載入記憶體中。 對於大部分的 Blob,請使用 StreamBlobClient 類型。 如需詳細資訊,請參閱 並行和記憶體使用量

如果您在嘗試系結至其中一個 儲存體 SDK 類型時收到錯誤訊息,請確定您有正確 儲存體 SDK 版本的參考

您也可以使用 儲存體 AccountAttribute 來指定要使用的記憶體帳戶。 當您需要使用與連結庫中其他函式不同的記憶體帳戶時,可以執行此動作。 建構函式會採用包含記憶體 連接字串的應用程式設定名稱。 屬性可以在參數、方法或類別層級套用。 下列範例顯示類別層級和方法層級:

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

要使用的記憶體帳戶會依下列順序決定:

  • 屬性 BlobTriggerConnection 屬性。
  • StorageAccount 用至與 屬性相同的參數 BlobTrigger 的屬性。
  • StorageAccount 用至函式的屬性。
  • StorageAccount 用至 類別的屬性。
  • 函式應用程式的預設記憶體帳戶,定義於應用程式設定中 AzureWebJobsStorage

屬性 @BlobInput 可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性,請將 設定 dataTypebinary。 如需詳細資訊, 請參閱輸入範例

使用 context.extraInputs.get()存取 Blob 數據。

透過符合系結名稱參數在 function.json 檔案中指定名稱的參數存取 Blob 數據。

透過輸入為 InputStream 的參數存取 Blob 數據。 如需詳細資訊, 請參閱輸入範例

連線

屬性 connection 是環境組態的參考,指定應用程式應該如何連線到 Azure Blob。 它可以指定:

如果設定的值既與單一設定完全相符,又是其他設定的前置詞比對,則會使用完全相符專案。

連接字串

若要取得 連接字串,請遵循管理記憶體帳戶存取密鑰中所述的步驟。 連接字串 必須是一般用途的記憶體帳戶,而不是 Blob 記憶體帳戶

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

如果應用程式設定名稱以 「AzureWebJobs」 開頭,您就只能在這裡指定名稱的其餘部分。 例如,如果您設定connection為 「My 儲存體」,Functions 運行時間會尋找名為 「AzureWebJobsMy 儲存體」 的應用程式設定。 如果您保留connection空白,Functions 運行時間會在名為 AzureWebJobsStorage的應用程式設定中使用預設 儲存體 連接字串。

身分識別型連線

如果您使用 5.x 版或更高版本的延伸模組non-.NET 語言堆疊組合 3.x 或更新版本),而不是搭配秘密使用 連接字串,您可以讓應用程式使用 Microsoft Entra 身分識別。 若要使用身分識別,您可以在對應至 connection 觸發程式和系結組態中 屬性的通用前置詞下定義設定。

如果您要將 設定connection為 「AzureWebJobs 儲存體」,請參閱使用身分識別來裝載記憶體 連線。 針對所有其他連線,擴充功能需要下列屬性:

屬性 環境變數範本 描述 範例值
Blob 服務 URI <CONNECTION_NAME_PREFIX>__serviceUri1 您使用 HTTPS 設定所連線之 Blob 服務的數據平面 URI。 https://< storage_account_name.blob.core.windows.net>

1<CONNECTION_NAME_PREFIX>__blobServiceUri 可作為別名。 如果 Blob 觸發程式將使用聯機組態, blobServiceUri 也必須隨附 queueServiceUri。 請參閱下方 。

serviceUri在 Blob、佇列和/或數據表之間使用整體聯機組態時,無法使用表單。 URI 只能指定 Blob 服務。 或者,您可以針對每個服務提供特別的 URI,以允許使用單一連線。 如果提供這兩個版本,則會使用多重服務窗體。 若要設定多個服務的連線,而不是 <CONNECTION_NAME_PREFIX>__serviceUri,請設定:

屬性 環境變數範本 描述 範例值
Blob 服務 URI <CONNECTION_NAME_PREFIX>__blobServiceUri 您使用 HTTPS 設定所連線之 Blob 服務的數據平面 URI。 https://< storage_account_name.blob.core.windows.net>
佇列服務 URI (Blob 觸發程式2 的必要專案) <CONNECTION_NAME_PREFIX>__queueServiceUri 使用 HTTPS 配置之佇列服務的數據平面 URI。 只有 Blob 觸發程式才需要此值。 <https:// storage_account_name.queue.core.windows.net>

2 Blob 觸發程式會藉由將有害 Blob 寫入佇列來處理多個重試失敗。 在表單中serviceUriAzureWebJobsStorage,會使用連接。 不過,指定 blobServiceUri時,也必須提供佇列服務 URI。queueServiceUri 建議您使用與 Blob 服務相同的記憶體帳戶中的服務。 您也需要藉由指派像是 儲存體 佇列數據參與者角色,確定觸發程式可以在設定的佇列服務中讀取和寫入訊息。

其他屬性可以設定為自定義連線。 請參閱 身分識別型連線的一般屬性。

主控於 Azure Functions 服務時,以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credentialclientID 屬性指定使用者指派的身分識別,但預設會使用系統指派的身分識別。 請注意,不支援使用資源標識符設定使用者指派的身分識別。 在其他內容中執行時,例如本機開發,會改用您的開發人員身分識別,但您可以自定義此身分識別。 請參閱 使用身分識別型連線進行本機開發。

授與權限給身分識別

正在使用的任何身分識別,都必須具有執行預期動作的權限。 對於大部分的 Azure 服務,這表示您必須 使用內建或自定義角色,在 Azure RBAC 中指派角色,以提供這些許可權。

重要

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

您必須建立角色指派,以在運行時間提供 Blob 容器的存取權。 擁有者之類的管理角色是不夠的。 下表顯示一般作業中使用 Blob 儲存體 擴充功能時建議的內建角色。 您的應用程式可能需要根據您撰寫的程式代碼進一步許可權。

繫結類型 範例內建角色
觸發程序 儲存體 Blob 數據擁有者and 儲存體 佇列數據參與者1

也必須將額外的許可權授與 AzureWebJobs 儲存體 連線。2
輸入繫結 儲存體 Blob 資料讀者
輸出繫結 儲存體 Blob 資料擁有者

1 Blob 觸發程式會藉由將有害 Blob 寫入連線所指定的記憶體帳戶上的佇列,來處理多個重試失敗。

2 AzureWebJobs 儲存體 聯機會在內部用於啟用觸發程式的 Blob 和佇列。 如果設定為使用身分識別型連線,則需要超出預設需求的額外許可權。 儲存體 Blob 數據擁有者、儲存體 佇列數據參與者和 儲存體 帳戶參與者角色涵蓋所需的許可權。 若要深入瞭解,請參閱使用身分識別 連線 裝載記憶體。

下一步