Partage via

Liaison de sortie Stockage Blob Azure pour Azure Functions

  • Article

La liaison de sortie vous permet de modifier et de supprimer des données de stockage d’objets Blob dans 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é.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    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, utilisation d’OutputBinding (Java)

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[]. L’annotation BlobOutput lie à OutputBinding outputItem, qui est ensuite utilisé par la fonction pour écrire le contenu de l’objet blob d’entrée dans le conteneur de stockage configuré.

  @FunctionName("copyBlobHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage copyBlobHttp(
    @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,
    @BlobOutput(
      name = "target", 
      path = "myblob/{Query.file}-CopyViaHttp")
    OutputBinding<String> outputItem,
    final ExecutionContext context) {
      // Save blob to outputItem
      outputItem.setValue(new String(content, StandardCharsets.UTF_8));

      // 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, utilisation de la valeur de retour de la fonction (Java)

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[]. L’annotation BlobOutput lie à la valeur de retour de la fonction, qui est ensuite utilisée par le runtime pour écrire le contenu de l’objet blob d’entrée dans le conteneur de stockage configuré.

  @FunctionName("copyBlobQueueTrigger")
  @StorageAccount("Storage_Account_Connection_String")
  @BlobOutput(
    name = "target", 
    path = "myblob/{queueTrigger}-Copy")
  public String copyBlobQueue(
    @QueueTrigger(
      name = "filename", 
      dataType = "string",
      queueName = "myqueue-items") 
    String filename,
    @BlobInput(
      name = "file", 
      path = "samples-workitems/{queueTrigger}") 
    String content,
    final ExecutionContext context) {
      context.getLogger().info("The content of \"" + filename + "\" is: " + content);
      return content;
  }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation @BlobOutput sur les paramètres de fonction dont la valeur serait écrite dans un objet du stockage Blob. Le type de paramètre doit être OutputBinding<T>, où T désigne n’importe quel type Java natif ou un POJO.

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 comment créer une copie d’un BLOB entrant comme sortie d’une fonction PowerShell.

Dans le fichier config de la fonction (function.json), la propriété de métadonnées trigger est utilisée pour spécifier le nom du BLOB de sortie dans les propriétés path.

Remarque

Pour éviter les boucles infinies, vérifiez que vos chemins d’entrée et de sortie sont différents.

{
  "bindings": [
    {
      "name": "myInputBlob",
      "path": "data/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in",
      "type": "blobTrigger"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "data/copy/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Voici le code PowerShell :

# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob

L’exemple suivant montre des liaisons d’entrée et de sortie d’objets blob dans une fonction Java. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

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és 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 constructeur BlobOutputAttribute 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.
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 les fonctions Python définies à l’aide de function.json, consultez la section Configuration.

Annotations

L'attribut @BlobOutput 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 de sortie 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 output.storageBlob().

Propriété Description
path Chemin du conteneur d’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é Description
type Cette propriété doit être définie sur blob.
direction Cette propriété doit être définie sur out pour une liaison de type sortie. 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. La valeur doit être $return pour faire référence à la valeur de retour de la fonction.
path Chemin du conteneur d’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.

Pour obtenir des exemples complets, consultez la section Exemple.

Utilisation

Les types de liaisons pris en charge par la sortie 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 Un objet représentant le contenu d'un blob JSON. Les fonctions tentent de sérialiser un ancien type d'objet CLR (POCO) en données JSON.

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

Type Description
T[] où T est l’un des types de liaison de sortie d’objet blob unique Un tableau contenant le contenu de plusieurs blobs. Chaque entrée représente le contenu d’un blob.

Pour d’autres scénarios de sortie, créez et utilisez un BlobClient ou BlobContainerClient avec d’autres types à partir d’Azure.Storage.Blobs directement. Consultez Inscrire des clients Azure pour obtenir un exemple d’utilisation de l’injection de dépendances pour créer un type de client à partir du Kit de développement logiciel (SDK) Azure.

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 @BlobOutput 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 de sortie pour plus d'informations.

Accédez aux données blob en retournant la valeur directement ou en utilisant context.extraOutputs.set().

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.

Vous pouvez déclarer des paramètres de fonction comme types suivants pour écrire dans le stockage blob :

  • Chaînes comme func.Out[str]
  • Flux comme func.Out[func.InputStream]

Reportez-vous à l’exemple de sortie pour plus d'informations.

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 du stockage et Contributeur aux données en file d’attente du stockage1

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

Exceptions et codes de retour

Liaison Informations de référence
Objet blob Codes d’erreur du service BLOB
Objet blob, Table, File d’attente Codes d’erreur de stockage
Objet blob, Table, File d’attente Dépannage

Étapes suivantes