Azure Blob Storage-indatabindning för Azure Functions

Med indatabindningen kan du läsa bloblagringsdata som indata till 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.

    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, leta upp blobnamn från frågesträngen

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[].

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

Köutlösare, ta emot blobnamn från kömeddelande

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[].

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

I Java Functions-körningsbiblioteket använder du anteckningen @BlobInput för parametrar vars värde skulle komma från en blob. Den här anteckningen kan användas med interna Java-typer, POJO:er eller null-värden med hjälp av Optional<T>.

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 en blobindatabindning, definierad i function.json-filen, vilket gör inkommande blobdata tillgängliga för PowerShell-funktionen.

Här är json-konfigurationen:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Här är funktionskoden:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

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 i både processprocess 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.

isolerad arbetsprocess definierar en indatabindning med hjälp av ett BlobInputAttribute attribut som 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 Anslut ioner.

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_inputblob_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.
data_type 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 @BlobInput 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 indataexemplet .

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 input.storageBlob() till metoden.

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

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

function.json egenskap beskrivning
typ Måste anges till blob.
riktning Måste anges till in. Undantag anges i användningsavsnittet.
Namn Namnet på variabeln som representerar bloben i funktionskoden.
sökväg Sökvägen till bloben.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Blobs. Se Anslut ioner.
Datatyp 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.

Se avsnittet Exempel för fullständiga exempel.

Användning

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

När du vill att funktionen ska bearbeta en enskild blob kan blobindatabindningen 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 När en blob innehåller JSON-data försöker Functions deserialisera JSON-data till en vanlig CLR-objekttyp (POCO).
Stream1 En indataström av blobinnehållet.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1
En klient som är ansluten till bloben. Den här uppsättningen typer ger mest kontroll för bearbetning av bloben och kan användas för att skriva tillbaka till den om anslutningen har tillräcklig behörighet.

När du vill att funktionen ska bearbeta flera blobar från en container kan blobindatabindningen binda till följande typer:

Typ Beskrivning
T[] eller List<T> var T är en av bindningstyperna för enskilda blobindata En matris eller lista över flera blobar. Varje post representerar en blob från containern. Du kan också binda till alla gränssnitt som implementeras av dessa typer, till exempel IEnumerable<T>.
BlobContainerClient1 En klient som är ansluten till containern. Den här typen ger mest kontroll för bearbetning av containern och kan användas för att skriva till den om anslutningen har tillräcklig behörighet.

1 Om du vill använda dessa typer måste du referera till Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 eller senare och de vanliga beroendena för SDK-typbindningar.

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-anslutningssträng. 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 BlobTriggerConnection 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 @BlobInput 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 indataexemplet .

Få åtkomst till blobdata med hjälp context.extraInputs.get()av .

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

Få åtkomst till blobdata via parametern som anges som InputStream. Mer information finns i indataexemplet .

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 anslutningssträng följer du stegen som visas i Hantera åtkomstnycklar för lagringskonto. Anslutningssträng måste vara för ett allmänt lagringskonto, inte för ett Blob Storage-konto.

Den här anslutningssträng 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 anslutningssträng 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) i stället för att använda en anslutningssträng med en hemlighet kan du 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 Anslut som värd för lagring 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 serviceUriAzureWebJobsStorage 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ägareochlagringskö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 Anslut som värd för lagring med en identitet.

Nästa steg