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"
此範例會使用 SDK 類型直接存取 Blob 記憶體輸入系結所提供的基礎 BlobClient
物件:
import logging
import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.route(route="file")
@app.blob_input(
arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
logging.info(
f"Python blob input function processed blob \n"
f"Properties: {client.get_blob_properties()}\n"
f"Blob content head: {client.download_blob().read(size=1)}"
)
return "ok"
如需使用其他 SDK 類型的範例,請參閱 ContainerClient
和 StorageStreamDownloader
範例。
若要深入瞭解,包括如何在專案中啟用 SDK 類型系結,請參閱 SDK 類型系結。
程序代碼會建立 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 |
針對動態類型語言,指定基礎數據類型。 可能的值為 string 、binary 或 stream 。 如需詳細資訊,請參閱 觸發程式和系結概念。 |
如需使用 function.json 定義的 Python 函式,請參閱組 態 一節。
註釋
屬性 @BlobInput
可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性,請將 設定 dataType
為 binary
。 如需詳細資訊, 請參閱輸入範例 。
組態
僅適用於 Python v1 程式設計模型。
下表說明您在 function.json 檔案中設定的繫結設定屬性。
function.json 屬性 | 描述 |
---|---|
type | 必須設定為 blob 。 |
direction | 必須設定為 in 。 使用區段中會指出例外狀況。 |
name | 表示函式程式碼中 Blob 的變數名稱。 |
path | blob 的路徑。 |
connection | 指定 Azure Blob 連線方式的應用程式設定或設定集合的名稱。 請參閱連線。 |
dataType | 針對動態類型語言,指定基礎數據類型。 可能的值為 string 、binary 或 stream 。 如需詳細資訊,請參閱 觸發程式和系結概念。 |
如需完整範例,請參閱範例一節。
使用方式
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.Storage.Blobs 6.0.0 或更新版本 ,以及 SDK 類型系結的常見相依性。
只有在 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
。
屬性 @BlobInput
可讓您存取觸發函式的 Blob。 如果您使用位元組陣列搭配 屬性,請將 設定 dataType
為 binary
。 如需詳細資訊, 請參閱輸入範例 。
透過符合系結名稱參數在 function.json 檔案中指定名稱的參數存取 Blob 數據。
透過輸入為 InputStream 的參數存取 Blob 數據。 如需詳細資訊, 請參閱輸入範例 。
Functions 也支援適用於 Azure Blob 記憶體的 Python SDK 類型系結,可讓您使用這些基礎 SDK 類型來處理 Blob 數據:
重要
Python 的 SDK 類型支援目前為預覽狀態,且僅支援 Python v2 程式設計模型。 如需詳細資訊,請參閱 Python 中的 SDK 類型。
連線
屬性 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>__serviceUri 1 |
您使用 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 寫入佇列來處理多個重試失敗。 在表單中serviceUri
AzureWebJobsStorage
,會使用連接。 不過,指定 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 資料擁有者、儲存體佇列資料參與者和儲存體帳戶參與者的角色所涵蓋。 如需深入了解,請參閱使用身分識別連線到主機儲存體。