Associações de saída de Armazenamento de Fila do Azure para o Azure Functions

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

O modelo de programação v1 do Python requer que você defina as associações em um arquivo function.json separado na pasta de funções. Para saber mais, confira o Guia do desenvolvedor do Python.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

O exemplo a seguir mostra uma função C# que cria uma mensagem da fila para cada solicitação HTTP recebida.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

O exemplo a seguir mostra uma função TypeScript disparada por HTTP que cria um item da fila para cada solicitação HTTP recebida.

import { app, HttpRequest, HttpResponseInit, InvocationContext, output } from '@azure/functions';

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Os exemplos de TypeScript não estão documentados para o modelo v3.

O exemplo a seguir mostra uma função JavaScript disparada por HTTP que cria um item da fila para cada solicitação HTTP recebida.

const { app, output } = require('@azure/functions');

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

• Conectar funções ao Armazenamento do Azure usando o Visual Studio Code
• Conectar funções ao Armazenamento do Azure usando ferramentas de linha de comando

O exemplo a seguir mostra uma associação de gatilho HTTP em um arquivo function.json e uma função JavaScript que usa a associação. A função cria um item da fila para cada solicitação HTTP recebida.

Aqui está o arquivo function.json:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

A seção configuração explica essas propriedades.

Aqui está o código JavaScript:

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

Você pode enviar várias mensagens de uma vez com a definição de uma matriz de mensagem para a myQueueItem associação de saída. O código JavaScript a seguir envia duas mensagens de fila com valores codificados para cada solicitação HTTP recebida.

module.exports = async function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
};

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Para obter um exemplo de ponta a ponta de como configurar uma ligação de saída para o armazenamento de filas, consulte um destes artigos:

• Conectar funções ao Armazenamento do Azure usando o Visual Studio Code
• Conectar funções ao Armazenamento do Azure usando ferramentas de linha de comando

Uma associação de fila de Armazenamento é definida em function.json, em que o tipo é definido como queue.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Para definir uma mensagem individual na fila, você passa um único valor para o método set.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Para criar várias mensagens na fila, declare um parâmetro como o tipo de lista apropriado e passe uma matriz de valores (que correspondam ao tipo de lista) para o método set.

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Ao executar em um processo de trabalho isolado, você usa QueueOutputAttribute, que leva o nome da fila, conforme mostrado no exemplo a seguir:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Somente as variáveis retornadas têm suporte durante a execução em um processo de trabalho isolado. Parâmetros de saída não podem ser usados.

Em bibliotecas de classes do C#, use o QueueAttribute. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia do script C#.

O atributo se aplica a um out parâmetro ou o valor de retorno da função. O construtor do atributo usa o nome da fila, conforme mostrado no exemplo a seguir:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Você pode definir a Connection propriedade para especificar a conta de armazenamento para usar, conforme mostrado no exemplo a seguir:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Você pode usar o StorageAccount atributo para especificar a conta de armazenamento no nível de classe, método ou parâmetro. Para obter mais informações, confira Gatilho – atributos.

A tabela a seguir explica as propriedades que você pode definir no objeto options transmitido para o método output.storageQueue().

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Uma função C# compilada da biblioteca de classes do processo de trabalho isolado é executada em um processo isolado do runtime.

Uma biblioteca de classes em processo é uma função C# compilada no mesmo processo que o runtime do Functions.

Grave uma mensagem de fila única usando um parâmetro de método como o out T paramName. Você pode usar o tipo de retorno de método em vez de um out parâmetro, e T pode ser qualquer um dos seguintes tipos:

• Um objeto serializado como JSON
• string
• byte[]
• QueueMessage

Para obter exemplos de como usar esses tipos, confira o repositório GitHub da extensão.

Você pode gravar várias mensagens na fila usando um dos seguintes tipos:

• ICollector<T> ou IAsyncCollector<T>
• QueueClient

Para obter exemplos de como usar o QueueMessage, e o QueueClient, confira o repositório GitHub da extensão.

Embora o atributo use uma propriedade Connection, não é possível usar Connection para especificar uma conexão da conta de armazenamento. Isso pode ser feito quando for necessário usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

A conta de armazenamento a ser usada é determinada na seguinte ordem:

• A propriedade Connection do atributo de gatilho ou associação.
• O atributo StorageAccount aplicado ao mesmo parâmetro do atributo de gatilho ou associação.
• O StorageAccount atributo aplicado à função.
• O StorageAccount atributo aplicado à classe.
• A conta de armazenamento padrão do aplicativo de funções, que é definido na configuração do aplicativo AzureWebJobsStorage.

Grave uma mensagem de fila única usando um parâmetro de método como o out T paramName. Você pode usar o tipo de retorno de método em vez de um out parâmetro, e T pode ser qualquer um dos seguintes tipos:

• Um objeto serializado como JSON
• string
• byte[]
• CloudQueueMessage

Se você tentar associar CloudQueueMessage e receber uma mensagem de erro, certifique-se de ter uma referência para a versão correta do SDK do Armazenamento.

Você pode gravar várias mensagens na fila usando um dos seguintes tipos:

• ICollector<T> ou IAsyncCollector<T>
• CloudQueue

Embora o atributo use uma propriedade Connection, não é possível usar Connection para especificar uma conexão da conta de armazenamento. Isso pode ser feito quando for necessário usar uma conta de armazenamento diferente de outras funções na biblioteca. O construtor toma o nome de uma configuração de aplicativo que contenha uma cadeia de conexão de armazenamento. O atributo pode ser aplicado no nível de classe, método ou parâmetro. O exemplo a seguir mostra o nível de classe e método:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

A conta de armazenamento a ser usada é determinada na seguinte ordem:

• A propriedade Connection do atributo de gatilho ou associação.
• O atributo StorageAccount aplicado ao mesmo parâmetro do atributo de gatilho ou associação.
• O StorageAccount atributo aplicado à função.
• O StorageAccount atributo aplicado à classe.
• A conta de armazenamento padrão do aplicativo de funções, que é definido na configuração do aplicativo AzureWebJobsStorage.

Quando você desejar que a função escreva uma única mensagem, a associação de saída da fila pode ser associada aos seguintes tipos:

Quando você deseja que a função escreva várias mensagens, a associação de saída da fila pode ser associada aos seguintes tipos:

Para outros cenários de saída, crie e use um QueueClient com outros tipos de Azure.Storage.Queues diretamente. Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente do SDK do Azure.

Atualmente, o processo de trabalho isolado dá suporte apenas para associação a parâmetros de cadeia de caracteres.

Acesse o item da fila de saída retornando o valor diretamente ou usando context.extraOutputs.set(). Você pode usar uma cadeia de caracteres ou um objeto serializável em JSON para o conteúdo de item de fila.

Acesse o item da fila de saída usando context.bindings.<name>, em que <name> é o valor especificado na propriedade name de function.json. Você pode usar uma cadeia de caracteres ou um objeto serializável em JSON para o conteúdo de item de fila.