Référence du développeur Go pour Azure Functions

Important

La prise en charge de Go dans Azure Functions est actuellement en préversion publique. Pendant la version préliminaire, les applications de fonction Go sont prises en charge uniquement sur le plan de consommation flexible.

Azure Functions est un service de calcul serverless que vous pouvez utiliser pour exécuter du code piloté par les événements sans provisionner ni gérer l’infrastructure. Le Worker Go vous permet d’écrire Azure Functions en mode natif dans Go, avec une intégration approfondie dans l’écosystème déclencheur Azure Functions.

Ce guide vous aide à :

• Comprendre le modèle de programmation Go
• Créer et structurer votre code de projet
• Utiliser des déclencheurs
• Déployez et exécutez votre application localement et dans Azure

Pour en savoir plus sur le développement Azure Functions en général, consultez la documentation de référence pour les développeurs Azure Functions.

Premiers pas

Choisissez l’environnement qui correspond à votre flux de travail et commencez à utiliser Azure Functions pour Go :

• Démarrage rapide de la ligne de commande

Prerequisites

• Accédez à la version 1.24 ou ultérieure
• Azure Functions Core Tools version 4.12 ou ultérieure. Exécutez func --version pour vérifier votre version installée.
• Azure CLI version 2.87.0 ou ultérieure, lorsque vous créez des ressources Azure ou déployez des packages sur Azure. Exécutez az version pour vérifier votre version installée.

Modèle de programmation

Le composant worker Go utilise un modèle de programmation axé sur le code. Vous définissez des fonctions serverless et leurs déclencheurs à l’aide de gestionnaires Go idiomatiques.

Point d’entrée

Chaque projet de code Go commence par une fonction main() qui crée un FunctionApp, enregistre des fonctions et démarre le worker :

package main

import (
    "fmt"
    "net/http"

    "github.com/azure/azure-functions-golang-worker/sdk"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()

    app.HTTP("hello", hello,
        sdk.WithMethods("GET", "POST"),
        sdk.WithAuth("anonymous"),
    )

    worker.Start(app)
}

func hello(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    fmt.Fprintf(w, "Hello, %s!", name)
}

Enregistrement de fonction

Inscrivez des fonctions à l’aide de l’API Fluent Builder avec le modèle d’options fonctionnelles. Chaque type de déclencheur a une méthode d’inscription sur l’objet App :

// HTTP trigger
app.HTTP("myHttpFunc", handler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

// Timer trigger
app.Timer("myTimerFunc", handler,
    sdk.WithSchedule("0 */5 * * * *"),
)

// Azure Cosmos DB trigger
app.CosmosDB("myCosmosFunc", handler,
    sdk.WithDatabase("mydb"),
    sdk.WithContainer("mycontainer"),
    sdk.WithConnection("CosmosDBConnection"),
)

// Azure Service Bus trigger
app.ServiceBusQueue("myServiceBusFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("ServiceBusConnection"),
)

// Event Hubs trigger
app.EventHub("myEventHubFunc", handler,
    sdk.WithEventHubName("myeventhub"),
    sdk.WithConnection("EventHubConnection"),
)

// Event Grid trigger
app.EventGrid("myEventGridFunc", handler)

// Blob trigger (extension model)
app.Blob("myBlobFunc", handler,
    sdk.WithPath("mycontainer/{name}"),
    sdk.WithConnection("AzureWebJobsStorage"),
)

Structure du projet

Un projet de code Go pour Azure Functions est un module Go standard. Lorsque vous exécutez func init --worker-runtime go, les fichiers suivants sont générés :

my-function-app/
├── host.json              # Host configuration
├── local.settings.json    # Local settings (connection strings, app settings)
├── go.mod                 # Go module file
├── go.sum                 # Go module checksums
└── main.go                # Entry point with function registrations

host.json

Le host.json fichier contient des options de configuration au niveau de l’hôte. Pour plus d’informations, consultez la référencehost.json.

local.settings.json

Le local.settings.json fichier stocke les paramètres d’application et les chaînes de connexion utilisés pendant le développement local. Ce fichier n'est pas publié dans Azure. Pour en savoir plus, voir Fichier de paramètres locaux.

Triggers

Le Worker Go classe les déclencheurs en deux niveaux en fonction de leurs besoins en dépendances :

Déclencheurs principaux

Les déclencheurs principaux reçoivent leur charge utile inline via gRPC. L’hôte Azure Functions sérialise les données du déclencheur en message gRPC, et le processus de travail les désérialise en structures Go typées. Ces déclencheurs ont :

• Signatures de gestionnaire typées avec sécurité au moment de la compilation
• Aucune dépendance externe au SDK Azure : seul encoding/json est requis
• Charges utiles limitées : les documents de flux de modification, les messages et les événements sont des objets discrets et limités à la taille

Déclencheurs principaux pris en charge :

Déclencheur	Signature du gestionnaire	Méthode d’inscription
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB, une base de données distribuée globale	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus (File d’attente)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (Rubrique)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Déclencheurs d’extension

Les déclencheurs d’extension fournissent un client Kit de développement logiciel (SDK) Azure authentifié au lieu de données brutes. L’hôte envoie uniquement les métadonnées (par exemple, le nom du conteneur et le chemin d’accès de l’objet blob), et le worker construit un client délimité à la ressource spécifique. Ces déclencheurs ont :

• Injection de client sdk : le gestionnaire reçoit un client prêt à l’emploi
• Dépendances isolées : les packages du SDK Azure se trouvent dans triggers/<name>/
• Prise en charge de la diffusion en continu : permet de lire des charges utiles volumineuses sans effectuer de mise en mémoire tampon via gRPC

Pour utiliser un déclencheur d’extension, ajoutez une importation vide pour le package d’extension :

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"

Déclencheur	Gestionnaire de réception	Méthode d’inscription
Stockage Blob	*blob.Client	app.Blob()

Exemple de déclencheur Blob

package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob"
    "github.com/azure/azure-functions-golang-worker/sdk"
    _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()
    app.Blob("processBlobTrigger", processBlob,
        sdk.WithPath("samples-workitems/{name}"),
        sdk.WithConnection("AzureWebJobsStorage"),
    )
    worker.Start(app)
}

func processBlob(ctx context.Context, client *blob.Client) error {
    get, err := client.DownloadStream(ctx, nil)
    if err != nil {
        return fmt.Errorf("download error: %w", err)
    }
    data, _ := io.ReadAll(get.Body)
    get.Body.Close()
    log.Printf("Blob size: %d bytes", len(data))
    return nil
}

Déclencheurs HTTP

Les gestionnaires de déclencheurs HTTP utilisent des types Go net/http standard, ce qui les rend immédiatement familiers aux développeurs Go :

func myHandler(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    w.Header().Set("Content-Type", "application/json")
    fmt.Fprintf(w, `{"message": "Hello, %s!"}`, name)
}

Inscrire des fonctions HTTP avec des méthodes et un niveau d’autorisation :

app.HTTP("myApi", myHandler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

Diffusion en continu HTTP

Go Worker prend en charge le streaming HTTP pour les scénarios tels que les événements envoyés par le serveur ou l’envoi de données de réponse volumineuses :

func streamHandler(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming not supported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream")
    for i := 0; i < 10; i++ {
        fmt.Fprintf(w, "data: message %d\n\n", i)
        flusher.Flush()
    }
}

Déclencheur de minuteur

Les déclencheurs de minuteur s’exécutent selon une planification définie par une expression cron :

app.Timer("myScheduledFunc", timerHandler,
    sdk.WithSchedule("0 */5 * * * *"),
)

func timerHandler(ctx context.Context, timer bindings.TimerInfo) error {
    log.Printf("Timer trigger executed at: %s", timer.ScheduleStatus.Next)
    return nil
}

Gestion des dépendances

Les projets de code Go utilisent des modules Go standard pour la gestion des dépendances.

1. Initialiser un nouveau module :

   go mod init myapp
   

2. Ajoutez le kit de développement logiciel (SDK) du worker Go pour Azure Functions :

   go get github.com/azure/azure-functions-golang-worker
   

   Pour la prise en charge du déclencheur Blob, la dépendance est incluse automatiquement via l’import vide de triggers/blob.

3. Nettoyer les dépendances :

   go mod tidy
   

Exécuter en local

Utilisez Azure Functions Core Tools pour exécuter votre projet localement :

func start

Outils de base automatiquement :

1. Détecte FUNCTIONS_WORKER_RUNTIME = "native" à partir de local.settings.json.
2. Résout le runtime du worker natif en Go lorsqu’un fichier go.mod est présent.
3. S’exécute go build -o bin/app . pour compiler votre projet pour votre système d’exploitation local.
4. Démarre l’hôte Azure Functions, qui communique avec le binaire compilé sur gRPC.
5. Affiche vos points de terminaison de fonction (par exemple, http://localhost:7071/api/hello).

Permet local.settings.json de configurer des variables d’environnement pour le développement local :

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "",
        "FUNCTIONS_WORKER_RUNTIME": "native"
    }
}

La valeur générée AzureWebJobsStorage est vide pour les projets Go. Définissez-la sur une chaîne de connexion à un compte de stockage ou UseDevelopmentStorage=true lorsque vous utilisez des déclencheurs qui nécessitent un stockage de l’hôte pendant le développement local.

Deployment

Compilation et empaquetage

Azure Functions version Core Tools 4.12 ou version ultérieure gère les builds Go pour les flux de déploiement locaux et Azure courants :

• func start génère votre projet en tant que bin/application pour votre système d’exploitation local avant de démarrer l’hôte Functions local.
• func azure functionapp publish génère, empaquette et déploie votre projet dans une application de fonctions existante dans Azure.
• func pack génère votre projet en tant que bin/app pour Linux x64 et crée un package .zip déployable.

Lors de l’empaquetage de Azure, le fichier .zip généré contient les fichiers nécessaires à l’hôte Linux Functions. Le fichier binaire compilé est stocké en tant que fichier bin/application dans votre projet local, mais Core Tools le place à la racine du package de déploiement en tant qu’application.

Si vous utilisez func pack --no-build, vous devez générer le binaire Linux x64 avant d’empaqueter :

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/app .

Déployer avec Core Tools

Utilisez func azure functionapp publish pour déployer votre projet Go sur une application de fonction existante dans Azure :

func azure functionapp publish <APP_NAME>

Remplacez <APP_NAME> par le nom de votre application de fonction.

Déployer un package zip

Utilisez func pack quand vous devez créer un package de déploiement séparément de la publication :

1. Créez un artefact zip déployable :

   func pack
   

2. Déployez le package à l’aide de la Azure CLI :

   az functionapp deployment source config-zip --resource-group <RESOURCE_GROUP> --name <APP_NAME> --src <ZIP_FILE_PATH>
   

Le package produit par func pack est prêt à s'exécuter dans Azure. Ne demandez donc pas de build distante lorsque vous le déployez.

Prise en charge de Docker

Vous pouvez exécuter des projets de code Go dans des conteneurs. Initialisez un projet avec la prise en charge de Docker :

func init --worker-runtime go --docker

La commande génère un Dockerfile ainsi que les fichiers de projet standard.

Télémétrie et observabilité

Le Worker Go d’Azure Functions prend en charge la journalisation structurée et l’observabilité basée sur OpenTelemetry. Utilisez des méthodes prenant en compte le contexte du package standard log/slog, telles que slog.InfoContext, pour mettre en corrélation les journaux avec l’appel de fonction actuel. Pour activer OpenTelemetry, configurez l’hôte Functions et inscrivez l’intergiciel Go Worker OpenTelemetry dans votre application. Pour obtenir des instructions de configuration, consultez Use OpenTelemetry avec Azure Functions.

Limitations connues (préversion)

Pendant la préversion publique, les limitations suivantes s’appliquent :

• func new n’est pas pris en charge. Ajoutez des fonctions en modifiant main.go directement.
• Durable Functions n’est pas pris en charge pour Go pendant la version préliminaire publique.
• Les applications de fonction Go s’exécutent sur Linux uniquement dans Azure.
• Seuls les déclencheurs répertoriés dans Triggers sont pris en charge dans le cadre de la préversion.
• La création de packages Go dans Core Tools cible actuellement les applications pour Linux x64.

Étapes suivantes

• Créer votre première fonction Go
• Les déclencheurs et les liaisons d'Azure Functions
• Utilisez OpenTelemetry avec Azure Functions
• Exemples du worker Go pour Azure Functions
• Guide du développeur Azure Functions