Déclencheur Stockage Blob Azure pour Azure FunctionsAzure Blob storage trigger for 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.The Blob storage trigger starts a function when a new or updated blob is detected. Le contenu du blob est fourni comme entrée de la fonction.The blob contents are provided as input to the function.

Le déclencheur Stockage Blob Azure nécessite un compte de stockage universel.The Azure Blob storage trigger require a general-purpose storage account. Pour utiliser un compte dédié aux blobs ou si votre application a des besoins spécifiques, passez en revue les alternatives à l’utilisation de ce déclencheur.To use a blob-only account, or if your application has specialized needs, review the alternatives to using this trigger.

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.For information on setup and configuration details, see the overview.

Autres solutionsAlternatives

Déclencheur Event GridEvent Grid trigger

Le déclencheur Event Grid possède également une prise en charge intégrée des événements blobs.The Event Grid trigger also has built-in support for blob events. Utilisez Event Grid au lieu du déclencheur de stockage Blob pour les scénarios suivants :Use Event Grid instead of the Blob storage trigger for the following scenarios:

  • Comptes de stockage Blob uniquement : Les comptes de stockage Blob uniquement sont pris en charge pour les liaisons d’entrée et de sortie, mais pas pour les déclencheurs blob.Blob-only storage accounts: Blob-only storage accounts are supported for blob input and output bindings but not for blob triggers.

  • Scalabilité élevée : La scalabilité élevée peut être définie comme des conteneurs qui contiennent plus de 100 000 objets blob ou des comptes de stockage avec plus de 100 mises à jour d’objets blob par seconde.High-scale: High scale can be loosely defined as containers that have more than 100,000 blobs in them or storage accounts that have more than 100 blob updates per second.

  • Minimisation de la latence : 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.Minimizing latency: If your function app is on the Consumption plan, there can be up to a 10-minute delay in processing new blobs if a function app has gone idle. Pour éviter toute latence, vous pouvez passer à un plan App Service dans lequel est activé AlwaysOn.To avoid this latency, you can switch to an App Service plan with Always On enabled. Vous pouvez également utiliser un déclencheur Event Grid avec votre compte de stockage Blob.You can also use an Event Grid trigger with your Blob storage account. Pour obtenir un exemple, consultez le tutoriel Event Grid.For an example, see the Event Grid tutorial.

Pour obtenir un exemple Azure Event Grid, consultez le tutoriel Redimensionnement d’image avec Event Grid.See the Image resize with Event Grid tutorial of an Event Grid example.

Déclencheur de stockage de file d’attenteQueue storage trigger

Une autre approche du traitement des blobs consiste à écrire des messages de file d’attente qui correspondent à des blobs créés ou modifiés, puis à utiliser un déclencheur Stockage File d’attente pour commencer le traitement.Another approach to processing blobs is to write queue messages that correspond to blobs being created or modified and then use a Queue storage trigger to begin processing.

ExempleExample

L’exemple suivant montre une fonction C# qui écrit une entrée de journal lorsqu’un objet blob est ajouté ou mis à jour dans le conteneur samples-workitems.The following example shows a C# function that writes a log when a blob is added or updated in the samples-workitems container.

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

La chaîne {name} dans le chemin d’accès du déclencheur d’objet blob samples-workitems/{name} crée une expression de liaison que vous pouvez utiliser dans le code de fonction pour accéder au nom de fichier de l’objet blob déclencheur.The string {name} in the blob trigger path samples-workitems/{name} creates a binding expression that you can use in function code to access the file name of the triggering blob. Pour plus d’informations, consultez la section Modèles de nom d’objet blob dans la suite de cet article.For more information, see Blob name patterns later in this article.

Pour plus d’informations sur l’attribut BlobTrigger, consultez les attributs et les annotations.For more information about the BlobTrigger attribute, see attributes and annotations.

Attributs et annotationsAttributes and annotations

Dans les bibliothèques de classes C#, utilisez les attributs suivants pour configurer un déclencheur d’objet blob :In C# class libraries, use the following attributes to configure a blob trigger:

  • BlobTriggerAttributeBlobTriggerAttribute

    Le constructeur de l’attribut prend une chaîne de chemin qui indique le conteneur à surveiller et éventuellement un modèle de nom d’objet blob.The attribute's constructor takes a path string that indicates the container to watch and optionally a blob name pattern. Voici un exemple :Here's an example:

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

    Vous pouvez définir la propriété Connection pour spécifier le compte de stockage à utiliser, comme indiqué dans l’exemple suivant :You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    Pour obtenir un exemple complet, consultez Exemple de déclencheur.For a complete example, see Trigger example.

  • StorageAccountAttributeStorageAccountAttribute

    Fournit une autre manière de spécifier le compte de stockage à utiliser.Provides another way to specify the storage account to use. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion de stockage.The constructor takes the name of an app setting that contains a storage connection string. L’attribut peut être appliqué au niveau du paramètre, de la méthode ou de la classe.The attribute can be applied at the parameter, method, or class level. L’exemple suivant montre le niveau de la classe et celui de la méthode :The following example shows class level and method level:

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

Le compte de stockage à utiliser est déterminé dans l’ordre suivant :The storage account to use is determined in the following order:

  • La propriété Connection de l’attribut BlobTrigger.The BlobTrigger attribute's Connection property.
  • L’attribut StorageAccount appliqué au même paramètre que l’attribut BlobTrigger.The StorageAccount attribute applied to the same parameter as the BlobTrigger attribute.
  • L’attribut StorageAccount appliqué à la fonction.The StorageAccount attribute applied to the function.
  • L’attribut StorageAccount appliqué à la classe.The StorageAccount attribute applied to the class.
  • Le compte de stockage par défaut pour l’application de fonction (paramètre d’application « AzureWebJobsStorage »).The default storage account for the function app ("AzureWebJobsStorage" app setting).

ConfigurationConfiguration

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json et l’attribut BlobTrigger.The following table explains the binding configuration properties that you set in the function.json file and the BlobTrigger attribute.

Propriété function.jsonfunction.json property Propriété d’attributAttribute property DescriptionDescription
typetype n/an/a Cette propriété doit être définie sur blobTrigger.Must be set to blobTrigger. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/an/a Cette propriété doit être définie sur in.Must be set to in. Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.This property is set automatically when you create the trigger in the Azure portal. Les exceptions sont notées à la section utilisation.Exceptions are noted in the usage section.
namename n/an/a Nom de la variable qui représente l’objet blob dans le code de la fonction.The name of the variable that represents the blob in function code.
pathpath BlobPathBlobPath Conteneur à superviser.The container to monitor. Peut être un modèle de nom d’objet blob.May be a blob name pattern.
connectionconnection ConnectionConnection Nom d’un paramètre d’application comportant la chaîne de connexion de stockage à utiliser pour cette liaison.The name of an app setting that contains the Storage connection string to use for this binding. Si le nom du paramètre d’application commence par « AzureWebJobs », vous ne pouvez spécifier que le reste du nom ici.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Par exemple, si vous définissez connection sur « MyStorage », le runtime Functions recherche un paramètre d’application qui est nommé « AzureWebJobsMyStorage ».For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "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.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

La chaîne de connexion doit être destinée à un compte de stockage à usage général, et non pas à un compte Stockage Blob.The connection string must be for a general-purpose storage account, not a Blob storage account.

Quand vous développez localement, les paramètres d’application vont dans le fichier local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

UsageUsage

Vous pouvez utiliser les types de paramètres suivants pour l’objet blob déclencheur :You can use the following parameter types for the triggering blob:

  • Stream
  • TextReader
  • string
  • Byte[]
  • Un objet POCO sérialisable au format JSONA POCO serializable as JSON
  • ICloudBlob1ICloudBlob1
  • CloudBlockBlob1CloudBlockBlob1
  • CloudPageBlob1CloudPageBlob1
  • CloudAppendBlob1CloudAppendBlob1

1 requiert la liaison « inout » direction dans function.json ou FileAccess.ReadWrite dans une bibliothèque de classes C#.1 Requires "inout" binding direction in function.json or FileAccess.ReadWrite in a C# class library.

Si vous essayez de lier à un des types de SDK Stockage et obtenez un message d’erreur, vérifiez que vous avez une référence à la bonne version du SDK Stockage.If you try to bind to one of the Storage SDK types and get an error message, make sure that you have a reference to the correct Storage SDK version.

La liaison avec string, Byte[] ou POCO est recommandée uniquement si la taille de l’objet blob est petite, car tout le contenu de l’objet blob est chargé en mémoire.Binding to string, Byte[], or POCO is only recommended if the blob size is small, as the entire blob contents are loaded into memory. En général, il est préférable d’utiliser un type Stream ou CloudBlockBlob.Generally, it is preferable to use a Stream or CloudBlockBlob type. Pour plus d’informations, consultez Concurrence et utilisation de la mémoire plus loin dans cet article.For more information, see Concurrency and memory usage later in this article.

Modèles de nom de blobBlob name patterns

Vous pouvez spécifier un modèle de nom d’objet blob dans la propriété path du fichier function.json ou dans le constructeur d’attribut BlobTrigger.You can specify a blob name pattern in the path property in function.json or in the BlobTrigger attribute constructor. Le modèle de nom peut être une expression de filtre ou de liaison.The name pattern can be a filter or binding expression. Les sections suivantes fournissent des exemples.The following sections provide examples.

Obtenir l’extension et le nom de fichierGet file name and extension

L’exemple suivant montre comment se lier séparément à l’extension et au nom de fichier de l’objet blob :The following example shows how to bind to the blob file name and extension separately:

"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.If the blob is named original-Blob1.txt, the values of the blobname and blobextension variables in function code are original-Blob1 and txt.

Filtrer sur le nom de l’objet blobFilter on blob name

L’exemple suivant déclenche uniquement sur les objets blob du conteneur input qui commencent par la chaîne « original- » :The following example triggers only on blobs in the input container that start with the string "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.If the blob name is original-Blob1.txt, the value of the name variable in function code is Blob1.

Filtrer sur le type de fichierFilter on file type

L’exemple suivant ne déclenche que sur des fichiers .png :The following example triggers only on .png files:

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

Filtrer sur les accolades dans les noms de fichiersFilter on curly braces in file names

Pour rechercher les accolades dans les noms de fichiers, utilisez une séquence d’échappement sous la forme de deux accolades.To look for curly braces in file names, escape the braces by using two braces. L’exemple suivant filtre en recherchant les objets blob qui contiennent des accolades dans le nom :The following example filters for blobs that have curly braces in the name:

"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.If the blob is named {20140101}-soundfile.mp3, the name variable value in the function code is soundfile.mp3.

MétadonnéesMetadata

Le déclencheur d’objet blob fournit plusieurs propriétés de métadonnées.The blob trigger provides several metadata properties. Ces propriétés peuvent être utilisées dans les expressions de liaison dans d’autres liaisons ou en tant que paramètres dans votre code.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Ces valeurs ont la même sémantique que le type CloudBlob.These values have the same semantics as the CloudBlob type.

PropriétéProperty TypeType DescriptionDescription
BlobTrigger string Chemin de l’objet blob déclencheur.The path to the triggering blob.
Uri System.Uri URI de l’objet blob pour l’emplacement principal.The blob's URI for the primary location.
Properties BlobPropertiesBlobProperties Propriétés système de l’objet blob.The blob's system properties.
Metadata IDictionary<string,string> Métadonnées définies par l’utilisateur pour l’objet blob.The user-defined metadata for the blob.

Par exemple, les exemples JavaScript et Script C# suivants enregistrent le chemin d’accès à l’objet blob déclencheur, notamment le conteneur :For example, the following C# script and JavaScript examples log the path to the triggering blob, including the container:

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

Reçus d’objets blobBlob receipts

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.The Azure Functions runtime ensures that no blob trigger function gets called more than once for the same new or updated blob. Pour déterminer si la version d’un objet blob donné a été traitée, il gère des reçus d’objet blob.To determine if a given blob version has been processed, it maintains blob receipts.

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).Azure Functions stores blob receipts in a container named azure-webjobs-hosts in the Azure storage account for your function app (defined by the app setting AzureWebJobsStorage). Un reçu d’objet blob contient les informations suivantes :A blob receipt has the following information:

  • Fonction déclenchée (« <nom de l’application de fonction> .Functions. <nom de la fonction>  », par exemple : « MyFunctionApp.Functions.CopyBlob »)The triggered function ("<function app name>.Functions.<function name>", for example: "MyFunctionApp.Functions.CopyBlob")
  • Nom du conteneurThe container name
  • Type d’objet blob (« BlockBlob » ou « PageBlob »)The blob type ("BlockBlob" or "PageBlob")
  • Nom de l’objet blobThe blob name
  • Étiquette d’entité (identificateur de version de l’objet blob, par exemple : « 0x8D1DC6E70A277EF »)The ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Pour forcer le retraitement d’un objet blob, supprimez manuellement le reçu de l’objet blob du conteneur azure-webjobs-hosts.To force reprocessing of a blob, delete the blob receipt for that blob from the azure-webjobs-hosts container manually. Si le retraitement n’a pas lieu immédiatement, il se produira ultérieurement.While reprocessing might not occur immediately, it's guaranteed to occur at a later point in time.

Blobs incohérentsPoison blobs

En cas d’échec d’une fonction de déclencheur d’objet blob, Azure Functions réessaie cette fonction jusqu’à 5 fois par défaut.When a blob trigger function fails for a given blob, Azure Functions retries that function a total of 5 times by default.

Si les 5 tentatives échouent, Azure Functions ajoute un message à une file d’attente de stockage nommée webjobs-blobtrigger-poison.If all 5 tries fail, Azure Functions adds a message to a Storage queue named webjobs-blobtrigger-poison. Vous pouvez configurer le nombre maximal de tentatives.The maximum number of retries is configurable. 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.The same MaxDequeueCount setting is used for poison blob handling and poison queue message handling. Le message en file d’attente associé aux objets blob incohérents correspond à un objet JSON, qui contient les propriétés suivantes :The queue message for poison blobs is a JSON object that contains the following properties:

  • FunctionId (au format <nom de l’application de fonctions> .Functions. <nom de la fonction> )FunctionId (in the format <function app name>.Functions.<function name>)
  • BlobType (« BlockBlob » ou « PageBlob »)BlobType ("BlockBlob" or "PageBlob")
  • ContainerNameContainerName
  • BlobNameBlobName
  • Étiquette d’entité (identificateur de version de l’objet blob, par exemple : « 0x8D1DC6E70A277EF »)ETag (a blob version identifier, for example: "0x8D1DC6E70A277EF")

Concurrence et utilisation de la mémoireConcurrency and memory usage

Le déclencheur de blob utilise une file d’attente en interne. Le nombre maximal d’appels de fonction concurrents est par conséquent contrôlé par la configuration des files d’attente dans host.json.The blob trigger uses a queue internally, so the maximum number of concurrent function invocations is controlled by the queues configuration in host.json. Les paramètres par défaut limitent la concurrence à 24 appels.The default settings limit concurrency to 24 invocations. Cette limite s’applique séparément à chaque fonction qui utilise un déclencheur de blob.This limit applies separately to each function that uses a blob trigger.

Le plan Consommation limite une application de fonction sur une machine virtuelle à 1,5 Go de mémoire.The Consumption plan limits a function app on one virtual machine (VM) to 1.5 GB of memory. La mémoire est utilisée par chaque instance de la fonction qui s’exécutent simultanément et par le runtime de fonctions lui-même.Memory is used by each concurrently executing function instance and by the Functions runtime itself. Si une fonction déclenchée par blob charge le blob entier en mémoire, la mémoire maximale utilisée par cette fonction uniquement pour les blobs est 24 * la taille maximale du blob.If a blob-triggered function loads the entire blob into memory, the maximum memory used by that function just for blobs is 24 * maximum blob size. Par exemple, une application de fonction avec trois fonctions déclenchées par blob et les paramètres par défaut aurait une concurrence par machine virtuelle maximale de 3 * 24 = 72 appels de fonction.For example, a function app with three blob-triggered functions and the default settings would have a maximum per-VM concurrency of 3*24 = 72 function invocations.

Les fonctions JavaScript et Java chargent l’objet blob entier en mémoire et les fonctions C# le font si vous faites la liaison avec string, Byte[] ou POCO.JavaScript and Java functions load the entire blob into memory, and C# functions do that if you bind to string, Byte[], or POCO.

InterrogationPolling

L’interrogation fonctionne de façon hybride entre l’inspection des journaux et l’exécution d’analyses régulières des conteneurs.Polling works as a hybrid between inspecting logs and running periodic container scans. Les objets blob sont analysés dans des groupes de 10 000 à la fois avec un jeton de continuation utilisé entre les intervalles.Blobs are scanned in groups of 10,000 at a time with a continuation token used between intervals.

Avertissement

En outre, les journaux d’activité de stockage sont créés selon le principe du meilleur effort.In addition, storage logs are created on a "best effort" basis. Il n’existe aucune garantie que tous les événements sont capturés.There's no guarantee that all events are captured. Dans certaines conditions, des journaux d’activité peuvent être omis.Under some conditions, logs may be missed.

Si vous avez besoin de traitement d’objets blob plus rapide ou plus fiable, envisagez de créer un message de file d’attente quand vous créez l’objet blob.If you require faster or more reliable blob processing, consider creating a queue message when you create the blob. Ensuite, utilisez un déclencheur de file d’attente plutôt qu’un déclencheur d’objet blob pour traiter l’objet blob.Then use a queue trigger instead of a blob trigger to process the blob. Une autre option consiste à utiliser Event Grid ; consultez le didacticiel Automatiser le redimensionnement des images téléchargées à l’aide d’Event Grid.Another option is to use Event Grid; see the tutorial Automate resizing uploaded images using Event Grid.

Étapes suivantesNext steps