Azure Blob Storage-Trigger für Azure Functions

Der Blobspeichertrigger startet eine Funktion, wenn ein neues oder aktualisiertes Blob erkannt wird. Der Blobinhalt wird als Eingabe für die Funktion bereitgestellt.

Ausführliche Informationen zu den Unterschieden zwischen den beiden Implementierungen des BLOB-Speichertriggers sowie zu anderen Triggeroptionen finden Sie unter Arbeiten mit Blobs.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Beispiel

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

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

@FunctionName("blobprocessor")
public void run(
  @BlobTrigger(name = "file",
               dataType = "binary",
               path = "myblob/{name}",
               connection = "MyStorageAccountAppSetting") byte[] content,
  @BindingName("name") String filename,
  final ExecutionContext context
) {
  context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}

import { app, InvocationContext } from '@azure/functions';

export async function storageBlobTrigger1(blob: Buffer, context: InvocationContext): Promise<void> {
    context.log(
        `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
    );
}

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: storageBlobTrigger1,
});

const { app } = require('@azure/functions');

app.storageBlob('storageBlobTrigger1', {
    path: 'samples-workitems/{name}',
    connection: 'MyStorageAccountAppSetting',
    handler: (blob, context) => {
        context.log(
            `Storage blob function processed blob "${context.triggerMetadata.name}" with size ${blob.length} bytes`
        );
    },
});

{
    "disabled": false,
    "bindings": [
        {
            "name": "myBlob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

module.exports = async function(context) {
    context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
};

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

param([byte[]] $InputBlob, $TriggerMetadata)

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

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.blob_trigger(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_trigger(client: blob.BlobClient):
    logging.info(
        f"Python blob trigger function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobTrigger1")
@app.blob_trigger(arg_name="myblob", 
                  path="PATH/TO/BLOB",
                  connection="CONNECTION_SETTING")
def test_function(myblob: func.InputStream):
   logging.info(f"Python blob trigger function processed blob \n"
                f"Name: {myblob.name}\n"
                f"Blob Size: {myblob.length} bytes")

{
    "scriptFile": "__init__.py",
    "disabled": false,
    "bindings": [
        {
            "name": "myblob",
            "type": "blobTrigger",
            "direction": "in",
            "path": "samples-workitems/{name}",
            "connection":"MyStorageAccountAppSetting"
        }
    ]
}

import logging
import azure.functions as func


def main(myblob: func.InputStream):
    logging.info('Python Blob trigger function processed %s', myblob.name)

[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)

[FunctionName("ResizeImage")]
public static void Run(
  [BlobTrigger("sample-images/{name}")] Stream image,
  [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
  ....
}

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

Vollständige Beispiele finden Sie im Abschnitt „Beispiele“.

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

context.log(`Full blob path: ${context.triggerMetadata.blobTrigger}`);

module.exports = async function (context, myBlob) {
    context.log("Full blob path:", context.bindingData.blobTrigger);
};

Verwendung

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

Verbindungen

Die Eigenschaft connection ist ein Verweis auf die Umgebungskonfiguration, die angibt, wie die App eine Verbindung mit Azure-Blobs herstellen soll. Folgendes kann angegeben werden:

• Der Name einer Anwendungseinstellung, die eine Verbindungszeichenfolge enthält
• Der Name eines gemeinsam genutzten Präfixes für mehrere Anwendungseinstellungen, die zusammen eine identitätsbasierte Verbindung definieren.

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Um eine Verbindungszeichenfolge zu erhalten, folgen Sie den Schritten unter Verwaltung der Zugriffsschlüssel für Speicherkonten. Bei der Verbindungszeichenfolge muss es sich um eine Verbindungszeichenfolge für ein allgemeines Speicherkonto (nicht für ein Blobspeicherkonto) handeln.

Diese Verbindungszeichenfolge sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der dem in der Eigenschaft connection der Bindungskonfiguration angegebenen Wert entspricht.

Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie hier nur den Rest des Namens angeben. Wenn Sie connection also beispielsweise auf „MyStorage“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyStorage“. Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Storage-Verbindungszeichenfolge aus der App-Einstellung AzureWebJobsStorage.

Identitätsbasierte Verbindungen

Wenn Sie Version 5.x oder höher der Erweiterung verwenden (Bündel 3.x oder höher für non-.NET Sprachstapel), anstatt einen Verbindungszeichenfolge mit einem geheimen Schlüssel zu verwenden, können Sie die App über eine Microsoft Entra-Identität verfügen. Um eine Identität zu verwenden, definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Eigenschaft connection in der Trigger- und Bindungskonfiguration zugeordnet ist.

Wenn Sie connection auf „AzureWebJobsStorage“ festlegen, finden Sie weitere Informationen unter Herstellen einer Verbindung zum Hostspeicher mit einer Identität. Für alle anderen Verbindungen erfordert die Erweiterung die folgenden Eigenschaften:

¹ <CONNECTION_NAME_PREFIX>__blobServiceUri kann als Alias verwendet werden. Wenn die Verbindungskonfiguration von einem Blobtrigger verwendet wird, muss blobServiceUri auch von queueServiceUri begleitet werden. Siehe unten.

Das Format serviceUri kann nicht verwendet werden, wenn die gesamte Verbindungskonfiguration über Blobs, Warteschlangen und/oder Tabellen hinweg verwendet werden soll. Der URI kann nur den Blob-Dienst festlegen. Alternativ können Sie einen URI speziell für jeden Dienst bereitstellen, sodass eine einzelne Verbindung verwendet werden kann. Wenn beide Versionen bereitgestellt werden, wird das Format für mehrere Dienste verwendet. Um die Verbindung für mehrere Dienste anstelle von <CONNECTION_NAME_PREFIX>__serviceUri zu konfigurieren, legen Sie Folgendes fest:

² Fehler bei mehreren erneuten Versuchen werden vom Blobtrigger durch Schreiben nicht verarbeitbarer Blobs in eine Warteschlange behandelt. Im serviceUri-Formular wird die AzureWebJobsStorage-Verbindung verwendet. Beim Angeben von blobServiceUri muss jedoch auch ein Warteschlangendienst-URI mit queueServiceUri bereitgestellt werden. Es wird empfohlen, den Dienst von demselben Speicherkonto aus zu verwenden wie den Blob-Dienst. Sie müssen ebenfalls sicherstellen, dass der Trigger Nachrichten im konfigurierten Warteschlangendienst lesen und schreiben kann, indem Sie eine Rolle wie Mitwirkender für Storage-Warteschlangendaten zuweisen.

Andere Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihren Blob-Container ermöglicht. Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für den normalen Betrieb mit der Blob Storage-Erweiterung empfohlen werden. Ihre Anwendung erfordert möglicherweise weitere Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

¹ Fehler bei mehreren erneuten Versuchen werden vom Blobtrigger durch Schreiben nicht verarbeitbarer Blobs in eine Warteschlange für das durch die Verbindung angegebene Speicherkonto behandelt.

² Die AzureWebJobsStorage-Verbindung wird intern für Blobs und Warteschlangen verwendet, die den Trigger aktivieren. Wenn die Verwendung einer identitätsbasierten Verbindung konfiguriert ist, sind zusätzliche Berechtigungen erforderlich, die über die Standardanforderung hinausgehen. Die erforderlichen Berechtigungen werden durch die Rollen Besitzer von Storage-Blobdaten, Mitwirkender für Storage-Warteschlangendaten und Speicherkontomitwirkender abgedeckt. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit dem Hostspeicher mit einer Identität.

Blobnamensmuster

Ein Blobnamensmuster kann in der Eigenschaft path (in path) oder im Konstruktor des Attributs BlobTrigger angegeben werden. Das Namensmuster kann ein Filter oder Bindungsausdruck sein. Die folgenden Abschnitte enthalten einige Beispiele.

Abrufen von Dateiname und Erweiterung

Das folgende Beispiel zeigt, wie Sie den Blobdateinamen und die Erweiterung separat binden:

"path": "input/{blobname}.{blobextension}",

Wenn das Blob original-Blob1.txt heißt, lauten die Werte der Variablen blobname und blobextension im Funktionscode original-Blob1 und txt.

Filtern nach Blobname

Im folgenden Beispiel wird der Trigger nur für Blobs im Container input ausgelöst, deren Name mit „original-“ beginnt:

"path": "input/original-{name}",

Wenn der Blobname original-Blob1.txt lautet, hat die Variable name im Funktionscode den Wert Blob1.txt.

Filtern nach Dateityp

Im folgenden Beispiel wird der Trigger nur für PNG-Dateien ausgelöst:

"path": "samples/{name}.png",

Filtern nach geschweiften Klammern in Dateinamen

Wenn in Dateinamen nach geschweiften Klammern gesucht werden soll, müssen doppelte Klammern verwendet werden. Im folgenden Beispiel wird nach Blobs gefiltert, deren Name geschweifte Klammern enthält:

"path": "images/{{20140101}}-{name}",

Wenn der Blobname {20140101}-soundfile.mp3 lautet, erhält die Variable name im Funktionscode den Wert soundfile.mp3.

Abfrage und Latenz

Der Abruf funktioniert als Kombination aus dem Überprüfen von Protokollen und dem Ausführen regelmäßiger Containerscans. Blobs werden jeweils in Gruppen von 10.000 gescannt, wobei zwischen den Intervallen ein Fortsetzungstoken verwendet wird. Wenn Ihre Funktions-App im Verbrauchsplan enthalten ist, kann es möglicherweise bis zu 10 Minuten dauern, bis neue Blobs verarbeitet werden, nachdem eine Funktionen-App in den Leerlauf gewechselt ist.

Wenn Sie eine schnellere oder zuverlässigere Blob-Verarbeitung benötigen, sollten Sie das Hosting wechseln, um einen App Service-Plan mit aktivierter Always On-Funktion zu verwenden, was zu höheren Kosten führen kann. Sie können auch einen anderen Trigger als den klassischen Abruf-BLOB-Trigger verwenden. Weitere Informationen und einen Vergleich der verschiedenen Triggeroptionen für Blob-Speichercontainer finden Sie unter Trigger für einen BLOB-Container.

BLOB-Zugänge

Die Azure Functions-Runtime stellt sicher, dass Blobtriggerfunktionen für ein neues oder aktualisiertes Blob nicht mehrmals aufgerufen werden. Zu diesem Zweck wird mittels Verwaltung der Blobbelege ermittelt, ob eine bestimmte Blobversion verarbeitet wurde.

Azure Functions speichert Blobbelege in einem Container mit dem Namen azure-webjobs-hosts im Azure Storage-Konto für Ihre Funktions-App (per App-Einstellung AzureWebJobsStorage definiert). Ein Blobbeleg enthält die folgenden Informationen:

• Die ausgelöste Funktion (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>, z. B. MyFunctionApp.Functions.CopyBlob)
• Containername
• Der Blobtyp (BlockBlob oder PageBlob)
• Blobname
• Das ETag (ein Blobversionsbezeichner, z. B. 0x8D1DC6E70A277EF)

Um eine erneute Verarbeitung eines Blobs zu erzwingen, können Sie den Blobbeleg für dieses Blob manuell aus dem Container azure-webjobs-hosts löschen. Auch wenn eine erneute Verarbeitung eventuell nicht sofort ausgeführt wird, erfolgt sie doch garantiert zu einem späteren Zeitpunkt. Für eine sofortige erneute Verarbeitung kann das ScanInfo-Blob in azure-webjobs-hosts/blobscaninfo aktualisiert werden. Alle Blobs mit einem Zeitstempel der letzten Änderung, der nach der LatestScan-Eigenschaft liegt, werden erneut überprüft.

Nicht verarbeitbare Blobs

Wenn bei Ausführung einer Blobtriggerfunktion für ein bestimmtes Blob ein Fehler auftritt, versucht Azure Functions standardmäßig bis zu fünfmal, diese Funktion auszuführen.

Wenn bei allen fünf Versuchen Fehler auftreten, fügt Azure Functions der Storage-Warteschlange webjobs-blobtrigger-poison eine Nachricht hinzu. Die maximale Anzahl von Wiederholungen ist konfigurierbar. Für die Verarbeitung nicht verarbeitbarer Blobs und der dazugehörigen Nachrichtenwarteschlange wird die gleiche MaxDequeueCount-Einstellung verwendet. Die Warteschlangennachricht für nicht verarbeitbare Blobs ist ein JSON-Objekt, das die folgenden Eigenschaften enthält:

• FunctionId (im Format <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob oder PageBlob)
• ContainerName
• BlobName
• ETag (ein Blobversionsbezeichner, z. B. 0x8D1DC6E70A277EF)

Arbeitsspeicherauslastung und Parallelität

Die Speicherauslastung kann weiter beeinträchtigt werden, wenn mehrere Funktionsinstanzen blob-Daten gleichzeitig verarbeiten. Wenn Arbeitsspeicherprobleme mit einem BLOB-Trigger auftreten, sollten Sie die Anzahl der zulässigen gleichzeitigen Ausführungen verringern. Die Reduzierung der Parallelität kann natürlich die Nebenwirkung haben, indem der Backlog von Blobs erhöht wird, die auf die Verarbeitung warten. Die Speicherbeschränkungen Ihrer Funktions-App hängen vom Plan ab. Weitere Informationen finden Sie unter Diensteinschränkungen.

Die Art und Weise, wie Sie die Anzahl der gleichzeitigen Ausführungen steuern können, hängt von der Version der verwendeten Speichererweiterung ab.

Grenzwerte gelten separat für jede Funktion, die einen Blobtrigger verwendet.

Eigenschaften von „host.json“

Die Datei host.json enthält Einstellungen, mit denen das Verhalten des Blobtriggers gesteuert werden kann. Informationen zu verfügbaren Einstellungen finden Sie im Abschnitt Einstellungen für „host.json“.

Nächste Schritte

• Lesen von Blob Storage-Daten, wenn eine Funktion ausgeführt wird
• Schreiben von Blob Storage-Daten aus einer Funktion