Sdílet prostřednictvím

Výstupní vazba azure Blob Storage pro Azure Functions

  • Článek

Výstupní vazba umožňuje upravovat a odstraňovat data úložiště objektů blob ve funkci 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.

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";
        }
    }
}

Tato část obsahuje následující příklady:

Trigger HTTP s využitím outputBinding (Java)

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[] Poznámky BlobOutput se sváže s OutputBinding outputItemfunkcí, která se pak použije k zápisu obsahu vstupního objektu blob do nakonfigurovaného kontejneru úložiště.

  @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();
  }

Trigger fronty s použitím návratové hodnoty funkce (Java)

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[] Poznámka BlobOutput se sváže s vrácenou hodnotou funkce, která se pak používá modulem runtime k zápisu obsahu vstupního objektu blob do nakonfigurovaného kontejneru úložiště.

  @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;
  }

V knihovně modulu runtime funkcí Java použijte poznámku @BlobOutput k parametrům funkce, jejichž hodnota by byla zapsána do objektu v úložišti objektů blob. Typ parametru by měl být OutputBinding<T>, kde T je jakýkoli nativní typ Java nebo POJO.

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, jak vytvořit kopii příchozího objektu blob jako výstup funkce PowerShellu.

V konfiguračním souboru funkce (function.json) trigger se vlastnost metadat používá k určení názvu výstupního path objektu blob ve vlastnostech.

Poznámka:

Abyste se vyhnuli nekonečným smyčkám, ujistěte se, že se vaše vstupní a výstupní cesty liší.

{
  "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
}

Tady je kód PowerShellu:

# 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

Následující příklad ukazuje vstupní a výstupní vazby objektu blob. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

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í k definování funkce atribut. 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#.

Konstruktor BlobOutputAttribute 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ě
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.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

Tento @BlobOutput 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 výstupu.

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ě output.storageBlob() .

Vlastnost Popis
path Cesta ke kontejneru objektů 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 Popis
type Musí být nastavena na blobhodnotu .
direction Musí být nastavená na out výstupní vazbu. Výjimky jsou zaznamenány v části využití .
Jméno Název proměnné, která představuje objekt blob v kódu funkce. Nastaví se tak, aby $return odkaz na vrácenou hodnotu funkce.
path Cesta ke kontejneru objektů 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í.

Kompletní příklady najdete v části Příklad.

Využití

Typy vazeb podporované výstupem objektu blob závisí na verzi balíčku rozšíření a způsobu použití v aplikaci funkcí jazyka C#.

Pokud chcete, aby funkce zapisuje do jednoho objektu blob, výstupní 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 Objekt představující obsah objektu blob JSON. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisuje do více objektů blob, výstupní vazba objektu blob může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single blob output binding types Pole obsahující obsah pro více objektů blob. Každá položka představuje obsah jednoho objektu blob.

V případě jiných výstupních scénářů vytvořte a použijte Objekt BlobClient nebo BlobContainerClient s jinými typy přímo z Azure.Storage.Blobs . Příklad použití injektáže závislostí k vytvoření typu klienta ze sady Azure SDK najdete v tématu Registrace klientů Azure.

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 @BlobOutput 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 výstupu.

Přístup k datům objektu blob vrácením hodnoty přímo nebo pomocí context.extraOutputs.set().

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 .

Parametry funkce můžete deklarovat jako následující typy pro zápis do úložiště objektů blob:

  • Řetězce jako func.Out[str]
  • Streamy jako func.Out[func.InputStream]

Podrobnosti najdete v příkladu výstupu.

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.

Výjimky a návratové kódy

Vazba Reference
Objekt blob Kódy chyb objektů blob
Objekt blob, tabulka, fronta Kódy chyb úložiště
Objekt blob, tabulka, fronta Řešení potíží

Další kroky