Vstupní vazba služby Azure Blob Storage pro Azure Functions
Vstupní vazba umožňuje číst data úložiště objektů blob jako vstup do funkce Azure Functions.
Informace o nastavení a konfiguraci najdete v přehledu.
Důležité
Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.
Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.
Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.
Tento článek podporuje oba programovací modely.
Příklad
Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:
- Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají
Microsoft.Azure.Functions.Worker.Extensions.*
obory názvů. - Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají
Microsoft.Azure.WebJobs.Extensions.*
obory názvů.
Důležité
Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.
Následující příklad je funkce jazyka C#, která běží v izolovaném pracovním procesu a používá trigger objektu blob se vstupními i výstupními vazbami objektu blob. Funkce se aktivuje vytvořením objektu blob v kontejneru test-samples-trigger . Načte textový soubor ze vstupního kontejneru test-samples a vytvoří nový textový soubor ve výstupním kontejneru na základě názvu aktivovaného souboru.
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";
}
}
}
Tato část obsahuje následující příklady:
- Trigger HTTP, vyhledání názvu objektu blob z řetězce dotazu
- Trigger fronty, příjem názvu objektu blob ze zprávy fronty
Trigger HTTP, vyhledání názvu objektu blob z řetězce dotazu
Následující příklad ukazuje funkci Java, která používá HttpTrigger
anotaci k přijetí parametru obsahujícího název souboru v kontejneru úložiště objektů blob. Poznámka BlobInput
pak přečte soubor a předá jeho obsah funkci jako .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();
}
Trigger fronty, příjem názvu objektu blob ze zprávy fronty
Následující příklad ukazuje funkci Java, která používá poznámku QueueTrigger
k přijetí zprávy obsahující název souboru v kontejneru úložiště objektů blob. Poznámka BlobInput
pak přečte soubor a předá jeho obsah funkci jako .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");
}
V knihovně modulu runtime funkcí Java použijte poznámku @BlobInput
k parametrům, jejichž hodnota pochází z objektu blob. Tuto poznámku lze použít s nativními typy Javy, POJOs nebo hodnotami null s použitím Optional<T>
.
Následující příklad ukazuje frontu aktivovanou typescriptovou funkci , která vytvoří kopii objektu blob. Funkce se aktivuje zprávou fronty, která obsahuje název objektu blob, který se má zkopírovat. Nový objekt blob má název {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,
});
Následující příklad ukazuje frontu aktivovanou javascriptovou funkci , která vytvoří kopii objektu blob. Funkce se aktivuje zprávou fronty, která obsahuje název objektu blob, který se má zkopírovat. Nový objekt blob má název {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);
},
});
Následující příklad ukazuje vstupní vazbu objektu blob definovanou v souboru function.json, která zpřístupňuje příchozí data objektů blob funkci PowerShellu.
Tady je konfigurace JSON:
{
"bindings": [
{
"name": "InputBlob",
"type": "blobTrigger",
"direction": "in",
"path": "source/{name}",
"connection": "AzureWebJobsStorage"
}
]
}
Tady je kód funkce:
# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"
V tomto příkladu se k přímému přístupu k podkladovému BlobClient
objektu poskytovanému vstupní vazbou blob storage používá typy sad SDK:
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"
Příklady použití jiných typů sad SDK najdete v ContainerClient
tématech a StorageStreamDownloader
ukázkách.
Další informace, včetně povolení vazeb typu sady SDK v projektu, najdete v tématu Vazby typu sady SDK.
Kód vytvoří kopii objektu 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"
Atributy
Knihovny C# v procesu i izolovaného pracovního procesu používají atributy k definování funkce. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.
Izolovaný pracovní proces definuje vstupní vazbu pomocí atributu BlobInputAttribute
, který přebírá následující parametry:
Parametr | Popis |
---|---|
BlobPath | Cesta k objektu blob. |
Připojení | Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k objektům blob Azure. Viz Připojení. |
Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values
.
Dekoratéry
Platí pouze pro programovací model Pythonu v2.
V případě funkcí Pythonu v2 definovaných pomocí dekorátorů definují následující vlastnosti blob_input
triggerů služby Blob Storage:blob_output
Vlastnost | Popis |
---|---|
arg_name |
Název proměnné, která představuje objekt blob v kódu funkce. |
path |
Cesta k objektu blob pro blob_input dekorátor je přečtený objekt blob. blob_output Pro dekorátor se jedná o výstup nebo kopii vstupního objektu blob. |
connection |
Připojovací řetězec účtu úložiště |
data_type |
U dynamicky zadaných jazyků určuje podkladový datový typ. Možné hodnoty jsou string , binary nebo stream . Další podrobnosti najdete v konceptech triggerů a vazeb. |
Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .
Poznámky
Tento @BlobInput
atribut poskytuje přístup k objektu blob, který funkci aktivoval. Pokud použijete bajtové pole s atributem, nastavte dataType
na binary
hodnotu . Podrobnosti najdete v příkladu vstupu.
Konfigurace
Platí pouze pro programovací model Pythonu v1.
Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options
metodě input.storageBlob()
.
Vlastnost | Popis |
---|---|
path | Cesta k objektu blob. |
připojení | Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k objektům blob Azure. Viz Připojení. |
Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json .
vlastnost function.json | Popis |
---|---|
type | Musí být nastavena na blob hodnotu . |
direction | Musí být nastavena na in hodnotu . Výjimky jsou zaznamenány v části využití . |
Jméno | Název proměnné, která představuje objekt blob v kódu funkce. |
path | Cesta k objektu blob. |
připojení | Název nastavení aplikace nebo kolekce nastavení, která určuje, jak se připojit k objektům blob Azure. Viz Připojení. |
Datatype | U dynamicky zadaných jazyků určuje podkladový datový typ. Možné hodnoty jsou string , binary nebo stream . Další podrobnosti najdete v konceptech triggerů a vazeb. |
Kompletní příklady najdete v části Příklad.
Využití
Typy vazeb podporované vstupem objektu blob závisí na verzi balíčku rozšíření a způsobu použití v aplikaci funkcí jazyka C#.
Pokud chcete, aby funkce zpracovávala jeden objekt blob, vstupní vazba objektu blob může svázat s následujícími typy:
Typ | Popis |
---|---|
string |
Obsah objektu blob jako řetězec. Použije se, když je obsah objektu blob jednoduchým textem. |
byte[] |
Bajty obsahu objektu blob. |
Serializovatelné typy JSON | Když objekt blob obsahuje data JSON, služba Functions se pokusí deserializovat data JSON do prostého typu objektu CLR (POCO). |
Stream1 | Vstupní datový proud obsahu objektu blob. |
BlobClient1, BlockBlobClient1, PageBlobClient1, AppendBlobClient1, BlobBaseClient1 |
Klient připojený k objektu blob. Tato sada typů nabízí největší kontrolu nad zpracováním objektu blob a lze ji použít k zápisu zpět, pokud má připojení dostatečná oprávnění. |
Pokud chcete, aby funkce zpracovávala více objektů blob z kontejneru, vstupní vazba objektu blob může svázat s následujícími typy:
Typ | Popis |
---|---|
T[] nebo List<T> kde T je jedním z typů vstupních vazeb jednoho objektu blob. |
Pole nebo seznam více objektů blob. Každá položka představuje jeden objekt blob z kontejneru. Můžete také vytvořit vazbu na všechna rozhraní implementovaná těmito typy, například IEnumerable<T> . |
BlobContainerClient1 | Klient je připojený ke kontejneru. Tento typ nabízí největší kontrolu nad zpracováním kontejneru a lze ho použít k zápisu, pokud má připojení dostatečná oprávnění. |
1 Pokud chcete použít tyto typy, musíte odkazovat na Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 nebo novější a běžné závislosti pro vazby typu sady SDK.
Vazba na string
objekt blob nebo Byte[]
se doporučuje pouze v případě, že je malá velikost objektu blob. To se doporučuje, protože celý obsah objektu blob se načte do paměti. U většiny objektů blob použijte Stream
typ nebo BlobClient
objekt blob. Další informace najdete v tématu Souběžnost a využití paměti.
Pokud se při pokusu o vytvoření vazby k některému z typů sady SDK služby Storage zobrazí chybová zpráva, ujistěte se, že máte odkaz na správnou verzi sady SDK služby Storage.
K určení účtu úložiště, který se má použít, můžete použít také StorageAccountAttribute . Můžete to udělat, když potřebujete použít jiný účet úložiště než jiné funkce v knihovně. Konstruktor přebírá název nastavení aplikace, které obsahuje připojovací řetězec úložiště. Atribut lze použít na úrovni parametru, metody nebo třídy. Následující příklad ukazuje úroveň třídy a úroveň metody:
[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
[FunctionName("BlobTrigger")]
[StorageAccount("FunctionLevelStorageAppSetting")]
public static void Run( //...
{
....
}
Účet úložiště, který se má použít, se určuje v následujícím pořadí:
- Vlastnost
BlobTrigger
atributuConnection
. - Atribut
StorageAccount
použitý na stejný parametr jakoBlobTrigger
atribut. - Atribut
StorageAccount
použitý na funkci. - Atribut
StorageAccount
použitý pro třídu. - Výchozí účet úložiště pro aplikaci funkcí, který je definován v
AzureWebJobsStorage
nastavení aplikace.
Tento @BlobInput
atribut poskytuje přístup k objektu blob, který funkci aktivoval. Pokud použijete bajtové pole s atributem, nastavte dataType
na binary
hodnotu . Podrobnosti najdete v příkladu vstupu.
Přístup k datům objektu blob prostřednictvím parametru, který odpovídá názvu určenému parametrem názvu vazby v souboru function.json .
Přístup k datům objektu blob prostřednictvím parametru zadaného jako InputStream. Podrobnosti najdete v příkladu vstupu.
Funkce také podporuje vazby typů sady Python SDK pro úložiště objektů blob v Azure, které umožňují pracovat s daty objektů blob pomocí těchto základních typů sady SDK:
Důležité
Podpora typů sad SDK pro Python je aktuálně ve verzi Preview a podporuje se pouze pro programovací model Pythonu v2. Další informace najdete v tématu Typy sad SDK v Pythonu.
Propojení
Vlastnost connection
je odkazem na konfiguraci prostředí, která určuje, jak se má aplikace připojit k objektům blob Azure. Může zadat:
- Název nastavení aplikace obsahující připojovací řetězec
- Název sdílené předpony pro více nastavení aplikace, společně definující připojení založené na identitě.
Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.
Connection string
Pokud chcete získat připojovací řetězec, postupujte podle kroků uvedených v tématu Správa přístupových klíčů účtu úložiště. Připojovací řetězec musí být pro účet úložiště pro obecné účely, nikoli účet úložiště Blob.
Tato připojovací řetězec by měla být uložena v nastavení aplikace s názvem, který connection
odpovídá hodnotě určené vlastností konfigurace vazby.
Pokud název nastavení aplikace začíná na "AzureWebJobs", můžete zde zadat pouze zbytek názvu. Pokud například nastavíte connection
"MyStorage", modul runtime Functions vyhledá nastavení aplikace s názvem AzureWebJobsMyStorage. Pokud necháte connection
prázdné, modul runtime Služby Functions použije výchozí připojovací řetězec úložiště v nastavení aplikace, které je pojmenované AzureWebJobsStorage
.
Připojení založená na identitách
Pokud používáte rozšíření verze 5.x nebo vyšší (sada 3.x nebo vyšší pro non-.NET zásobníky jazyků), místo použití připojovací řetězec s tajným kódem můžete aplikaci použít identitu Microsoft Entra. Pokud chcete použít identitu, definujete nastavení pod běžnou předponou, která se mapuje na connection
vlastnost v konfiguraci triggeru a vazby.
Pokud nastavujete connection
azureWebJobsStorage, přečtěte si téma Připojení k hostitelskému úložišti pomocí identity. Pro všechna ostatní připojení rozšíření vyžaduje následující vlastnosti:
Vlastnost | Šablona proměnné prostředí | Popis | Příklad hodnoty |
---|---|---|---|
Blob Service URI | <CONNECTION_NAME_PREFIX>__serviceUri 1 |
Identifikátor URI roviny dat služby Blob Service, ke které se připojujete, pomocí schématu HTTPS. | <https:// storage_account_name.blob.core.windows.net> |
1 <CONNECTION_NAME_PREFIX>__blobServiceUri
lze použít jako alias. Pokud se konfigurace připojení použije triggerem objektu blob, blobServiceUri
musí být doprovázena queueServiceUri
také . Viz níže.
Formulář serviceUri
nelze použít, pokud se má použít celková konfigurace připojení napříč objekty blob, frontami a/nebo tabulkami. Identifikátor URI může určit pouze službu blob. Jako alternativu můžete zadat identifikátor URI speciálně pro každou službu, což umožňuje použití jediného připojení. Pokud jsou k dispozici obě verze, použije se formulář s více službami. Pokud chcete nakonfigurovat připojení pro více služeb, nikoli <CONNECTION_NAME_PREFIX>__serviceUri
nastavit:
Vlastnost | Šablona proměnné prostředí | Popis | Příklad hodnoty |
---|---|---|---|
Blob Service URI | <CONNECTION_NAME_PREFIX>__blobServiceUri |
Identifikátor URI roviny dat služby Blob Service, ke které se připojujete, pomocí schématu HTTPS. | <https:// storage_account_name.blob.core.windows.net> |
Identifikátor URI služby Queue Service (vyžadovaný pro triggeryobjektů blob 2) | <CONNECTION_NAME_PREFIX>__queueServiceUri |
Identifikátor URI roviny dat služby fronty pomocí schématu HTTPS. Tato hodnota je nutná pouze pro triggery objektů blob. | <https:// storage_account_name.queue.core.windows.net> |
2 Trigger objektu blob zpracovává selhání napříč několika opakováními tím, že zapíše otrávené objekty blob do fronty . Ve formuláři serviceUri
AzureWebJobsStorage
se použije připojení. Při zadávání blobServiceUri
však musí být k dispozici také identifikátor URI služby fronty queueServiceUri
. Doporučujeme používat službu ze stejného účtu úložiště jako služba blob. Musíte také zajistit, aby trigger mohl číst a zapisovat zprávy ve službě nakonfigurované fronty přiřazením role, jako je Přispěvatel dat fronty služby Storage.
Pro přizpůsobení připojení mohou být nastaveny další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.
Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID
vlastnostmicredential
. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.
Udělení oprávnění identitě
Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.
Důležité
Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.
Musíte vytvořit přiřazení role, které poskytuje přístup k kontejneru objektů blob za běhu. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Blob Storage v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.
Typ vazby | Příklad předdefinovaných rolí |
---|---|
Trigger | Vlastník dat objektů blob služby Storage a Přispěvateldat fronty úložiště 1 Navíc musí být udělena také připojení AzureWebJobsStorage.2 |
Vstupní vazba | Čtenář dat v objektech blob služby Storage |
Výstupní vazba | Vlastník dat v objektech blob služby Storage |
1 Trigger objektu blob zpracovává selhání napříč několika opakováními tím, že zapíše otrávené objekty blob do fronty v účtu úložiště určeném připojením.
2 Připojení AzureWebJobsStorage se používá interně pro objekty blob a fronty, které aktivují trigger. Pokud je nakonfigurované tak, aby používalo připojení založené na identitě, potřebuje další oprávnění nad rámec výchozího požadavku. Požadovaná oprávnění jsou pokryta rolemi Vlastník dat objektů blob služby Storage, Přispěvatel dat fronty úložiště a Přispěvatel účtů úložiště. Další informace najdete v tématu Připojení k hostitelskému úložišti pomocí identity.