Associações do SendGrid no Azure Functions

  • Artigo

Este artigo explica como enviar emails usando as associações de SendGrid no Azure Functions. O Azure Functions suporta uma associação de saída para o SendGrid.

Essas são as informações de referência para desenvolvedores do Azure Functions. Se for novo no Azure Functions, comece com os seguintes recursos:

Instalar a extensão

O pacote NuGet da extensão instalado depende do modo C# usado no aplicativo de funções:

As funções são executadas em um processo de trabalho do C# isolado. Para saber mais, confira o Guia para executar C# do Azure Functions em um processo de trabalho isolado.

A funcionalidade da extensão varia de acordo com a versão da extensão:

Adicione a extensão ao seu projeto instalando o pacote NuGet, versão 3.x.

Instalar pacote

A partir da versão Funções 2.x, a extensão HTTP faz parte de um pacote de extensão, que é especificado no arquivo de projeto host.json. Para saber mais, confira pacotes de extensão.

Esta versão da extensão já deve estar disponível para seu aplicativo de funções com o pacote de extensão na versão 2.x.

Exemplo

A função C# pode ser criada por meio de um dos seguintes modos C#:

  • Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework.
  • Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions.
  • Script C#: usado principalmente ao criar funções C# no portal do Azure.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Atualmente, não há um exemplo para usar a associação SendGrid em um aplicativo de funções em execução em um processo de trabalho isolado.

O exemplo a seguir mostra uma associação de saída de SendGrid em um arquivo function.json e uma função JavaScript que usa a associação.

Aqui estão os dados de associação no arquivo function.json:

{
    "bindings": [
        {
            "name": "$return",
            "type": "sendGrid",
            "direction": "out",
            "apiKey" : "MySendGridKey",
            "to": "{ToEmail}",
            "from": "{FromEmail}",
            "subject": "SendGrid output bindings"
        }
    ]
}

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

Aqui está o código JavaScript:

module.exports = function (context, input) {
    var message = {
        "personalizations": [ { "to": [ { "email": "sample@sample.com" } ] } ],
        from: { email: "sender@contoso.com" },
        subject: "Azure news",
        content: [{
            type: 'text/plain',
            value: input
        }]
    };

    return message;
};

Exemplos completos do PowerShell não estão disponíveis atualmente para as associações do SendGrid.

O exemplo a seguir mostra uma função disparada por HTTP que envia um email usando a associação SendGrid. Você pode fornecer valores padrão na configuração da associação. Por exemplo, o endereço de email de origem é configurado em function.json.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "type": "httpTrigger",
      "authLevel": "function",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "sendGrid",
      "name": "sendGridMessage",
      "direction": "out",
      "apiKey": "SendGrid_API_Key",
      "from": "sender@contoso.com"
    }
  ]
}

A função a seguir mostra como você pode fornecer valores personalizados para propriedades opcionais.

import logging
import json
import azure.functions as func

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

    value = "Sent from Azure Functions"

    message = {
        "personalizations": [ {
          "to": [{
            "email": "user@contoso.com"
            }]}],
        "subject": "Azure Functions email with SendGrid",
        "content": [{
            "type": "text/plain",
            "value": value }]}

    sendGridMessage.set(json.dumps(message))

    return func.HttpResponse(f"Sent")

O exemplo a seguir usa a anotação @SendGridOutput da @SendGridOutput para enviar um email usando a associação de saída SendGrid.

package com.function;

import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerSendGrid {

    @FunctionName("HttpTriggerSendGrid")
    public HttpResponseMessage run(

        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.GET, HttpMethod.POST },
            authLevel = AuthorizationLevel.FUNCTION)
                HttpRequestMessage<Optional<String>> request,

        @SendGridOutput(
            name = "message",
            dataType = "String",
            apiKey = "SendGrid_API_Key",
            to = "user@contoso.com",
            from = "sender@contoso.com",
            subject = "Azure Functions email with SendGrid",
            text = "Sent from Azure Functions")
                OutputBinding<String> message,

        final ExecutionContext context) {

        final String toAddress = "user@contoso.com";
        final String value = "Sent from Azure Functions";

        StringBuilder builder = new StringBuilder()
            .append("{")
            .append("\"personalizations\": [{ \"to\": [{ \"email\": \"%s\"}]}],")
            .append("\"content\": [{\"type\": \"text/plain\", \"value\": \"%s\"}]")
            .append("}");

        final String body = String.format(builder.toString(), toAddress, value);

        message.setValue(body);

        return request.createResponseBuilder(HttpStatus.OK).body("Sent").build();
    }
}

Atributos

Ambas as bibliotecas C# em processo e no processo de trabalho isolado usam atributos para definir a associação de saída. Em vez disso, o script C# usa um arquivo de configuração function.json.

Em aplicativos de funções do processo de trabalho isolado, o SendGridOutputAttribute dá suporte para os seguintes parâmetros:

Propriedade de atributo/anotação Descrição
ApiKey O nome de uma configuração de aplicativo que contém sua chave de API. Se não estiver configurado, o nome da configuração do aplicativo padrão será AzureWebJobsSendGridApiKey.
Para (Opcional) Insira o endereço de email do destinatário.
De (Opcional) Insira o endereço de email do remetente.
Assunto (Opcional) Insira o assunto do email.
Texto (Opcional) O conteúdo do email.

Anotações

A anotação SendGridOutput permite configurar declarativamente a associação SendGrid fornecendo os valores de configuração a seguir.

Configuração

A tabela a seguir lista as propriedades de configuração de associação disponíveis no arquivo function.json e no atributo/na anotação SendGrid.

Propriedade function.json Descrição
tipo Deve ser definido como sendGrid.
direction Deve ser definido como out.
name O nome da variável usada no código da função para a solicitação ou o corpo da solicitação. Esse valor é $return quando há apenas um valor retornado.
apiKey O nome de uma configuração de aplicativo que contém sua chave de API. Se não configurado, o nome da configuração do aplicativo padrão será AzureWebJobsSendGridApiKey.
to (Opcional) Insira o endereço de email do destinatário.
from (Opcional) Insira o endereço de email do remetente.
subject (Opcional) Insira o assunto do email.
text (Opcional) O conteúdo do email.

As propriedades opcionais podem ter valores padrão definidos na associação e podem ser adicionadas ou substituídas programaticamente.

Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values.

configurações de host.json

Esta seção descreve as definições de configuração disponíveis para a associação nas versões 2.x e superiores. As configurações no arquivo host.json se aplicam a todas as funções em uma instância do aplicativo de funções. O arquivo host.json de exemplo abaixo contém apenas as configurações das versões 2.x e superiores para a associação. Para saber mais sobre as definições de configuração do aplicativo de funções nas versões 2.x e superiores, confira a referência de host.json para o Azure Functions.

Observação

Para obter uma referência de host.json no Functions 1.x, confira Referência de host.json para o Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "sendGrid": {
            "from": "Azure Functions <samples@functions.com>"
        }
    }
}
Propriedade Padrão Descrição
from N/D Endereço de email do remetente em todas as funções.

Próximas etapas

Aprenda mais sobre gatilhos e de associações do Azure Functions