Los patrones de expresiones de enlace de Azure FunctionsAzure Functions binding expression patterns

Una de las características más eficaces de desencadenadores y enlaces es expresiones de enlace.One of the most powerful features of triggers and bindings is binding expressions. En el archivo function.json, y en el código y en los parámetros de función, puede usar expresiones que se resuelvan como valores procedentes de diversos orígenes.In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

La mayoría de las expresiones se identifican encerrándolas entre llaves.Most expressions are identified by wrapping them in curly braces. Por ejemplo, en una función de desencadenador de cola, {queueTrigger} se resuelve como el texto del mensaje de cola.For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. Si la propiedad path de un enlace de blob de salida es container/{queueTrigger} y la función se desencadena mediante un mensaje de cola HelloWorld, se crea un blob denominado HelloWorld.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.

Tipos de expresiones de enlaceTypes of binding expressions

Expresiones de enlace: configuración de aplicaciónBinding expressions - app settings

Como procedimiento recomendado, los secretos y las cadenas de conexión deberían administrarse mediante los ajustes de la aplicación, en lugar de archivos de configuración.As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. De este modo, se limita el acceso a estos secretos y resulta seguro almacenar archivos como function.json en repositorios de control de código fuente públicos.This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

Los ajustes de la aplicación también son útiles cuando se desea cambiar la configuración en función del entorno.App settings are also useful whenever you want to change configuration based on the environment. Por ejemplo, en un entorno de prueba, es posible que quiera supervisar una cola o un contenedor de almacenamiento de blobs diferente.For example, in a test environment, you may want to monitor a different queue or blob storage container.

Las expresiones de enlace de configuración de aplicación se identifican de forma diferente de otras expresiones de enlace: se encierran entre símbolos de porcentaje en lugar de entre llaves.App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. Por ejemplo, si la ruta de acceso del enlace de salida de blob es %Environment%/newblob.txt y el valor de configuración de aplicación Environment es Development, se creará un blob en el contenedor 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.

Cuando una función se ejecuta localmente, los valores de configuración de aplicación proceden del archivo local.settings.json.When a function is running locally, app setting values come from the local.settings.json file.

Tenga en cuenta que la propiedad connection de los desencadenadores y enlaces es un caso especial, ya que resuelve automáticamente los valores como configuración de aplicación, sin símbolos de porcentaje.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

En el ejemplo siguiente, aparece un desencadenador de Azure Queue Storage que se sirve del valor de configuración de la aplicación %input-queue-name% para definir la cola que se desencadenará.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"
    }
  ]
}

Puede usar el mismo enfoque con las bibliotecas de clases: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}");
}

Nombre de archivo de desencadenadorTrigger file name

El patrón path de un desencadenador de blob puede ser uno que permite hacer referencia al nombre del blob de desencadenamiento en otros enlaces y el código de función.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. El patrón también puede incluir criterios de filtrado que especifiquen qué blobs pueden desencadenar una invocación de función.The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

Por ejemplo, en el siguiente enlace de desencadenador de blob, el patrón path es sample-images/{filename}, lo que crea una expresión de enlace denominada 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"
    },
    ...

Luego, la expresión filename puede utilizarse en un enlace de salida para especificar el nombre del blob que se va a crear: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"
    }
  ],
}

El código de función tiene acceso a este mismo valor usando filename como nombre de parámetro: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 misma capacidad para usar patrones y expresiones de enlace se aplica a los atributos de las bibliotecas de clases.The same ability to use binding expressions and patterns applies to attributes in class libraries. En el ejemplo siguiente, los parámetros del constructor de atributo son los mismos valores path que los ejemplos de function.json anteriores: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}");
    // ...
}

También puede crear expresiones para partes del nombre de archivo como la extensión.You can also create expressions for parts of the file name such as the extension. Para obtener más información sobre cómo usar expresiones y patrones en la cadena de ruta de acceso de blob, consulte la referencia de enlace de blob de almacenamiento.For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

Metadatos de desencadenadorTrigger metadata

Además de la carga de datos que proporciona un desencadenador (como el contenido del mensaje de la cola que desencadenó una función), muchos desencadenadores facilitan valores de metadatos adicionales.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. Estos valores pueden usarse como parámetros de entrada en C# y F# o como propiedades en el objeto context.bindings de JavaScript.These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

Por ejemplo, un desencadenador de Azure Queue Storage admite las siguientes propiedades:For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigger (desencadena el contenido del mensaje si hay una cadena válida)QueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • IdId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

A estos valores de metadatos se accede en las propiedades del archivo function.json.These metadata values are accessible in function.json file properties. Por ejemplo, supongamos que usa un desencadenador de cola y el mensaje de la cola contiene el nombre de un blob que desea leer.For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. En el archivo function.json, puede usar la propiedad de metadatos queueTrigger en la propiedad de blob path, como se muestra en el ejemplo siguiente: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"
    }
  ]

Los detalles sobre las propiedades de metadatos de cada desencadenador se describen en el artículo de referencia correspondiente.Details of metadata properties for each trigger are described in the corresponding reference article. Para un ejemplo, consulte la sección acerca de los metadatos de los desencadenadores de cola.For an example, see queue trigger metadata. También podrá encontrar documentación en la pestaña Integrar del portal, en la sección Documentación, debajo del área de configuración de enlaces.Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

Cargas de JSONJSON payloads

Cuando una carga de desencadenador es JSON, puede hacer referencia a sus propiedades en la configuración de otros enlaces de la misma función y del código de función.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.

El siguiente ejemplo muestra el archivo function.json de una función de webhook que recibe el nombre de un blob en 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"}. Un enlace de entrada de blob lee el blob y el enlace de salida HTTP devuelve el contenido del blob en la respuesta HTTP.A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. Tenga en cuenta que el enlace de entrada de blob obtiene el nombre del blob haciendo referencia directamente a la propiedad 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"
    }
  ]
}

Para que funcione en C# y F#, necesita una clase que defina los campos que se deserializarán, como en el ejemplo siguiente: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}"
    });
}

En JavaScript, la deserialización de JSON se lleva a cabo de manera automática.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();
}

Notación de puntosDot notation

Si algunas de las propiedades de la carga útil JSON son objetos con propiedades, puede hacer referencia a ellos directamente mediante la notación de puntos.If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. Por ejemplo, suponga que su carga útil JSON tiene el siguiente aspecto:For example, suppose your JSON looks like this:

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

Puede hacer referencia directamente a FileName como BlobName.FileName.You can refer directly to FileName as BlobName.FileName. Con este formato JSON, así sería el aspecto de la propiedad path del ejemplo anterior: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#, necesitaría dos clases: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; }
}

Creación de los identificadores únicos globalesCreate GUIDs

La expresión de enlace {rand-guid} crea un identificador único global.The {rand-guid} binding expression creates a GUID. La siguiente ruta de acceso de blob en un archivo function.json crea un blob con un nombre como 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}"
}

Hora actualCurrent time

La expresión de enlace DateTime se resuelve como DateTime.UtcNow.The binding expression DateTime resolves to DateTime.UtcNow. La siguiente ruta de acceso de blob en un archivo function.json crea un blob con un nombre como 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}"
}

Enlace en tiempo de ejecuciónBinding at runtime

En C# y otros lenguajes .NET, puede usar un patrón de enlace imperativo, en contraposición a los enlaces declarativos de function.json y los atributos.In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json and attributes. Los enlaces imperativos resultan útiles cuando los parámetros de enlace tienen que calcularse en tiempo de ejecución, en lugar de en el tiempo de diseño.Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. Para obtener más información, consulte la referencia para desarrolladores de C# o la referencia para desarrolladores de scripts de C#.To learn more, see the C# developer reference or the C# script developer reference.

Pasos siguientesNext steps