Sdílet prostřednictvím

Vstupní vazba služby Azure Blob Storage pro Azure Functions

  • Článek

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

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, binarynebo 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 binaryhodnotu . 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 blobhodnotu .
direction Musí být nastavena na inhodnotu . 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, binarynebo 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 stringobjekt 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 atributu Connection .
  • Atribut StorageAccount použitý na stejný parametr jako BlobTrigger 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 binaryhodnotu . Podrobnosti najdete v příkladu vstupu.

Přístup k datům objektu blob pomocí .context.extraInputs.get()

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:

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>__serviceUri1 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 queueServiceUritaké . 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>__serviceUrinastavit:

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í blobServiceUrivš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.

Další kroky