Liaison de sortie Stockage Blob Azure pour Azure Functions

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

Le support Go n’est pas disponible pour ce liaison pour le moment.

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 création d’un blob dans le conteneur test-samples-trigger déclenche la fonction. 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 est un type natif de Java ou un objet Java simple (POJO).

L’exemple suivant montre une fonction TypeScript déclenchée par une file d’attente qui fait une copie d’un blob. Un message de file contenant le nom du blob à copier déclenche la fonction. 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. Un message de file contenant le nom du blob à copier déclenche la fonction. 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. L’utilisation de ces types est recommandée car l’ensemble du contenu du blob est chargé en 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é BlobTrigger de l’attribut Connection.
  • 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 connection propriété est définie sur une clé dans les paramètres de l’application qui renvoie une valeur utilisée par l’exécution Functions pour se connecter au compte de stockage utilisé par l’extension. La valeur du paramètre de propriété de connexion dépend du type de connexion :

  • Connexion d’identité gérée : La connection propriété est <CONNECTION_NAME_PREFIX> partagée par un groupe de paramètres qui définissent ensemble une connexion basée sur l’identité avec le compte de stockage. Pour plus d’informations, voir Définir les connexions identités.
  • Référence Key Vault : Le connection paramètre de propriété renvoie une référence Azure Key Vault à l’emplacement où la chaîne de connexion est centralisée. Pour plus d’informations, voir Définir les connexions Key Vault.
  • Référence App Configuration : Le connection paramètre de propriété renvoie une référence Azure App Configuration qui renvoie une chaîne de connexion ou une référence Key Vault. Pour plus d’informations, consultez Azure App Configuration dans l’article sur les connexions.
  • Connection string : Le connection paramètre de propriété renvoie la chaîne de connexion réelle du compte de stockage. Parce que la chaîne de connexion contient des clés secrètes partagées, vous devriez envisager d’utiliser une connexion d’identité gérée, lorsque c’est possible. Pour plus d’informations, voir Définir les connexions.

Pour en savoir plus sur les connexions de liaisons, consultez Gérer la connexion dans Azure Functions. 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.

Lorsque vous définissez connection une clé ou un préfixe de clé nommé AzureWebJobsStorage ou une chaîne vide, l’extension de liaison utilise le compte de stockage hôte par défaut. Pour plus d’informations, voir Optimiser la performance de stockage.

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

  • Last updated on