Azure Functions 的 Azure Blob 記憶體輸出系結
輸出系結可讓您修改和刪除 Azure 函式中的 Blob 記憶體數據。
如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。
重要
本文使用索引標籤來支援多個版本的 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 容器讀取文字檔，並根據觸發的檔名，在輸出容器中建立新的文本檔。
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
namespace SampleApp
{
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";
}
}
}
本區段包含下列範例：
使用 OutputBinding 的 HTTP 觸發程式 （Java）
下列範例顯示 Java 函式，該函式會使用 HttpTrigger 註釋接收包含 Blob 記憶體容器中檔案名稱的參數。 然後批 BlobInput 註會讀取檔案，並將其內容傳遞至 函式做為 byte[]。 批 BlobOutput 注會系結至 OutputBinding outputItem，然後函式會使用此函式將輸入 Blob 的內容寫入已設定的記憶體容器。
@FunctionName("copyBlobHttp")
@StorageAccount("Storage_Account_Connection_String")
public HttpResponseMessage copyBlobHttp(
@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,
@BlobOutput(
name = "target",
path = "myblob/{Query.file}-CopyViaHttp")
OutputBinding<String> outputItem,
final ExecutionContext context) {
// Save blob to outputItem
outputItem.setValue(new String(content, StandardCharsets.UTF_8));
// 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();
}
佇列觸發程式，使用函式傳回值 （Java）
下列範例顯示 Java 函式，該函式會使用 QueueTrigger 註釋來接收訊息，其中包含 Blob 記憶體容器中檔案的名稱。 然後批 BlobInput 註會讀取檔案，並將其內容傳遞至 函式做為 byte[]。 批 BlobOutput 注會系結至函式傳回值，然後由運行時間用來將輸入 Blob 的內容寫入設定的記憶體容器。
@FunctionName("copyBlobQueueTrigger")
@StorageAccount("Storage_Account_Connection_String")
@BlobOutput(
name = "target",
path = "myblob/{queueTrigger}-Copy")
public String copyBlobQueue(
@QueueTrigger(
name = "filename",
dataType = "string",
queueName = "myqueue-items")
String filename,
@BlobInput(
name = "file",
path = "samples-workitems/{queueTrigger}")
String content,
final ExecutionContext context) {
context.getLogger().info("The content of \"" + filename + "\" is: " + content);
return content;
}
在 Java 函式運行時間連結庫中，對 @BlobOutput 函式參數使用註釋，其值會寫入 Blob 記憶體中的物件。 參數類型應該是 OutputBinding<T>，其中 T 是任何原生 Java 類型或 POJO。
下列範例顯示佇列觸發的 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);
},
});
下列範例示範如何建立傳入 Blob 複本作為 PowerShell 函式的輸出。
在函式的組態檔 （function.json）， trigger 元數據屬性是用來在屬性中 path 指定輸出 Blob 名稱。
注意
若要避免無限迴圈，請確定您的輸入和輸出路徑不同。
{
"bindings": [
{
"name": "myInputBlob",
"path": "data/{trigger}",
"connection": "MyStorageConnectionAppSetting",
"direction": "in",
"type": "blobTrigger"
},
{
"name": "myOutputBlob",
"type": "blob",
"path": "data/copy/{trigger}",
"connection": "MyStorageConnectionAppSetting",
"direction": "out"
}
],
"disabled": false
}
以下是 PowerShell 程式代碼：
# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob
下列範例顯示 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# 腳本指南中所述。
建 BlobOutputAttribute 構函式會採用下列參數：
| 參數 | 描述 |
|---|---|
| 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 |
儲存體帳戶連接字串。 |
dataType |
針對動態類型語言，指定基礎數據類型。 可能的值為 string、binary 或 stream。 如需詳細資訊，請參閱 觸發程式和系結概念。 |
如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。
註釋
屬性 @BlobOutput 可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性，請將 設定 dataType 為 binary。 如需詳細資訊， 請參閱輸出範例 。
組態
僅適用於 Python v1 程式設計模型。
下表說明您在 function.json 檔案中設定的繫結設定屬性。
| 屬性 | 描述 |
|---|---|
| type | 必須設定為 blob。 |
| direction | 輸出系結必須設定為 out 。 使用區段中會指出例外狀況。 |
| name | 表示函式程式碼中 Blob 的變數名稱。 設為 $return 以參考函式傳回值。 |
| path | Blob 容器的路徑。 |
| connection | 指定 Azure Blob 連線方式的應用程式設定或設定集合的名稱。 請參閱連線。 |
如需完整範例，請參閱範例一節。
使用方式
Blob 輸出支援的系結類型取決於函式應用程式中所使用的擴充套件版本和 C# 形式。
當您想要讓函式寫入單一 Blob 時，Blob 輸出系結可以繫結至下列類型：
| 類型 | 描述 |
|---|---|
string |
Blob 內容做為字串。 當 Blob 內容是簡單的文字時， 請使用 。 |
byte[] |
Blob 內容的位元組。 |
| JSON 可序列化型別 | 物件，表示 JSON Blob 的內容。 函式會嘗試將一般舊的CLR物件 （POCO） 類型串行化為 JSON 數據。 |
當您想要讓函式寫入多個 Blob 時，Blob 輸出系結可以繫結至下列類型：
| 類型 | 描述 |
|---|---|
T[] 其中 T 是其中一個 Blob 輸出系結類型 |
數位，包含多個 Blob 的內容。 每個專案都代表一個 Blob 的內容。 |
針對其他輸出案例，直接從 Azure.Storage.Blobs 建立和使用類型。
只有在 Blob 大小很小時，才建議系結至 string或 Byte[] 。 這是建議的，因為整個 Blob 內容會載入記憶體中。 對於大部分的 Blob，請使用 Stream 或 BlobClient 類型。 如需詳細資訊，請參閱 並行和記憶體使用量。
如果您在嘗試系結至其中一個記憶體 SDK 類型時收到錯誤訊息，請確定您有正確的記憶體 SDK 版本的參考。
您也可以使用 StorageAccountAttribute 來指定要使用的記憶體帳戶。 當您需要使用與連結庫中其他函式不同的記憶體帳戶時，可以執行此動作。 建構函式會採用包含記憶體 連接字串的應用程式設定名稱。 屬性可以在參數、方法或類別層級套用。 下列範例顯示類別層級和方法層級：
[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
[FunctionName("BlobTrigger")]
[StorageAccount("FunctionLevelStorageAppSetting")]
public static void Run( //...
{
....
}
要使用的記憶體帳戶會依下列順序決定：
- 屬性
BlobTrigger的Connection屬性。 - 套
StorageAccount用至與 屬性相同的參數BlobTrigger的屬性。 - 套
StorageAccount用至函式的屬性。 - 套
StorageAccount用至 類別的屬性。 - 函式應用程式的預設記憶體帳戶，定義於應用程式設定中
AzureWebJobsStorage。
屬性 @BlobOutput 可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性，請將 設定 dataType 為 binary。 如需詳細資訊， 請參閱輸出範例 。
透過符合系結名稱參數在 function.json 檔案中指定名稱的參數存取 Blob 數據。
連線
屬性 connection 是環境組態的參考，指定應用程式應該如何連線到 Azure Blob。 此屬性可以指定：
- 包含 連接字串 的應用程式設定名稱
- 多個應用程式設定的共用前置詞名稱，一起定義身分識別型連線。
如果設定的值與單一設定完全相符，又與其他設定的開頭相符，則會使用完全相符項目。
連接字串
若要取得連接字串，請遵循管理儲存體帳戶存取金鑰所示的步驟。 連接字串 必須是一般用途的記憶體帳戶，而不是 Blob 記憶體帳戶。
此 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的 屬性所connection指定的值。
如果應用程式設定名稱以 「AzureWebJobs」 開頭，您就只能在這裡指定名稱的其餘部分。 例如，如果您設定 connection 為 「MyStorage」，Functions 運行時間會尋找名為 「AzureWebJobsMyStorage」 的應用程式設定。 如果您保留connection空白，Functions 運行時間會在名為 AzureWebJobsStorage的應用程式設定中使用預設的記憶體 連接字串。
身分識別型連線
如果您使用 5.x 版或更高版本的延伸模組（non-.NET 語言堆疊組合 3.x 或更新版本），而不是使用具有秘密的 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要使用身分識別，您可以在對應至 connection 觸發程式和系結組態中 屬性的通用前置詞下定義設定。
如果您要將 設定 connection 為 「AzureWebJobsStorage」，請參閱 使用身分識別連線到主機記憶體。 針對所有其他連線，擴充功能需要下列屬性：
| 屬性 | 環境變數範本 | 描述 | 範例值 |
|---|---|---|---|
| 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 服務時，以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。 請注意，不支援以資源識別碼來設定使用者指派的身分識別。 在本機開發等其他內容中執行時，雖然這可以自訂，但仍會改用您的開發人員身分識別。 請參閱使用身分識別型連線進行本機開發。
授與權限給身分識別
正在使用的任何身分識別，都必須具有執行預期動作的權限。 有關大多數 Azure 服務，意即您需要指派 Azure RBAC 的角色，利用提供這些權限的內建或自訂角色。
重要
部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠讀取資料來源，請使用只有讀取權限的角色。 不宜指派也允許寫入該服務的角色，因為讀取作業不需要這麼多權限。 同樣地，最好確保角色指派的範圍僅限於需要讀取的資源。
您必須建立可在執行階段存取 Blob 容器的角色指派。 擁有者之類的管理角色不足夠。 下表顯示在一般作業中使用 Blob 儲存體延伸模組時建議的內建角色。 您的應用程式可能會根據您撰寫的程式碼而要求進一步權限。
| 繫結類型 | 內建角色範例 |
|---|---|
| 觸發程序 | 儲存體 Blob 資料擁有者和儲存體佇列資料參與者1 也必須將額外權限授予 AzureWebJobsStorage 連線。2 |
| 輸入繫結 | 儲存體 Blob 資料讀者 |
| 輸出繫結 | 儲存體 Blob 資料擁有者 |
1 Blob 觸發程序會藉由將有害 Blob 寫入儲存體帳戶中由連線所指定的佇列，來處理多個重試失敗。
2 AzureWebJobsStorage 連線會針對啟用觸發程序的 Blob 和佇列在內部使用。 如果將其設定成使用身分識別型連線，則需要超出預設需求的額外權限。 所需的權限是由儲存體 Blob 資料擁有者、儲存體佇列資料參與者和儲存體帳戶參與者的角色所涵蓋。 如需深入了解，請參閱使用身分識別連線到主機儲存體。
例外狀況和傳回碼
| 繫結 | 參考 |
|---|---|
| Blob | Blob 錯誤碼 |
| Blob、數據表、佇列 | 記憶體錯誤碼 |
| Blob、數據表、佇列 | 疑難排解 |
下一步
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應