Modèles d’expressions de liaison Azure FunctionsAzure Functions binding expression patterns

Les expressions de liaison sont l’une des fonctionnalités les plus puissantes des déclencheurs et liaisons.One of the most powerful features of triggers and bindings is binding expressions. Dans le fichier function.json ainsi que dans les paramètres et le code de la fonction, vous pouvez utiliser des expressions qui sont remplacées par des valeurs provenant de diverses sources.In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

La plupart des expressions sont identifiées par les accolades qui les entourent.Most expressions are identified by wrapping them in curly braces. Par exemple, dans une fonction de déclencheur de file d’attente, {queueTrigger} correspond au texte du message de file d’attente.For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. Si la propriété path pour une liaison de sortie d’objet blob est container/{queueTrigger} et que la fonction est déclenchée par un message de file d’attente HelloWorld, alors un objet blob nommé HelloWorld est créé.If the path property for a blob output binding is container/{queueTrigger} and the function is triggered by a queue message HelloWorld, a blob named HelloWorld is created.

Types d’expressions de liaisonTypes of binding expressions

Expression de liaison - Paramètres d’applicationBinding expressions - app settings

En tant que meilleure pratique, les chaînes de connexion et les secrets doivent être gérés avec des paramètres de l’application, plutôt qu’avec des fichiers de configuration.As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. Cela limite l’accès à ces secrets et permet de stocker des fichiers tels que function.json en toute sécurité dans des référentiels de contrôle de code source public.This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

Les paramètres de l’application sont également utiles lorsque vous souhaitez modifier la configuration en fonction de l’environnement.App settings are also useful whenever you want to change configuration based on the environment. Par exemple, dans un environnement de test, vous pourriez vouloir surveiller une autre file d’attente ou un autre conteneur Stockage Blob.For example, in a test environment, you may want to monitor a different queue or blob storage container.

Les expressions de liaison de paramètres d’application ne sont pas identifiées comme les autres expressions de liaison : elles sont entourées de signes de pourcentage et non d’accolades.App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. Par exemple, si le chemin de liaison de sortie d’objet blob est %Environment%/newblob.txt et que la valeur du paramètre d’application Environment est Development, un objet blob sera créé dans le conteneur Development.For example if the blob output binding path is %Environment%/newblob.txt and the Environment app setting value is Development, a blob will be created in the Development container.

Lorsqu’une fonction s’exécute localement, les valeurs des paramètres de l’application proviennent du fichier local.settings.json.When a function is running locally, app setting values come from the local.settings.json file.

Veuillez noter que la propriété connection des déclencheurs et liaisons est un cas spécial et résout automatiquement les valeurs en tant que paramètres de l’application, sans les signes de pourcentage.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

L’exemple suivant est un déclencheur de stockage de file d’attente Azure qui utilise un paramètre d’application %input-queue-name% pour définir la file d’attente sur laquelle effectuer le déclenchement.The following example is an Azure Queue Storage trigger that uses an app setting %input-queue-name% to define the queue to trigger on.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input-queue-name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

Vous pouvez utiliser la même approche dans les bibliothèques de classes :You can use the same approach in class libraries:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input-queue-name%")]string myQueueItem, 
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

Nom du fichier de déclencheurTrigger file name

Le path pour un objet blob de déclencheur peut être un modèle qui vous permet de faire référence au nom de l’objet blob de déclenchement dans d’autres liaisons et codes de fonction.The path for a Blob trigger can be a pattern that lets you refer to the name of the triggering blob in other bindings and function code. Le modèle peut également inclure des critères de filtre qui indiquent les objets blob qui peuvent déclencher un appel de fonction.The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

Par exemple, dans la liaison de déclencheur d’objet blob suivante, le modèle path est sample-images/{filename}, ce qui crée une expression de liaison nommée filename :For example, in the following Blob trigger binding, the path pattern is sample-images/{filename}, which creates a binding expression named filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

L’expression filename peut ensuite être utilisée dans une liaison de sortie pour spécifier le nom de l’objet blob en cours de création :The expression filename can then be used in an output binding to specify the name of the blob being created:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

Le code de fonction peut accéder à cette même valeur en utilisant filename comme nom de paramètre :Function code has access to this same value by using filename as a parameter name:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)  
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
} 

La même possibilité d’utiliser des modèles et des expressions de liaison s’applique aux attributs dans les bibliothèques de classes.The same ability to use binding expressions and patterns applies to attributes in class libraries. Dans l’exemple suivant, les paramètres de constructeur d’attribut sont les mêmes valeurs path que les exemples de function.json précédents :In the following example, the attribute constructor parameters are the same path values as the preceding function.json examples:

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger log)
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
}

Vous pouvez également créer des expressions pour certaines parties du nom de fichier.You can also create expressions for parts of the file name. Dans l’exemple suivant, la fonction est déclenchée uniquement sur les noms de fichiers qui correspondent à un modèle : anyname-anyfile.csvIn the following example, function is triggered only on file names that match a pattern: anyname-anyfile.csv

{
    "name": "myBlob",
    "type": "blobTrigger",
    "direction": "in",
    "path": "testContainerName/{date}-{filetype}.csv",
    "connection": "OrderStorageConnection"
}

Pour plus d’informations sur l’utilisation des expressions et des modèles dans la chaîne du chemin d’accès à l’objet blob, consultez l’article sur la référence de liaison de stockage blob.For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

Métadonnées d’un déclencheurTrigger metadata

En plus de la charge utile de données fournie par un déclencheur (par exemple, le contenu du message de file d’attente qui a déclenché une fonction), plusieurs déclencheurs fournissent des valeurs de métadonnées supplémentaires.In addition to the data payload provided by a trigger (such as the content of the queue message that triggered a function), many triggers provide additional metadata values. Ces valeurs peuvent être utilisées comme paramètres d’entrée dans C# et F# ou comme propriétés sur l’objet context.bindings dans JavaScript.These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

Par exemple, un déclencheur Stockage File d’attente Azure prend en charge les propriétés suivantes :For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigger - déclenchant le contenu du message si une chaîne valideQueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • IdId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

Ces valeurs de métadonnées sont accessibles dans les propriétés de fichier function.json.These metadata values are accessible in function.json file properties. Par exemple, supposons que vous utilisez un déclencheur de file d’attente et que le message de la file d’attente contient le nom d’un objet blob que vous souhaitez lire.For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. Dans le fichier function.json, vous pouvez utiliser la propriété de métadonnées queueTrigger dans la propriété de l’objet blob path, comme indiqué dans l’exemple suivant :In the function.json file, you can use queueTrigger metadata property in the blob path property, as shown in the following example:

  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]

Les détails des propriétés de métadonnées pour chaque déclencheur sont décrits dans l’article de référence correspondante.Details of metadata properties for each trigger are described in the corresponding reference article. Pour obtenir un exemple, consultez Métadonnées de déclencheur de file d’attente.For an example, see queue trigger metadata. La documentation est également disponible dans l’onglet Intégrer du portail, dans la section Documentation située sous la zone de configuration de liaison.Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

Charges utiles JSONJSON payloads

Lorsque la charge utile d’un déclencheur est JSON, vous pouvez faire référence à ses propriétés dans la configuration pour d’autres liaisons dans la même fonction et dans le code de la fonction.When a trigger payload is JSON, you can refer to its properties in configuration for other bindings in the same function and in function code.

L’exemple suivant illustre le fichier function.json pour une fonction de Webhook qui reçoit un nom d’objet blob dans JSON : {"BlobName":"HelloWorld.txt"}.The following example shows the function.json file for a webhook function that receives a blob name in JSON: {"BlobName":"HelloWorld.txt"}. Une liaison d’entrée d’objet blob lit l’objet blob et la liaison de sortie HTTP retourne le contenu de l’objet blob dans la réponse HTTP.A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. Notez que la liaison d’entrée d’objet blob obtient le nom de l’objet blob en faisant directement référence à la propriété BlobName ("path": "strings/{BlobName}")Notice that the Blob input binding gets the blob name by referring directly to the BlobName property ("path": "strings/{BlobName}")

{
  "bindings": [
    {
      "name": "info",
      "type": "httpTrigger",
      "direction": "in",
      "webHookType": "genericJson"
    },
    {
      "name": "blobContents",
      "type": "blob",
      "direction": "in",
      "path": "strings/{BlobName}",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ]
}

Pour que cela fonctionne en C# et F#, vous avez besoin d’une classe qui définit les champs à désérialiser, comme dans l’exemple suivant :For this to work in C# and F#, you need a class that defines the fields to be deserialized, as in the following example:

using System.Net;
using Microsoft.Extensions.Logging;

public class BlobInfo
{
    public string BlobName { get; set; }
}
  
public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents, ILogger log)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    log.LogInformation($"Processing: {info.BlobName}");

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

Dans JavaScript, la désérialisation JSON est effectuée automatiquement.In JavaScript, JSON deserialization is automatically performed.

module.exports = function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
    context.done();
}

Notation par pointsDot notation

Si certaines des propriétés de votre charge utile JSON sont des objets dotés de propriétés, vous pouvez y faire référence directement à l’aide de la notation par points.If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. Par exemple, supposons que votre JSON ressemble à l’exemple qui suit :For example, suppose your JSON looks like this:

{
  "BlobName": {
    "FileName":"HelloWorld",
    "Extension":"txt"
  }
}

Vous pouvez faire référence directement à FileName par l’expression BlobName.FileName.You can refer directly to FileName as BlobName.FileName. Avec ce format JSON, voici ce à quoi la propriété path de l’exemple précédent ressemblerait :With this JSON format, here's what the path property in the preceding example would look like:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

En C#, vous avez besoin de deux classes :In C#, you would need two classes:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

Créer des GUIDCreate GUIDs

L’expression de liaison {rand-guid} crée un GUID.The {rand-guid} binding expression creates a GUID. Le chemin d’accès à l’objet blob suivant dans un fichier function.json crée un objet blob avec un nom similaire à ce qui suit : 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.The following blob path in a function.json file creates a blob with a name like 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}.txt"
}

Heure actuelleCurrent time

L’expression de liaison DateTime se résout en DateTime.UtcNow.The binding expression DateTime resolves to DateTime.UtcNow. Le chemin d’accès à l’objet blob suivant dans un fichier function.json crée un objet blob avec un nom similaire à ce qui suit : 2018-02-16T17-59-55Z.txt.The following blob path in a function.json file creates a blob with a name like 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}.txt"
}

Liaison au runtimeBinding at runtime

Avec C# et d’autres langages .NET, vous pouvez utiliser un schéma de liaison impératif, par opposition aux liaisons déclaratives dans function.json, et des attributs.In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json and attributes. La liaison impérative est utile lorsque les paramètres de liaison doivent être calculés au moment du runtime plutôt que lors de la conception.Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. Pour plus d’informations, consultez les informations de référence pour les développeurs C# ou les informations de référence pour les développeurs de scripts C#.To learn more, see the C# developer reference or the C# script developer reference.

Étapes suivantesNext steps