Déclencheur Stockage Blob Azure pour Azure Functions

Le déclencheur de stockage Blob démarre une fonction lors de la détection d’un objet blob nouveau ou mis à jour. Le contenu du blob est fourni comme entrée de la fonction.

Pour plus d’informations sur les différences entre les deux implémentations du déclencheur de stockage d’objets blob, ainsi que d’autres options de déclenchement, consultez Utilisation des objets blob.

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.

Exemple

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( //...
{
    ...
}

Pour obtenir des exemples complets, consultez la section Exemple.

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

Utilisation

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

Connexions

La propriété connection est une référence à la configuration de l’environnement qui spécifie la façon dont l’application doit se connecter aux blobs Azure. Elle peut spécifier :

• Le nom d’un paramètre d’application contenant une chaîne de connexion
• Le nom d’un préfixe partagé pour plusieurs paramètres d’application, définissant ensemble une connexion basée sur l’identité.

Si la valeur configurée est à la fois une correspondance exacte pour un paramètre unique et une correspondance de préfixe pour d’autres paramètres, la correspondance exacte est utilisée.

Chaîne de connexion

Pour obtenir une chaîne de connexion, suivez les étapes indiquées à la section Gérer les clés d’accès au compte de stockage. La chaîne de connexion doit être destinée à un compte de stockage à usage général, et non pas à un compte Stockage Blob.

Cette chaîne de connexion doit être stockée dans un paramètre d’application dont le nom correspond à la valeur spécifiée par la propriété connection de la configuration de liaison.

Si le nom du paramètre d’application commence par « AzureWebJobs », vous ne pouvez spécifier que le reste du nom ici. Par exemple, si vous définissez connection sur « MyStorage », le runtime Functions recherche un paramètre d’application nommé « AzureWebJobsMyStorage ». Si vous laissez connection vide, le runtime Functions utilise la chaîne de connexion de stockage par défaut dans le paramètre d’application nommé AzureWebJobsStorage.

Connexions basées sur l’identité

Si vous utilisez la version 5.x ou ultérieure de l’extension (bundle 3.x ou version ultérieure pour les piles linguistiques non-.NET), au lieu d’utiliser un chaîne de connexion avec un secret, vous pouvez faire en sorte que l’application utilise une identité Microsoft Entra. Pour utiliser une identité, vous devez définir les paramètres sous un préfixe commun qui correspond à la propriété connection dans le déclencheur et la configuration de liaison.

Si vous définissez connection sur « AzureWebJobsStorage », consultez la section Connexion au stockage hôte avec une identité. Pour toutes les autres connexions, l’extension nécessite les propriétés suivantes :

¹ <CONNECTION_NAME_PREFIX>__blobServiceUri peut être utilisé comme alias. Si la configuration de la connexion sera utilisée par un déclencheur d’objet Blob, blobServiceUri doit également être accompagné de queueServiceUri. Voir ci-dessous.

La forme serviceUri ne peut pas être utilisée lorsque la configuration globale de la connexion doit être utilisée sur des objets blob, des files d’attente et/ou des tables. L’URI ne peut désigner que le service d’objets blob. Vous pouvez également fournir un URI spécifique pour chaque service, en autorisant l’utilisation d’une connexion unique. Si les deux versions sont fournies, la forme à plusieurs services est utilisée. Pour configurer la connexion pour plusieurs services, au lieu de <CONNECTION_NAME_PREFIX>__serviceUri, définissez :

² Le déclencheur d’objet Blob gère les échecs entre plusieurs tentatives en écrivant des objets Blob incohérents dans une file d’attente. Dans la forme serviceUri, la connexion AzureWebJobsStorage est utilisée. Toutefois, lorsque vous spécifiez blobServiceUri, un URI de service de file d’attente doit également être fourni avec queueServiceUri. Il est recommandé d’utiliser le service à partir du même compte de stockage que le service d’objets blob. Vous devez également vous assurer que le déclencheur peut lire et écrire des messages dans le service de file d’attente configuré en affectant un rôle comme Contributeur aux données en file d’attente du stockage.

D’autres propriétés peuvent être définies pour personnaliser la connexion. Consultez Propriétés communes pour les connexions basées sur l’identité.

Quand elles sont hébergées dans le service Azure Functions, les connexions basées sur une identité utilisent une identité managée. L’identité attribuée par le système est utilisée par défaut, bien qu’une identité attribuée par l’utilisateur puisse être spécifiée avec les propriétés credential et clientID. Notez que la configuration d’une identité affectée par l’utilisateur avec un ID de ressource n’est pas prise en charge. Lors d’une exécution dans d’autres contextes, tels que le développement local, votre identité de développeur est utilisée à la place, même si cela peut être personnalisé. Consultez Développement local avec connexions basées sur une identité.

Accorder l’autorisation à l’identité

Quelle que soit l’identité utilisée, elle doit avoir les autorisations nécessaires pour effectuer les actions prévues. Pour la plupart des services Azure, cela signifie que vous devez attribuer un rôle dans Azure RBAC en utilisant des rôles intégrés ou personnalisés qui fournissent ces autorisations.

Vous devez créer une attribution de rôle qui donne accès à votre conteneur de blobs au moment de l’exécution. Les rôles de gestion comme Propriétaire ne sont pas suffisants. Le tableau suivant présente les rôles intégrés qui sont recommandés lors de l’utilisation de l’extension Stockage Blob dans le cadre d’un fonctionnement normal. Il est possible que votre application nécessite des autorisations supplémentaires en fonction du code que vous écrivez.

¹ Le déclencheur Blob gère l’échec sur plusieurs tentatives en écrivant des blobs incohérents dans une file d’attente sur le compte de stockage spécifié par la connexion.

² La connexion AzureWebJobsStorage est utilisée en interne pour les blobs et les files d’attente qui activent le déclencheur. Si elle est configurée de manière à utiliser une connexion basée sur une identité, elle a besoin d’autorisations supplémentaires au-delà de la spécification par défaut. Ces autorisations requises sont couvertes par les rôles Propriétaire des données Blob du stockage, Contributeur aux données en file d’attente du stockage et Contributeur de compte de stockage. Pour en savoir plus, consultez Connexion au stockage hôte avec une identité.

Modèles de nom de blob

Vous pouvez spécifier un modèle de nom d’objet blob dans la propriété path du fichier path ou dans le constructeur d’attribut BlobTrigger. Le modèle de nom peut être une expression de filtre ou de liaison. Les sections suivantes fournissent des exemples.

Obtenir l’extension et le nom de fichier

L’exemple suivant montre comment se lier séparément à l’extension et au nom de fichier de l’objet blob :

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

Si l’objet blob est nommé original-Blob1.txt, les valeurs des variables blobname et blobextension dans le code de la fonction sont original-Blob1 et txt.

Filtrer sur le nom de l’objet blob

L’exemple suivant déclenche uniquement sur les objets blob du conteneur input qui commencent par la chaîne « original- » :

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

Si le nom de l’objet blob est original-Blob1.txt, la valeur de la variable name dans le code de la fonction est Blob1.txt.

Filtrer sur le type de fichier

L’exemple suivant ne déclenche que sur des fichiers .png :

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

Filtrer sur les accolades dans les noms de fichiers

Pour rechercher les accolades dans les noms de fichiers, utilisez une séquence d’échappement sous la forme de deux accolades. L’exemple suivant filtre en recherchant les objets blob qui contiennent des accolades dans le nom :

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

Si l’objet blob est nommé {20140101}-soundfile.mp3, la valeur de la variable name dans le code de la fonction est soundfile.mp3.

Interrogation et latence

L’interrogation fonctionne de façon hybride entre l’inspection des journaux et l’exécution d’analyses régulières des conteneurs. Les objets blob sont analysés dans des groupes de 10 000 à la fois avec un jeton de continuation utilisé entre les intervalles. Si votre application de fonction est dans le plan Consommation, il peut y avoir jusqu’à 10 minutes de délai dans le traitement des nouveaux objets blob si une application de fonction est devenue inactive.

Si vous avez besoin d’un traitement d’objets blob plus rapide ou plus fiable, vous devez envisager de changer votre hébergement pour utiliser un plan App Service avec Always On activé, ce qui peut entraîner une augmentation des coûts. Vous pouvez également envisager d’utiliser un déclencheur autre que le déclencheur d’objet blob d’interrogation classique. Pour plus d’informations et une comparaison des différentes options de déclenchement pour les conteneurs de stockage d’objets blob, consultez Déclencheur sur un conteneur d’objets blob.

Reçus d’objets blob

Le runtime Azure Functions vérifie qu’aucune fonction de déclencheur d’objet blob n’est appelée plusieurs fois pour un même objet blob, nouveau ou mis à jour. Pour déterminer si la version d’un objet blob donné a été traitée, il gère des reçus d’objet blob.

Azure Functions stocke les reçus d’objet blob dans un conteneur appelé azure-webjobs-hosts dans le compte de stockage Azure de votre application de fonction (définie par le paramètre d’application AzureWebJobsStorage). Un reçu d’objet blob contient les informations suivantes :

• Fonction déclenchée (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>, par exemple : MyFunctionApp.Functions.CopyBlob)
• Nom du conteneur
• Type de blob (BlockBlob ou PageBlob)
• Nom de l’objet blob
• Étiquette d’entité (identificateur de la version du BLOB, par exemple : 0x8D1DC6E70A277EF)

Pour forcer le retraitement d’un objet blob, supprimez manuellement le reçu de l’objet blob du conteneur azure-webjobs-hosts. Si le retraitement n’a pas lieu immédiatement, il se produira ultérieurement. Pour effectuer un retraitement immédiatement, le blob ScanInfo dans azure-webjobs-hosts/blobscaninfo peut être mis à jour. Les blobs ayant un timestamp de dernière modification après la propriété LatestScan sont à nouveau analysés.

Blobs incohérents

En cas d’échec d’une fonction de déclencheur pour un blob donné, Azure Functions réessaie cette fonction jusqu’à cinq fois par défaut.

Si les 5 tentatives échouent, Azure Functions ajoute un message à une file d’attente de stockage nommée webjobs-blobtrigger-poison. Vous pouvez configurer le nombre maximal de tentatives. Le paramètre MaxDequeueCount est utilisé à la fois pour la gestion des objets blob incohérents et pour l’administration des messages de la file d’attente de messages incohérents. Le message en file d’attente associé aux objets blob incohérents correspond à un objet JSON, qui contient les propriétés suivantes :

• FunctionId (au format <FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>)
• BlobType (BlockBlob ou PageBlob)
• ContainerName
• BlobName
• ETag (identificateur de la version du BLOB, par exemple : 0x8D1DC6E70A277EF)

Utilisation de la mémoire et concurrence

L’utilisation de la mémoire peut être davantage affectée lorsque plusieurs instances de fonction traitent simultanément les données d’objet blob. Si vous rencontrez des problèmes de mémoire à l’aide d’un déclencheur d’objet blob, envisagez de réduire le nombre d’exécutions simultanées autorisées. Bien sûr, la réduction de l’accès concurrentiel peut avoir l’effet secondaire de l’augmentation du backlog des objets blob en attente de traitement. Les limites de mémoire de votre application de fonction dépendent du plan. Pour plus d’informations, consultez Limites du Service.

La façon dont vous pouvez contrôler le nombre d’exécutions simultanées dépend de la version de l’extension de stockage que vous utilisez.

Les limites s’appliquent séparément à chaque fonction qui utilise un déclencheur d’objet blob.

Propriétés host.json

Le fichier host.json contient les paramètres qui contrôlent le comportement du déclencheur de blob. Consultez la section Paramètres host.json pour plus d’informations concernant les paramètres disponibles.

Étapes suivantes

• Lire des données de stockage de blobs lors de l’exécution d’une fonction
• Écrire des données de stockage d’objets blob à partir d’une fonction