Patrones de expresiones de enlace de Azure Functions

  • Artículo

Una de las características más eficaces de los desencadenadores y enlaces son las expresiones de enlace. 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.

La mayoría de las expresiones se identifican encerrándolas entre llaves. Por ejemplo, en una función de desencadenador de cola, {queueTrigger} se resuelve como el texto del mensaje de cola. 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.

Tipos de expresiones de enlace

Expresiones de enlace: configuración de aplicación

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

Los ajustes de la aplicación también son útiles cuando se desea cambiar la configuración en función del entorno. Por ejemplo, en un entorno de prueba, es posible que quiera supervisar una cola o un contenedor de almacenamiento de blobs diferente.

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

Cuando una función se ejecuta localmente, los valores de configuración de aplicación proceden del archivo local.settings.json.

Nota

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.

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

{
  "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:

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

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. El patrón también puede incluir criterios de filtrado que especifiquen qué blobs pueden desencadenar una invocación de función.

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:

{
  "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:

    ...
    {
      "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:

// 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. En el ejemplo siguiente, los parámetros del constructor de atributo son los mismos valores path que los ejemplos de path anteriores:

[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. En el ejemplo siguiente, la función se desencadena solo en los nombres de archivo que coinciden con un patrón: anyname-anyfile.csv

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

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.

Metadatos de desencadenador

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. Estos valores pueden usarse como parámetros de entrada en C# y F# o como propiedades en el objeto context.bindings de JavaScript.

Por ejemplo, un desencadenador de Azure Queue Storage admite las siguientes propiedades:

  • QueueTrigger (desencadena el contenido del mensaje si hay una cadena válida)
  • DequeueCount
  • ExpirationTime
  • Identificador
  • InsertionTime
  • NextVisibleTime
  • PopReceipt

A estos valores de metadatos se accede en las propiedades del archivo function.json. Por ejemplo, supongamos que usa un desencadenador de cola y el mensaje de la cola contiene el nombre de un blob que desea leer. 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:

{
  "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. Para un ejemplo, consulte la sección acerca de los metadatos de los desencadenadores de cola. 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.

Cargas JSON

En algunos escenarios, puede consultar las propiedades de la carga útil del desencadenador en la configuración para otros enlaces en la misma función y en el código de función. Esto requiere que la carga útil del disparador sea JSON y sea menor que un umbral específico para cada disparador. Normalmente, el tamaño de la carga útil debe ser inferior a 100 MB, pero debes verificar el contenido de referencia para cada activador. El uso de propiedades de carga útil del activador puede afectar el rendimiento de su aplicación y obliga a que el tipo de parámetro del activador sea tipos simples como cadenas o un tipo de objeto personalizado que represente datos JSON. No se puede utilizar con transmisiones, clientes u otros tipos de SDK.

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"}. Un enlace de entrada de blob lee el blob y el enlace de salida HTTP devuelve el contenido del blob en la respuesta HTTP. 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}").

{
  "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:

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.

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

Notación de puntos

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 (.). Esta notación no funciona para los enlaces de Azure Cosmos DB o Almacenamiento de tablas.

Por ejemplo, suponga que su carga útil JSON tiene el siguiente aspecto:

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

Puede hacer referencia directamente a FileName como BlobName.FileName. Con este formato JSON, así sería el aspecto de la propiedad path del ejemplo anterior:

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

En C#, necesitaría dos clases:

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 globales

La expresión de enlace {rand-guid} crea un identificador único global. La siguiente ruta de acceso de blob en un archivo function.json crea un blob con un nombre como function.json.

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

Hora actual

La expresión de enlace DateTime se resuelve como DateTime.UtcNow. La siguiente ruta de acceso de blob en un archivo function.json crea un blob con un nombre como function.json.

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

Enlace en tiempo de ejecución

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. 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. Para obtener más información, consulte la referencia para desarrolladores de C# o la referencia para desarrolladores de scripts de C#.

Contenido relacionado