SendGrid-Bindungen in Azure Functions

Artikel
04/07/2024

Dieser Artikel erläutert das Senden von E-Mail-Nachrichten mithilfe von SendGrid-Bindungen in Azure Functions. Azure Functions bietet eine Ausgabebindung für SendGrid.

Dies sind Referenzinformationen für Azure Functions-Entwickler. Falls Sie mit Azure Functions noch nicht vertraut sind, beginnen Sie mit den folgenden Ressourcen:

Entwicklerreferenz zu Azure Functions

Erstellen Ihrer ersten Funktion
Referenzen für C#-Entwickler:

Installieren der Erweiterung

Das NuGet-Erweiterungspaket, das Sie installieren, hängt vom C#-Modus ab, den Sie in Ihrer Funktions-App verwenden:

Isoliertes Workermodell
In-Process-Modell

Funktionen werden in einem isolierten C#-Workerprozess ausgeführt. Weitere Informationen finden Sie im Leitfaden zum Ausführen von Azure Functions (C#) in einem isolierten Workerprozess.

Die Funktionalität der Erweiterung ist abhängig von der Erweiterungsversion unterschiedlich:

Fügen Sie ihrem Projekt die Erweiterung hinzu, indem Sie das NuGet-Paket, Version 3.x, installieren.

Installieren des Pakets

Ab Functions Version 2.x ist die HTTP-Erweiterung Teil eines Erweiterungspakets, das in Ihrer Projektdatei „host.json“ angegeben wird. Weitere Informationen finden Sie unter Erweiterungspakete.

Paket v2.x
Functions 1.x

Diese Version der Erweiterung sollte bereits für Ihre Funktions-App mit dem Erweiterungspaket, Version 2.x, verfügbar sein.

Beispiel

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden.
In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird.
C#-Skript: Wird hauptsächlich beim Erstellen von C#-Funktionen im Azure-Portal verwendet.

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Isoliertes Workermodell
In-Process-Modell

Derzeit gibt es kein Beispiel für die Verwendung der SendGrid-Bindung in einer Funktions-App, die in einem isolierten Workerprozess ausgeführt wird.

Die folgenden Beispiele zeigen eine C#-Funktion, die einen Service Bus-Warteschlangentrigger und eine SendGrid-Ausgabebindung verwendet.

Das folgende Beispiel zeigt eine synchrone Ausführung:

using SendGrid.Helpers.Mail;
using System.Text.Json;

...

[FunctionName("SendEmail")]
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] Message email,
    [SendGrid(ApiKey = "CustomSendGridKeyAppSettingName")] out SendGridMessage message)
{
    var emailObject = JsonSerializer.Deserialize<OutgoingEmail>(Encoding.UTF8.GetString(email.Body));

    message = new SendGridMessage();
    message.AddTo(emailObject.To);
    message.AddContent("text/html", emailObject.Body);
    message.SetFrom(new EmailAddress(emailObject.From));
    message.SetSubject(emailObject.Subject);
}

public class OutgoingEmail
{
    public string To { get; set; }
    public string From { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

Das folgende Beispiel zeigt eine asynchrone Ausführung:

using SendGrid.Helpers.Mail;
using System.Text.Json;

...

[FunctionName("SendEmail")]
public static async Task Run(
 [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] Message email,
 [SendGrid(ApiKey = "CustomSendGridKeyAppSettingName")] IAsyncCollector<SendGridMessage> messageCollector)
{
    var emailObject = JsonSerializer.Deserialize<OutgoingEmail>(Encoding.UTF8.GetString(email.Body));

    var message = new SendGridMessage();
    message.AddTo(emailObject.To);
    message.AddContent("text/html", emailObject.Body);
    message.SetFrom(new EmailAddress(emailObject.From));
    message.SetSubject(emailObject.Subject);

    await messageCollector.AddAsync(message);
}

public class OutgoingEmail
{
    public string To { get; set; }
    public string From { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

Sie müssen die ApiKey-Eigenschaft des Attributs nicht festlegen, wenn Ihr API-Schlüssel in einer App-Einstellung mit dem Namen „AzureWebJobsSendGridApiKey“ enthalten ist.

Das folgende Beispiel zeigt eine SendGrid-Ausgabebindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet.

Bindungsdaten in der Datei function.json:

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

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Der JavaScript-Code sieht wie folgt aus:

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

Vollständige PowerShell-Beispiele sind derzeit für SendGrid-Bindungen nicht verfügbar.

Das folgende Beispiel zeigt eine HTTP-ausgelöste Funktion, die mithilfe der SendGrid-Bindung eine E-Mail sendet. Sie können Standardwerte in der Bindungskonfiguration angeben. Beispielsweise wird die E-Mail-Adresse des Absenders (Von) in function.json konfiguriert.

{
  "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"
    }
  ]
}

Die folgende Funktion zeigt, wie Sie benutzerdefinierte Werte für optionale Eigenschaften bereitstellen können.

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

Im folgenden Beispiel wird die @SendGridOutput-Anmerkung aus der Java-Funktions-Laufzeitbibliothek zum Senden einer E-Mail mithilfe der SendGrid-Ausgabebindung verwendet.

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

Attributes

Sowohl von C#-Bibliotheken des Typs In-Process als auch des Typs Isolierter Workerprozess werden Attribute verwendet, um die Ausgabebindung zu definieren. Vom C#-Skript wird stattdessen die Konfigurationsdatei function.json verwendet.

Isoliertes Workermodell
In-Process-Modell

Bei Funktions-Apps vom Typ Isolierter Workerprozess unterstützt SendGridOutputAttribute die folgenden Parameter:

Attribute/Annotation-Eigenschaft	BESCHREIBUNG
ApiKey	Der Name einer App-Einstellung, die Ihren API-Schlüssel enthält. Wenn sie nicht festgelegt wird, lautet der Standardname der App-Einstellung `AzureWebJobsSendGridApiKey`.
An	(Optional) Die E-Mail-Adresse des Empfängers.
From	(Optional) Die E-Mail-Adresse des Absenders.
Subject	(Optional) Der Betreff der E-Mail.
Text	(Optional) Der Inhalt der E-Mail.

In-Process-Funktions-Apps verwenden das SendGridAttribute, das die folgenden Parameter unterstützt.

Attribute/Annotation-Eigenschaft	BESCHREIBUNG
ApiKey	Der Name einer App-Einstellung, die Ihren API-Schlüssel enthält. Wenn sie nicht festgelegt wird, lautet der Standardname der App-Einstellung `AzureWebJobsSendGridApiKey`.
An	(Optional) Die E-Mail-Adresse des Empfängers.
From	(Optional) Die E-Mail-Adresse des Absenders.
Subject	(Optional) Der Betreff der E-Mail.
Text	(Optional) Der Inhalt der E-Mail.

Anmerkungen

Mit der SendGridOutput-Anmerkung können Sie die SendGrid-Bindung deklarativ konfigurieren, indem Sie die folgenden Konfigurationswerte bereitstellen.

Konfiguration

In der folgenden Tabelle sind die Bindungskonfigurationseigenschaften aufgeführt, die in der Datei function.json und dem Attribut bzw. der Anmerkung SendGrid verfügbar sind.

function.json-Eigenschaft	BESCHREIBUNG
type	Muss auf `sendGrid` festgelegt sein.
direction	Muss auf `out` festgelegt sein.
name	Der Variablenname, der im Funktionscode für die Anforderung oder den Anforderungstext verwendet wird. Dieser Wert ist `$return`, wenn es nur einen Rückgabewert gibt.
apiKey	Der Name einer App-Einstellung, die Ihren API-Schlüssel enthält. Wenn sie nicht festgelegt wird, lautet der Standardname der App-Einstellung AzureWebJobsSendGridApiKey.
to	(Optional) Die E-Mail-Adresse des Empfängers.
from	(Optional) Die E-Mail-Adresse des Absenders.
subject	(Optional) Der Betreff der E-Mail.
text	(Optional) Der Inhalt der E-Mail.

Optionale Eigenschaften können in der Bindung definierte Standardwerte aufweisen und programmgesteuert hinzugefügt oder überschrieben werden.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Einstellungen für „host.json“

In diesem Abschnitt werden die für diese Bindung verfügbaren Konfigurationseinstellungen in Version 2.x und höher beschrieben. Einstellungen in der Datei „host.json“ gelten für alle Funktionen in einer Funktions-App-Instanz. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x und höhere Versionen für diese Bindung. Weitere Informationen zu den Konfigurationseinstellungen für Funktions-Apps in Version 2.x und höher finden Sie unter host.json-Referenz für Azure Functions.

Hinweis

Eine Referenz für „host.json“ in Functions 1.x finden Sie unter host.json-Referenz für Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "sendGrid": {
            "from": "Azure Functions <samples@functions.com>"
        }
    }
}

Eigenschaft	Standard	BESCHREIBUNG
from	–	E-Mail-Adresse des Absenders für alle Funktionen.

Nächste Schritte

Konzepte für Azure Functions-Trigger und -Bindungen

Freigeben über