Partage via

Liaison d’entrée Stockage Blob Azure pour Azure Functions

  • Article

La liaison d’entrée vous permet de lire des données de stockage Blob en tant qu’entrée d’une fonction Azure.

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

Important

Cet article utilise des onglets pour prendre en charge plusieurs versions du modèle de programmation Node.js. Le modèle v4 est en disponibilité générale. Il est conçu pour offrir une expérience plus flexible et intuitive aux développeurs JavaScript et TypeScript. Pour plus d’informations sur le fonctionnement du modèle v4, reportez-vous au guide du développeur Azure Functions Node.js. Pour plus d’informations sur les différences entre v3 et v4, consultez le guide de migration.

Azure Functions prend en charge deux modèles de programmation pour Python. La façon dont vous définissez vos liaisons dépend du modèle de programmation choisi.

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

Cet article prend en compte les deux modèles de programmation.

Exemple

Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :

  • Modèle worker isolé : fonction C# compilée exécutée dans un processus worker isolé du runtime. Le processus Worker isolé est requis pour prendre en charge les fonctions C# exécutées sur les versions LTS et non-LTS de .NET et de .NET Framework. Les extensions pour les fonctions de processus de travail isolés utilisent des espaces de noms Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modèle In-process : fonction C# compilée exécutée dans le même processus que le runtime Functions. Dans une variation de ce modèle, Functions peut être exécuté à l’aide de scripts C#, principalement pris en charge pour la modification du portail C#. Les extensions pour les fonctions in-process utilisent des espaces de noms Microsoft.Azure.WebJobs.Extensions.*.

Important

La prise en charge du modèle in-process prendra fin le 10 novembre 2026. Pour continuer à bénéficier d’une prise en charge complète, nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé.

L’exemple suivant est une fonction C# qui s’exécute dans un processus worker isolé et utilise un déclencheur Blob avec des liaisons blob en entrée et en sortie. La fonction est déclenchée par la création d’un objet blob dans le conteneur test-samples-trigger. Elle lit un fichier texte à partir du conteneur test-samples-input et crée un nouveau fichier texte dans un conteneur de sortie en fonction du nom du fichier déclenché.

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

Cette section contient les exemples suivants :

Déclencheur HTTP, rechercher le nom de l’objet blob dans la chaîne de requête

L’exemple suivant montre une fonction Java qui utilise l’annotation HttpTrigger pour recevoir un paramètre qui contient le nom d’un fichier dans un conteneur de stockage d’objets blob. L’annotation BlobInput lit ensuite le fichier et transmet son contenu à la fonction en tant que 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();
  }

Déclencheur de file d’attente, recevoir le nom de l’objet blob à partir du message en file d’attente

L’exemple suivant montre une fonction Java qui utilise l’annotation QueueTrigger pour recevoir un message qui contient le nom d’un fichier dans un conteneur de stockage d’objets blob. L’annotation BlobInput lit ensuite le fichier et transmet son contenu à la fonction en tant que 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");
  }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation @BlobInput sur les paramètres dont la valeur proviendrait d’un objet blob. Vous pouvez utiliser cette annotation avec des types Java natifs, des objets POJO ou des valeurs Null à l’aide de Optional<T>.

L’exemple suivant montre une fonction TypeScript déclenchée par une file d’attente qui fait une copie d’un blob. La fonction est déclenchée par un message de file d’attente qui contient le nom de l’objet blob à copier. Le nouvel objet blob est nommé {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,
});

L’exemple suivant montre une fonction JavaScript déclenchée par une file d’attente qui fait une copie d’un blob. La fonction est déclenchée par un message de file d’attente qui contient le nom de l’objet blob à copier. Le nouvel objet blob est nommé {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);
    },
});

L’exemple suivant montre une liaison d’entrée de blob, définie dans le fichier function.json, qui rend les données blob entrantes disponibles pour la fonction PowerShell.

Voici la configuration JSON :

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

Voici le code de la fonction :

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

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

Cet exemple utilise des types sdk pour accéder directement à l’objet sous-jacent BlobClient fourni par la liaison d’entrée de stockage Blob :

import logging

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

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

Pour obtenir des exemples d’utilisation d’autres types de SDK, consultez les exemples et StorageStreamDownloader les ContainerClient exemples.

Pour en savoir plus, notamment sur l’activation des liaisons de type sdk dans votre projet, consultez les liaisons de type sdk.

Le code crée une copie d’un objet 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"

Attributs

Les bibliothèques C# in-process et de processus Worker isolé utilisent des attributs pour définir la fonction. Le script C# utilise à la place un fichier de configuration function.json comme décrit dans le guide de script C#.

Le processus worker isolé définit une liaison d’entrée à l’aide d’un BlobInputAttribute attribut, qui accepte les paramètres suivants :

Paramètre Description
BlobPath Chemin de l’objet blob.
Connection Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des objets blob Azure. Consultez Connexions.

Lorsque vous développez en local, ajoutez vos paramètres d’application dans le fichier local.settings.json de la collection Values.

Décorateurs

S’applique uniquement au modèle de programmation Python v2.

Pour les fonctions Python v2 définies à l’aide de décorateurs, les propriétés suivantes des décorateurs blob_input et blob_output définissent les déclencheurs Stockage Blob :

Propriété Description
arg_name Nom de la variable qui représente l’objet blob dans le code de la fonction.
path Chemin d’accès à l’objet blob Pour le décorateur blob_input, il s’agit de l’objet blob lu. Pour le décorateur blob_output, il s’agit de la sortie ou de la copie de l’objet blob d’entrée.
connection La chaîne de connexion de compte de stockage.
data_type Pour les langages dont le type est dynamique, spécifie le type de données sous-jacent. Les valeurs possibles sont string, binary ou stream. Pour plus d’informations, reportez-vous aux concepts des déclencheurs et des liaisons.

Pour les fonctions Python définies à l’aide de function.json, consultez la section Configuration.

Annotations

L'attribut @BlobInput vous permet d’accéder à l’objet blob qui a déclenché la fonction. Si vous utilisez un tableau d’octets avec l’attribut, définissez dataType sur binary. Reportez-vous à l’exemple d’entrée pour plus d'informations.

Configuration

S’applique uniquement au modèle de programmation Python v1.

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode input.storageBlob().

Propriété Description
path Chemin de l’objet blob.
connection Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des objets blob Azure. Consultez Connexions.

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété function.json Description
type Cette propriété doit être définie sur blob.
direction Cette propriété doit être définie sur in. Les exceptions sont notées à la section utilisation.
name Nom de la variable qui représente l’objet blob dans le code de la fonction.
path Chemin de l’objet blob.
connection Nom d’un paramètre d’application ou d’une collection de paramètres d’application qui spécifie la façon de se connecter à des objets blob Azure. Consultez Connexions.
dataType Pour les langages dont le type est dynamique, spécifie le type de données sous-jacent. Les valeurs possibles sont string, binary ou stream. Pour plus d’informations, reportez-vous aux concepts des déclencheurs et des liaisons.

Pour obtenir des exemples complets, consultez la section Exemple.

Utilisation

Les types de liaisons pris en charge par l’entrée d’objet blob dépendent de la version du package d’extension et de la modalité C# utilisée dans votre application de fonction.

Lorsque vous souhaitez que la fonction écrive dans un seul blob, la liaison de sortie blob peut se lier aux types suivants :

Type Description
string Contenu de l’objet blob en tant que chaîne. À utiliser quand le contenu de l’objet blob est un texte simple.
byte[] Octets du contenu de l’objet blob.
Types sérialisables JSON Quand un objet blob contient des données JSON, Functions tente de désérialiser les données JSON dans un type d’objet POCO (Plain-Old CLR Object).
Stream1 Flux d’entrée du contenu de l’objet blob.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 Client connecté à l’objet blob. Cet ensemble de types offre le meilleur contrôle pour le traitement de l’objet blob et peut être utilisé pour réécrire dans celui-ci, si la connexion dispose des autorisations suffisantes.

Lorsque vous souhaitez que la fonction traite plusieurs blobs à partir d’un conteneur, la liaison de sortie blob peut se lier aux types suivants :

Type Description
T[] ou List<T> où T est l’un des types de liaison de sortie d’objet blob unique Tableau ou liste de plusieurs objets blob. Chaque entrée représente un objet blob du conteneur. Vous pouvez également lier à n’importe quelle interface implémentée par ces types, telles que IEnumerable<T>.
BlobContainerClient1 Un client connecté au conteneur. Ce type offre le meilleur contrôle pour le traitement du conteneur et peut être utilisé pour écrire dans celui-ci si la connexion dispose d’autorisations suffisantes.

1 Pour utiliser ces types, vous devez référencer Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 ou version ultérieure et les dépendances courantes pour les liaisons de type kit de développement logiciel (SDK).

La liaison avec string ou Byte[] n’est recommandée que lorsque l’objet Blob est de petite taille. Cette recommandation est d’application, car l’ensemble du contenu des objets Blob est chargé dans la mémoire. Pour la plupart des objets Blob, utilisez un type Stream ou BlobClient. Pour plus d’informations, consultez Concurrence et utilisation de la mémoire.

Si un message d'erreur s’affiche lorsque vous essayez d’effectuer la liaison à un des types de SDK Stockage, vérifiez que vous avez une référence à la bonne version du SDK Stockage.

Vous pouvez également utiliser StorageAccountAttribute pour spécifier le compte de stockage à utiliser. Vous pouvez le faire lorsque vous avez besoin d’utiliser un compte de stockage différent de celui utilisé par les autres fonctions de la bibliothèque. Le constructeur prend le nom d’un paramètre d’application comportant une chaîne de connexion de stockage. L’attribut peut être appliqué au niveau du paramètre, de la méthode ou de la classe. L’exemple suivant montre le niveau de la classe et celui de la méthode :

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

  • La propriété Connection de l’attribut BlobTrigger.
  • L’attribut StorageAccount appliqué au même paramètre que l’attribut BlobTrigger.
  • L’attribut StorageAccount appliqué à la fonction.
  • L’attribut StorageAccount appliqué à la classe.
  • Compte de stockage par défaut pour l’application de fonction, lequel est défini dans le paramètre d’application AzureWebJobsStorage.

L'attribut @BlobInput vous permet d’accéder à l’objet blob qui a déclenché la fonction. Si vous utilisez un tableau d’octets avec l’attribut, définissez dataType sur binary. Reportez-vous à l’exemple d’entrée pour plus d'informations.

Accédez aux données blob avec context.extraInputs.get().

Accédez aux données BLOB via un paramètre qui correspond au nom désigné par le paramètre Nom de la liaison dans le fichier function.json.

Accédez aux données blob via le paramètre de type InputStream. Reportez-vous à l’exemple d’entrée pour plus d'informations.

Functions prend également en charge les liaisons de types de sdk Python pour le stockage Blob Azure, ce qui vous permet d’utiliser les données blob à l’aide de ces types de SDK sous-jacents :

Important

La prise en charge des types sdk pour Python est actuellement en préversion et est prise en charge uniquement pour le modèle de programmation Python v2. Pour plus d’informations, consultez les types de SDK dans Python.

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 :

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 :

Propriété Modèle de variable d’environnement Description Valeur d'exemple
URI du service blob <CONNECTION_NAME_PREFIX>__serviceUri1 URI du plan de données du service blob auquel vous vous connectez, à l’aide du même schéma HTTPS. https://<storage_account_name>.blob.core.windows.net

1 <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 :

Propriété Modèle de variable d’environnement Description Valeur d'exemple
URI du service blob <CONNECTION_NAME_PREFIX>__blobServiceUri URI du plan de données du service blob auquel vous vous connectez, à l’aide du même schéma HTTPS. https://<storage_account_name>.blob.core.windows.net
URI de service de file d’attente (requis pour les déclencheurs Blob2) <CONNECTION_NAME_PREFIX>__queueServiceUri URI du plan de données d’un service de file d’attente, à l’aide du schéma HTTPS. Cette valeur est requise uniquement pour les déclencheurs d’objets Blob. https://<storage_account_name>.queue.core.windows.net

2 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.

Important

Parmi les autorisations exposées par le service cible, certaines ne sont peut-être pas nécessaires pour tous les contextes. Dans la mesure du possible, adhérez au principe du privilège minimum, en accordant à l’identité uniquement les privilèges nécessaires. Par exemple, si l’application a juste besoin de pouvoir lire à partir d’une source de données, utilisez un rôle qui a uniquement l’autorisation de lecture. Il serait inapproprié d’attribuer un rôle qui autorise aussi l’écriture dans ce service, car ce serait une autorisation excessive pour une opération de lecture. De même, vous voudrez vous assurer que l’attribution de rôle est limitée aux seules ressources qui doivent être lues.

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.

Type de liaison Exemples de rôles intégrés
Déclencheur Propriétaire des données Blob de stockage et Contributeuraux données de file d’attente de stockage 1

Des autorisations supplémentaires doivent également être accordées à la connexion AzureWebJobsStorage.2
Liaison d’entrée Lecteur des données blob du stockage
Liaison de sortie Propriétaire des données Blob du stockage

1 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.

2 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é.

Étapes suivantes