Partilhar via

Padrões de expressão de vinculação do Azure Functions

  • Artigo

Um dos recursos mais poderosos de gatilhos e ligações é a vinculação de expressões. No arquivo function.json e nos parâmetros de função e código, você pode usar expressões que resolvem para valores de várias fontes.

A maioria das expressões são identificadas encapsulando-as em chavetas. Por exemplo, em uma função de gatilho de fila, {queueTrigger} resolve para o texto da mensagem de fila. Se a path propriedade de uma ligação de saída de blob for container/{queueTrigger} e a função for acionada por uma mensagem HelloWorldde fila , um blob nomeado HelloWorld será criado.

Tipos de expressões de enlace

Expressões de vinculação - configurações do aplicativo

Como prática recomendada, segredos e cadeias de conexão devem ser gerenciados usando configurações do aplicativo, em vez de arquivos de configuração. Isso limita o acesso a esses segredos e torna seguro armazenar arquivos como function.json em repositórios públicos de controle de código-fonte.

As configurações do aplicativo também são úteis sempre que você deseja alterar a configuração com base no ambiente. Por exemplo, em um ambiente de teste, talvez você queira monitorar uma fila ou contêiner de armazenamento de blob diferente.

As expressões de vinculação de configuração de aplicativo são identificadas de forma diferente de outras expressões de vinculação: elas são envolvidas em sinais de porcentagem em vez de chaves encaracoladas. Por exemplo, se o caminho de ligação de saída do blob for %Environment%/newblob.txt e o valor da configuração do Environment aplicativo for Development, um blob será criado no Development contêiner.

Quando uma função é executada localmente, os valores de configuração do aplicativo vêm do arquivo local.settings.json .

Nota

A connection propriedade de gatilhos e associações é um caso especial e resolve automaticamente os valores como configurações do aplicativo, sem sinais de porcentagem.

O exemplo a seguir é um gatilho de Armazenamento de Filas do Azure que usa uma configuração %input_queue_name% de aplicativo para definir a fila a ser acionada.

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

Você pode usar a mesma abordagem em bibliotecas de classes:

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

Nome de ficheiro do acionador

O path gatilho para um Blob pode ser um padrão que permite que você se refira ao nome do blob de acionamento em outras associações e código de função. O padrão também pode incluir critérios de filtragem que especificam quais blobs podem acionar uma chamada de função.

Por exemplo, na seguinte ligação de gatilho de Blob, o path padrão é sample-images/{filename}, que cria uma expressão de ligação chamada filename:

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

A expressão filename pode ser usada em uma associação de saída para especificar o nome do blob que está sendo criado:

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

O código da função tem acesso a esse mesmo valor usando filename como um nome 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}");
    // ...
}

A mesma capacidade de usar expressões e padrões de associação se aplica a atributos em bibliotecas de classes. No exemplo a seguir, os parâmetros do construtor de atributo são os mesmos path valores que os exemplos de function.json 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}");
    // ...
}

Você também pode criar expressões para partes do nome do arquivo. No exemplo a seguir, a função é acionada somente em nomes de arquivo que correspondem a um padrão: anyname-anyfile.csv

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

Para obter mais informações sobre como usar expressões e padrões na cadeia de caracteres do caminho Blob, consulte a Referência de vinculação de blob de armazenamento.

Metadados do acionador

Além da carga útil de dados fornecida por um gatilho (como o conteúdo da mensagem de fila que disparou uma função), muitos gatilhos fornecem valores de metadados adicionais. Esses valores podem ser usados como parâmetros de entrada em C# e F# ou propriedades no context.bindings objeto em JavaScript.

Por exemplo, um gatilho de armazenamento de fila do Azure dá suporte às seguintes propriedades:

  • QueueTrigger - acionando o conteúdo da mensagem se uma cadeia de caracteres válida
  • DequeueCount
  • Tempo de expiração
  • Id
  • Tempo de Inserção
  • PróximoVisibleTime
  • PopReceipt

Esses valores de metadados são acessíveis em function.json propriedades do arquivo. Por exemplo, suponha que você use um gatilho de fila e a mensagem de fila contenha o nome de um blob que você deseja ler. No arquivo function.json, você pode usar queueTrigger a propriedade metadata na propriedade blobpath, conforme mostrado no exemplo a seguir:

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

Os detalhes das propriedades de metadados para cada gatilho são descritos no artigo de referência correspondente. Para obter um exemplo, consulte metadados de gatilho de fila. A documentação também está disponível na guia Integrar do portal, na seção Documentação abaixo da área de configuração de vinculação.

Payloads JSON

Em alguns cenários, você pode consultar as propriedades da carga útil do gatilho na configuração para outras associações na mesma função e no código da função. Isso requer que a carga útil do gatilho seja JSON e seja menor do que um limite específico para cada gatilho. Normalmente, o tamanho da carga precisa ser inferior a 100 MB, mas você deve verificar o conteúdo de referência para cada gatilho. O uso de propriedades de carga útil de gatilho pode afetar o desempenho de seu aplicativo e força o tipo de parâmetro trigger a ser tipos simples, como cadeias de caracteres ou um tipo de objeto personalizado que representa dados JSON. Ele não pode ser usado com fluxos, clientes ou outros tipos de SDK.

O exemplo a seguir mostra o arquivo function.json para uma função webhook que recebe um nome de blob em JSON: {"BlobName":"HelloWorld.txt"}. Uma associação de entrada Blob lê o blob e a associação de saída HTTP retorna o conteúdo do blob na resposta HTTP. Observe que a associação de entrada Blob obtém o nome do blob referindo-se diretamente à BlobName propriedade ("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 isso funcione em C# e F#, você precisa de uma classe que defina os campos a serem desserializados, como no exemplo a seguir:

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}"
    });
}

Em JavaScript, a desserialização JSON é executada automaticamente.

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

Notação de pontos

Se algumas das propriedades em sua carga JSON forem objetos com propriedades, você poderá consultá-las diretamente usando a notação dot (.). Essa notação não funciona para associações de armazenamento do Azure Cosmos DB ou Tabela.

Por exemplo, suponha que seu JSON tenha esta aparência:

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

Você pode se referir diretamente como FileName BlobName.FileName. Com esse formato JSON, veja como seria a path propriedade no exemplo anterior:

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

Em C#, você precisaria de duas classes:

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

Criar GUIDs

A {rand-guid} expressão de associação cria um GUID. O caminho de blob a seguir em um function.json arquivo cria um blob com um nome como 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

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

Hora atual

A expressão DateTime de ligação é resolvida para DateTime.UtcNow. O caminho de blob a seguir em um function.json arquivo cria um blob com um nome como 2018-02-16T17-59-55Z.txt.

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

Vinculação em tempo de execução

Em C# e outras linguagens .NET, você pode usar um padrão de vinculação imperativa, em oposição às associações declarativas em function.json e atributos. A vinculação imperativa é útil quando os parâmetros de vinculação precisam ser calculados em tempo de execução em vez de tempo de design. Para saber mais, consulte a referência do desenvolvedor C# ou a referência do desenvolvedor de script C#.

Conteúdos relacionados