Dela via


Azure Blob Storage-utdatabindning för Azure Functions

Med utdatabindningen kan du ändra och ta bort bloblagringsdata i en Azure-funktion.

Information om konfiguration och konfigurationsinformation finns i översikten.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för in-process-funktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.

Följande exempel är en C#-funktion som körs i en isolerad arbetsprocess och använder en blobutlösare med både blobindata- och blobutdatablobbindningar. Funktionen utlöses när en blob skapas i containern test-samples-trigger . Den läser en textfil från containern test-samples-input och skapar en ny textfil i en utdatacontainer baserat på namnet på den utlösta filen.

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

Det här avsnittet innehåller följande exempel:

HTTP-utlösare med OutputBinding (Java)

I följande exempel visas en Java-funktion som använder anteckningen HttpTrigger för att ta emot en parameter som innehåller namnet på en fil i en bloblagringscontainer. Anteckningen BlobInput läser sedan filen och skickar dess innehåll till funktionen som en byte[]. Anteckningen BlobOutput binder till OutputBinding outputItem, som sedan används av funktionen för att skriva innehållet i indatabloben till den konfigurerade lagringscontainern.

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

Köutlösare med hjälp av funktionens returvärde (Java)

I följande exempel visas en Java-funktion som använder anteckningen QueueTrigger för att ta emot ett meddelande som innehåller namnet på en fil i en bloblagringscontainer. Anteckningen BlobInput läser sedan filen och skickar dess innehåll till funktionen som en byte[]. Anteckningen BlobOutput binder till funktionens returvärde, som sedan används av körningen för att skriva innehållet i indatabloben till den konfigurerade lagringscontainern.

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

I Java Functions-körningsbiblioteket använder du anteckningen @BlobOutput för funktionsparametrar vars värde skulle skrivas till ett objekt i bloblagringen. Parametertypen ska vara OutputBinding<T>, där T är någon inbyggd Java-typ eller en POJO.

I följande exempel visas en köutlöst TypeScript-funktion som gör en kopia av en blob. Funktionen utlöses av ett kömeddelande som innehåller namnet på bloben som ska kopieras. Den nya bloben heter {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,
});

I följande exempel visas en köutlöst JavaScript-funktion som gör en kopia av en blob. Funktionen utlöses av ett kömeddelande som innehåller namnet på bloben som ska kopieras. Den nya bloben heter {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);
    },
});

I följande exempel visas hur du skapar en kopia av en inkommande blob som utdata från en PowerShell-funktion.

I funktionens konfigurationsfil (function.json) används metadataegenskapen trigger för att ange utdatablobnamnet i path egenskaperna.

Kommentar

För att undvika oändliga loopar kontrollerar du att dina indata- och utdatasökvägar är olika.

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

Här är PowerShell-koden:

# 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

I följande exempel visas blobindata- och utdatabindningar. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

Koden skapar en kopia av en 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"

Attribut

C#-bibliotek för både process- och isolerad arbetsprocess använder attribut för att definiera funktionen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

Konstruktorn BlobOutputAttribute tar följande parametrar:

Parameter Description
BlobPath Sökvägen till bloben.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Blobs. Se Anslutningar.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

För Python v2-funktioner som definierats med hjälp av dekoratörer definierar följande egenskaper på blob_input blob_output dekoratörerna bloblagringsutlösare:

Property beskrivning
arg_name Namnet på variabeln som representerar bloben i funktionskoden.
path Sökvägen till bloben För dekoratören blob_input är det blobläsningen. För dekoratören blob_output är det utdata eller kopia av indatabloben.
connection Anslutningssträngen för lagringskontot.
dataType För dynamiskt inskrivna språk anger du den underliggande datatypen. Möjliga värden är string, binaryeller stream. Mer information finns i begreppen utlösare och bindningar.

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

Attributet @BlobOutput ger dig åtkomst till den blob som utlöste funktionen. Om du använder en bytematris med attributet anger du dataType till binary. Mer information finns i utdataexemplet .

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.storageBlob() till metoden.

Property beskrivning
sökväg Sökvägen till blobcontainern.
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Blobs. Se Anslutningar.

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json .

Property Beskrivning
typ Måste anges till blob.
riktning Måste anges till out för en utdatabindning. Undantag anges i användningsavsnittet.
Namn Namnet på variabeln som representerar bloben i funktionskoden. Ange till för att referera till $return funktionens returvärde.
sökväg Sökvägen till blobcontainern.
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Blobs. Se Anslutningar.

Se avsnittet Exempel för fullständiga exempel.

Användning

Vilka bindningstyper som stöds av blobutdata beror på tilläggspaketversionen och den C#-modalitet som används i funktionsappen.

När du vill att funktionen ska skriva till en enda blob kan blobutdatabindningen binda till följande typer:

Typ Beskrivning
string Blobinnehållet som en sträng. Använd när blobinnehållet är enkel text.
byte[] Byte för blobinnehållet.
JSON-serialiserbara typer Ett objekt som representerar innehållet i en JSON-blob. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data.

När du vill att funktionen ska skriva till flera blobar kan blobutdatabindningen binda till följande typer:

Typ Beskrivning
T[] där T är en av bindningstyperna för enskilda blobutdata En matris som innehåller innehåll för flera blobar. Varje post representerar innehållet i en blob.

För andra utdatascenarier skapar och använder du typer från Azure.Storage.Blobs direkt.

Bindning till string, eller Byte[] rekommenderas endast när blobstorleken är liten. Detta rekommenderas eftersom hela blobinnehållet läses in i minnet. Använd en Stream eller BlobClient typ för de flesta blobar. Mer information finns i Samtidighet och minnesanvändning.

Om du får ett felmeddelande när du försöker binda till någon av Storage SDK-typerna kontrollerar du att du har en referens till rätt Storage SDK-version.

Du kan också använda StorageAccountAttribute för att ange vilket lagringskonto som ska användas. Du kan göra detta när du behöver använda ett annat lagringskonto än andra funktioner i biblioteket. Konstruktorn tar namnet på en appinställning som innehåller en lagrings-niska veze. Attributet kan användas på parameter-, metod- eller klassnivå. I följande exempel visas klassnivå och metodnivå:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

Lagringskontot som ska användas bestäms i följande ordning:

  • Attributets BlobTrigger Connection egenskap.
  • Attributet StorageAccount som tillämpas på samma parameter som attributet BlobTrigger .
  • Attributet StorageAccount som tillämpas på funktionen.
  • Attributet StorageAccount som tillämpas på klassen.
  • Standardlagringskontot för funktionsappen, som definieras i programinställningen AzureWebJobsStorage .

Attributet @BlobOutput ger dig åtkomst till den blob som utlöste funktionen. Om du använder en bytematris med attributet anger du dataType till binary. Mer information finns i utdataexemplet .

Få åtkomst till blobdata genom att returnera värdet direkt eller med hjälp av context.extraOutputs.set().

Få åtkomst till blobdata via en parameter som matchar namnet som anges av bindningens namnparameter i filen function.json .

Du kan deklarera funktionsparametrar som följande typer för att skriva ut till bloblagring:

  • Strängar som func.Out[str]
  • Strömmar som func.Out[func.InputStream]

Mer information finns i utdataexemplet .

anslutningar

Egenskapen connection är en referens till miljökonfigurationen som anger hur appen ska ansluta till Azure Blobs. Den kan ange:

Om det konfigurerade värdet både är en exakt matchning för en enskild inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Connection string

För att få en niska veze följer du stegen som visas i Hantera åtkomstnycklar för lagringskonto. Niska veze måste vara för ett allmänt lagringskonto, inte för ett Blob Storage-konto.

Den här niska veze ska lagras i en programinställning med ett namn som matchar det värde som anges av connection egenskapen för bindningskonfigurationen.

Om namnet på appinställningen börjar med "AzureWebJobs" kan du bara ange resten av namnet här. Om du till exempel anger connection "MyStorage" letar Functions-körningen efter en appinställning med namnet "AzureWebJobsMyStorage". Om du lämnar connection tomt använder Functions-körningen standardinställningen Storage niska veze i appinställningen med namnet AzureWebJobsStorage.

Identitetsbaserade anslutningar

Om du använder version 5.x eller senare av tillägget (paket 3.x eller senare för non-.NET språkstackar) kan du i stället för att använda en niska veze med en hemlighet låta appen använda en Microsoft Entra-identitet. Om du vill använda en identitet definierar du inställningar under ett vanligt prefix som mappar till connection egenskapen i utlösar- och bindningskonfigurationen.

Om du anger connection "AzureWebJobsStorage" läser du Ansluta till värdlagring med en identitet. För alla andra anslutningar kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Blob Service URI <CONNECTION_NAME_PREFIX>__serviceUri1 Dataplanets URI för blobtjänsten som du ansluter till med hjälp av HTTPS-schemat. <https:// storage_account_name.blob.core.windows.net>

1 <CONNECTION_NAME_PREFIX>__blobServiceUri kan användas som ett alias. Om anslutningskonfigurationen ska användas av en blobutlösare blobServiceUri måste även åtföljas av queueServiceUri. Se nedan.

Formuläret serviceUri kan inte användas när den övergripande anslutningskonfigurationen ska användas mellan blobar, köer och/eller tabeller. URI:n kan bara ange blobtjänsten. Alternativt kan du ange en URI specifikt för varje tjänst, vilket gör att en enda anslutning kan användas. Om båda versionerna tillhandahålls används formuläret för flera tjänster. Om du vill konfigurera anslutningen för flera tjänster i stället för <CONNECTION_NAME_PREFIX>__serviceUrianger du:

Property Miljövariabelmall beskrivning Exempelvärde
Blob Service URI <CONNECTION_NAME_PREFIX>__blobServiceUri Dataplanets URI för blobtjänsten som du ansluter till med hjälp av HTTPS-schemat. <https:// storage_account_name.blob.core.windows.net>
Kötjänst-URI (krävs för blobutlösare2) <CONNECTION_NAME_PREFIX>__queueServiceUri Dataplanets URI för en kötjänst med hjälp av HTTPS-schemat. Det här värdet behövs bara för blobutlösare. <https:// storage_account_name.queue.core.windows.net>

2 Blobutlösaren hanterar fel i flera återförsök genom att skriva giftblobar till en kö. I formuläret serviceUri AzureWebJobsStorage används anslutningen. Men när du blobServiceUrianger måste en kötjänst-URI också anges med queueServiceUri. Vi rekommenderar att du använder tjänsten från samma lagringskonto som blobtjänsten. Du måste också se till att utlösaren kan läsa och skriva meddelanden i den konfigurerade kötjänsten genom att tilldela en roll som Lagringsködatadeltagare.

Andra egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. För de flesta Azure-tjänster innebär det att du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt!

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om minsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom detta skulle vara överdriven behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Du måste skapa en rolltilldelning som ger åtkomst till din blobcontainer vid körning. Hanteringsroller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder Blob Storage-tillägget i normal drift. Ditt program kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller
Utlösare Lagringsblobdataägare och lagringsködatadeltagare1

Extra behörigheter måste också beviljas till AzureWebJobsStorage-anslutningen.2
Indatabindning Storage Blob Data-läsare
Utdatabindning Storage Blob Data-ägare

1 Blobutlösaren hanterar fel i flera återförsök genom att skriva giftblobar till en kö på det lagringskonto som anges av anslutningen.

2 AzureWebJobsStorage-anslutningen används internt för blobar och köer som aktiverar utlösaren. Om den har konfigurerats för att använda en identitetsbaserad anslutning behöver den extra behörigheter utöver standardkravet. De behörigheter som krävs omfattas av rollerna Storage Blob Data Owner, Storage Queue Data Contributor och Storage Account Contributor . Mer information finns i Ansluta till värdlagring med en identitet.

Undantag och returkoder

Bindning Referens
Blob Blobfelkoder
Blob, Tabell, Kö Felkoder för lagring
Blob, Tabell, Kö Felsökning

Nästa steg