Dela via

Go-konfigurationsprovider

Azure App Configuration är en hanterad tjänst som hjälper utvecklare att centralisera sina programkonfigurationer enkelt och säkert. Med go-konfigurationsproviderbiblioteket kan du läsa in konfiguration från ett Azure App Configuration-arkiv på ett hanterat sätt. Det här klientbiblioteket lägger till ytterligare funktioner ovanpå Azure SDK för Go.

Läs in konfiguration

Med Azure App Configuration Go-providern kan du läsa in konfigurationsvärden från Azure App Configuration Store till dina Go-program. Du kan ansluta med antingen Microsoft Entra-ID-autentisering eller en anslutningssträng.

Om du vill använda Go-konfigurationsprovidern installerar du paketet:

go get github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration

Du anropar Load funktionen från azureappconfiguration paketet för att läsa in konfigurationen från Azure App Configuration. Funktionen Load accepterar autentiseringsalternativ och konfigurationsalternativ för att anpassa inläsningsbeteendet.

Du kan använda DefaultAzureCredential, eller någon annan implementering av tokenautentiseringsuppgifter, för att autentisera dig mot appkonfigurationslagringen. Följ anvisningarna för att tilldela dina autentiseringsuppgifter rollen App Configuration Data Reader .

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
	ctx := context.Background()
	
	// Get the endpoint from environment variable
	endpoint := os.Getenv("AZURE_APPCONFIG_ENDPOINT")
	
	// Create a credential using DefaultAzureCredential
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("Failed to create credential: %v", err)
	}

	// Set up authentication options
	authOptions := azureappconfiguration.AuthenticationOptions{
		Endpoint:   endpoint,
		Credential: credential,
	}

	// Load configuration from Azure App Configuration
	appConfig, err := azureappconfiguration.Load(ctx, authOptions, nil)
	if err != nil {
		log.Fatalf("Failed to load configuration: %v", err)
	}
}

Läs in specifika nyckelvärden med hjälp av väljare

Som standard läser konfigurationsprovidern in alla nyckelvärden utan etikett från App Configuration. Du kan selektivt läsa in nyckelvärden genom att Selectors konfigurera fältet i structen Options .

options := &azureappconfiguration.Options{
	Selectors: []azureappconfiguration.Selector{
		{
			// Load configuration values with prefix "App:" and no label
			KeyFilter:   "App:*",
			LabelFilter: "",
		},
		{
			// Load configuration values with prefix "App:" and "Prod" label
			KeyFilter:   "App:*",
			LabelFilter: "Prod",
		},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Structen Selector stöder följande fält:

  • KeyFilter: Avgör vilka konfigurationsnycklar som ska ingå. Använd exakta matchningar, prefixmatchning med *, eller kommaavgränsade flera nycklar.
  • LabelFilter: Väljer nyckelvärden med en specifik etikett. Om det är tomt läser du in nyckelvärden utan etikett.

Anmärkning

När flera väljare innehåller överlappande nycklar har senare väljare företräde framför tidigare.

Filter för taggar

Parametern TagFilters väljer nyckelvärden med specifika taggar. Ett nyckelvärde läses bara in om alla taggar och motsvarande värden anges i filtren.

options := &azureappconfiguration.Options{
	Selectors: []azureappconfiguration.Selector{
		{
			// Load configuration values with prefix "App:" and specific tags
			KeyFilter:   "App:*",
			TagFilters: []string{"env=prod"},
		},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Anmärkning

Tecknen asterisk (*), kommatecken (,) och omvänt snedstreck (\) är reserverade och måste vara undantagna med ett omvänt snedstreck när de används i ett taggfilter.

Trimma prefix från nycklar

När du läser in konfigurationsvärden med specifika prefix kan du använda TrimKeyPrefixes alternativet för att ta bort dessa prefix från nycklarna i konfigurationen. Detta skapar renare konfigurationsnycklar i ditt program samtidigt som du bibehåller organisationen i App Configuration-lagret.

options := &azureappconfiguration.Options{
	// Load configuration values with prefix "TestApp:" and trim the prefix
	Selectors: []azureappconfiguration.Selector{
		{
			KeyFilter: "TestApp:*",
		},
	},
	TrimKeyPrefixes: []string{"TestApp:"},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Om appkonfigurationsarkivet till exempel innehåller en nyckel med namnet TestApp:Settings:Message kommer det att vara tillgängligt i din applikation som Settings:Message efter att prefixet TestApp: har trimmats.

Hantering av JSON-innehållstyp

Du kan skapa JSON-nyckelvärden i App Configuration. När ett nyckelvärde med innehållstypen "application/json" läss parsas konfigurationsprovidern i kapslade strukturer. Mer information finns i Använda innehållstyp för att lagra JSON-nyckelvärden i App Configuration.

Anmärkning

Från och med version 1.2.0 tillåter konfigurationsprovidern kommentarer, enligt definitionen i (JSONC), i nyckelvärden med en application/json innehållstyp.

Använda konfiguration

Den AzureAppConfiguration typ som returneras av Load funktionen innehåller flera metoder för att komma åt dina konfigurationsdata:

Unmarshal till structs

Metoden Unmarshal ger ett typsäkert sätt att läsa in konfigurationsvärden i Go-structs. Den här metoden förhindrar körningsfel från feltypade konfigurationsnycklar och gör koden mer underhållsbar. Metoden accepterar en valfri ConstructionOptions parameter för att anpassa hur konfigurationsnycklar mappas till structfält.

type Config struct {
	Message string
	App     struct {
		Name     string
		Debug    bool
		Settings struct {
			Timeout    int
			RetryCount int
		}
	}
}

func main() {
	// ... load configuration ...
	
	// Create a configuration struct and unmarshal into it
	var config Config
	if err := appConfig.Unmarshal(&config, nil); err != nil {
		log.Fatalf("Failed to unmarshal configuration: %v", err)
	}

	// Access configuration values
	fmt.Printf("Message: %s\n", config.Message)
	fmt.Printf("App Name: %s\n", config.App.Name)
	fmt.Printf("Debug Mode: %t\n", config.App.Debug)
	fmt.Printf("Timeout: %d seconds\n", config.App.Settings.Timeout)
}

Anpassade nyckelavgränsare

Du kan anpassa hur konfigurationsnycklar mappas till structfält med hjälp av ConstructionOptions. Det här är användbart när konfigurationsnycklarna använder andra avgränsare än standardpunkten (.):

// Configuration keys using colon separator: "App:Name", "App:Settings:Timeout"
constructionOptions := &azureappconfiguration.ConstructionOptions{
	Separator: ":",
}

var config Config
if err := appConfig.Unmarshal(&config, constructionOptions); err != nil {
	log.Fatalf("Failed to unmarshal configuration: %v", err)
}

Structen ConstructionOptions stöder följande avgränsare: ., ,, ;, -, _, , __, /, . : Om det inte anges används standardavgränsaren . .

Hämta råa JSON-byte

Metoden GetBytes hämtar din konfiguration som råa JSON-data, vilket ger flexibilitet för integrering med JSON-bearbetningsbibliotek eller konfigurationsramverk som viper. Den här metoden accepterar också en valfri ConstructionOptions parameter för att styra nyckelhierarkimappning.

// Get configuration as JSON bytes with default separator
jsonBytes, err := appConfig.GetBytes(nil)
if err != nil {
	log.Fatalf("Failed to get configuration as bytes: %v", err)
}

fmt.Println("Raw JSON Configuration:")
fmt.Println(string(jsonBytes))

// Get configuration with custom separator
constructionOptions := &azureappconfiguration.ConstructionOptions{
	Separator: ":",
}
jsonBytes, err = appConfig.GetBytes(constructionOptions)
if err != nil {
	log.Fatalf("Failed to get configuration as bytes: %v", err)
}

// Example: Use with viper
v := viper.New()
v.SetConfigType("json")
if err := v.ReadConfig(bytes.NewBuffer(jsonBytes)); err != nil {
	log.Fatalf("Failed to read config into viper: %v", err)
}

Uppdatering av konfiguration

Genom att konfigurera uppdatering kan programmet hämta de senaste värdena från App Configuration Store utan att behöva starta om. Du kan konfigurera uppdateringsalternativ med hjälp RefreshOptions av fältet i structen Options . Den inlästa konfigurationen uppdateras när alla ändringar av valda nyckelvärden identifieras på servern. Som standard används ett uppdateringsintervall på 30 sekunder, men du kan åsidosätta det med Interval egenskapen .

options := &azureappconfiguration.Options{
	// Load all keys that start with `TestApp:` and have no label
	Selectors: []azureappconfiguration.Selector{
		{
			KeyFilter:   "TestApp:*",
			LabelFilter: "",
		},
	},
	// Trigger full configuration refresh when any selected key changes
	RefreshOptions: azureappconfiguration.KeyValueRefreshOptions{
		Enabled:  true,
		// Check for changes no more often than every 60 seconds
		Interval: 60 * time.Second,
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Konfigurationen uppdateras inte automatiskt när du konfigurerar RefreshOptions den. Du måste anropa Refresh metoden på instansen AzureAppConfiguration för att utlösa en uppdatering.

// Trigger a refresh
if err := appConfig.Refresh(ctx); err != nil {
	log.Printf("Failed to refresh configuration: %v", err)
}

Den här designen förhindrar onödiga begäranden till App Configuration när programmet är inaktivt. Du bör inkludera anropet där programaktiviteten Refresh inträffar. Detta kallas aktivitetsdriven konfigurationsuppdatering. Du kan till exempel anropa Refresh när du bearbetar en inkommande begäran eller inuti en iteration där du utför en komplex uppgift.

Anmärkning

Även om uppdateringsanropet misslyckas av någon anledning fortsätter programmet att använda den cachelagrade konfigurationen. Ett annat försök görs när det konfigurerade uppdateringsintervallet har passerat och uppdateringsanropet utlöses av programaktiviteten. Anrop Refresh är en no-op innan det konfigurerade uppdateringsintervallet förflutit, så dess prestandapåverkan är minimal även om den anropas ofta.

Uppdatera sentinelnyckeln

En sentinel-nyckel är en nyckel som du uppdaterar när du har slutfört ändringen av alla andra nycklar. Konfigurationsprovidern övervakar sentinel-nyckeln i stället för alla valda nyckelvärden. När en ändring identifieras uppdaterar appen alla konfigurationsvärden.

Den här metoden är användbar när du uppdaterar flera nyckelvärden. Genom att uppdatera sentinel-nyckeln först när alla andra konfigurationsändringar har slutförts säkerställer du att ditt program bara läser in konfigurationen en gång till, vilket upprätthåller konsekvens.

options := &azureappconfiguration.Options{
	// Load all keys that start with `TestApp:` and have no label
	Selectors: []azureappconfiguration.Selector{
		{
			KeyFilter:   "TestApp:*",
			LabelFilter: "",
		},
	},
	// Trigger full configuration refresh only if the `SentinelKey` changes
	RefreshOptions:  azureappconfiguration.KeyValueRefreshOptions{
		Enabled: true,
		WatchedSettings: []azureappconfiguration.WatchedSetting{
			{
				Key:   "SentinelKey",
				Label: "",
			},
		},
	},
}

Återanrop till anpassad uppdatering

Metoden OnRefreshSuccess registrerar en återanropsfunktion som körs när konfigurationen har uppdaterats och faktiska ändringar har identifierats.

var config Config
if err := appConfig.Unmarshal(&config, nil); err != nil {
    log.Fatalf("Failed to unmarshal configuration: %v", err)
}

// Register refresh callback
appConfig.OnRefreshSuccess(func() {
    // Re-unmarshal the configuration
    err := appConfig.Unmarshal(&config, nil)
    if err != nil {
        log.Printf("Failed to unmarshal updated configuration: %s", err)
        return
    }
})

Funktionsflaggor

Funktionsflaggor i Azure App Configuration är ett modernt sätt att styra funktionstillgängligheten i dina program. Till skillnad från vanliga konfigurationsvärden måste funktionsflaggor läsas in explicit med hjälp av FeatureFlagOptions fältet i structen Options .

options := &azureappconfiguration.Options{
	FeatureFlagOptions: azureappconfiguration.FeatureFlagOptions{
		Enabled: true,
		// Load feature flags that start with `TestApp:` and have `dev` label
		Selectors: []azureappconfiguration.Selector{
			{
				KeyFilter:   "TestApp:*",
				LabelFilter: "dev",
			},
		},
		RefreshOptions: azureappconfiguration.RefreshOptions{
			Enabled:  true,
			Interval: 60 * time.Second,
		},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Tips/Råd

När ingen väljare anges i FeatureFlagOptions, läser den in alla funktionsflaggor utan etikett i din App Configuration-butik. Standarduppdateringsintervallet för funktionsflaggor är 30 sekunder.

Viktigt!

Installera och använda featuremanagement paketet för att effektivt använda och hantera funktionsflaggor som lästs in från Azure App Configuration. Det här biblioteket är ett strukturerat sätt att styra funktionsbeteendet i ditt program.

Funktionshantering

Biblioteket Feature Management Go är ett strukturerat sätt att utveckla och exponera programfunktioner baserat på funktionsflaggor. Funktionshanteringsbiblioteket är utformat för att fungera tillsammans med konfigurationsproviderbiblioteket.

Om du vill använda funktionsflaggor med funktionshanteringsbiblioteket installerar du de paket som krävs:

go get github.com/microsoft/Featuremanagement-Go/featuremanagement
go get github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig

I följande exempel visas hur du integrerar funktionshanteringsbiblioteket med konfigurationsprovidern för att dynamiskt styra funktionstillgängligheten:

import (
	"github.com/microsoft/Featuremanagement-Go/featuremanagement"
	"github.com/microsoft/Featuremanagement-Go/featuremanagement/providers/azappconfig"
)

func main() {
	// Set up authentication options
	authOptions := azureappconfiguration.AuthenticationOptions{
		Endpoint:   endpoint,
		Credential: credential,
	}

	// Load configuration with feature flags enabled
	options := &azureappconfiguration.Options{
		FeatureFlagOptions: azureappconfiguration.FeatureFlagOptions{
			Enabled: true,
			RefreshOptions: azureappconfiguration.RefreshOptions{
				Enabled: true,
			},
		},
	}

	appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)
	if err != nil {
		log.Fatalf("Failed to load configuration: %v", err)
	}

	// Create feature flag provider using the Azure App Configuration
	featureFlagProvider, err := azappconfig.NewFeatureFlagProvider(appConfig)
	if err != nil {
		log.Fatalf("Error creating feature flag provider: %v", err)
	}

	// Create feature manager
	featureManager, err := featuremanagement.NewFeatureManager(featureFlagProvider, nil)
	if err != nil {
		log.Fatalf("Error creating feature manager: %v", err)
	}

	// Use the feature manager to check feature flags
	isEnabled, err := featureManager.IsEnabled("Beta")
	if err != nil {
		log.Printf("Error checking feature flag: %v", err)
		return
	}

	if isEnabled {
		fmt.Println("Beta feature is enabled!")
		// Execute beta functionality
	} else {
		fmt.Println("Beta feature is disabled")
		// Execute standard functionality
	}
}

Mer information om hur du använder go-funktionshanteringsbiblioteket finns i snabbstarten för funktionsflaggan.

Key Vault-referens

Azure App Configuration har stöd för att referera till hemligheter som lagras i Azure Key Vault. I App Configuration kan du skapa nycklar som mappar till hemligheter som lagras i Key Vault, men som kan nås som alla andra konfigurationer när de har lästs in.

Konfigurationsproviderbiblioteket hämtar Key Vault-referenser, precis som för andra nycklar som lagras i App Configuration. Du måste konfigurera Key Vault-åtkomst med hjälp av KeyVaultOptions fältet i structen Options .

Ansluta till Key Vault

Du kan konfigurera Åtkomst till Key Vault genom att ange autentiseringsuppgifter som kan autentiseras för dina Key Vault-instanser.

import (
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

// Create a credential for Key Vault access
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
	log.Fatalf("Failed to create credential: %v", err)
}

options := &azureappconfiguration.Options{
	KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
		Credential: credential,
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Anpassad hemlighetslösare

Du kan också ange en anpassad lösningsfunktion för hemlighet för att hantera Key Vault-referenser när standardmetoden för autentiseringsuppgifter inte är lämplig:

options := &azureappconfiguration.Options{
	KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
		SecretResolver: func(ctx context.Context, keyVaultReference url.URL) (string, error) {
			// Custom logic to resolve secrets
			// This could integrate with your existing secret management system
			// or provide fallback values for development environments
			
			if isDevelopment {
				return os.Getenv("FALLBACK_SECRET_VALUE"), nil
			}
			
			// Implement your custom secret retrieval logic here
			return retrieveSecret(keyVaultReference)
		},
	},
}

Viktigt!

Om ditt program läser in nyckelvärden som innehåller Key Vault-referenser utan korrekt Key Vault-konfiguration returneras ett fel under inläsningen. Kontrollera att du har konfigurerat key vault-åtkomsten eller en hemlig lösning korrekt.

Hemlig uppdatering av Key Vault

Med Azure App Configuration kan du konfigurera hemliga uppdateringsintervall oberoende av konfigurationsuppdateringscykeln. Detta är viktigt för säkerheten eftersom även om Key Vault-referens-URI:n i App Configuration förblir oförändrad, kan den underliggande hemligheten i Key Vault roteras som en del av dina säkerhetsrutiner.

För att säkerställa att ditt program alltid använder de senaste hemliga värdena konfigurerar du RefreshOptions fältet i structen KeyVaultOptions .

import (
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

// Create a credential for Key Vault access
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
	log.Fatalf("Failed to create credential: %v", err)
}

options := &azureappconfiguration.Options{
	KeyVaultOptions: azureappconfiguration.KeyVaultOptions{
		Credential: credential,
		RefreshOptions: azureappconfiguration.RefreshOptions{
			Enabled: true,
			Interval: 5 * time.Minute,
		},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Ögonblicksbild

Ögonblicksbild är en namngiven, oföränderlig delmängd av ett appkonfigurationsarkivs nyckelvärden. De nyckelvärden som utgör en ögonblicksbild väljs under skapandetiden genom användning av nyckel- och etikettfilter. När en ögonblicksbild har skapats kommer nyckelvärdena inom garanterat att förbli oförändrade.

Du kan konfigurera SnapshotName fältet i Selector struktur för att läsa in nyckelvärden från en ögonblicksbild.

options := &azureappconfiguration.Options{
	Selectors: []azureappconfiguration.Selector{
		{KeyFilter: "app*", LabelFilter: "prod"},
		{SnapshotName: "my-snapshot"},
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Geo-replication

Information om hur du använder geo-replikering finns i Aktivera geo-replikering.

Startförsök igen

Konfigurationsinläsning är en kritisk operation under programstarten. För att säkerställa tillförlitlighet implementerar Azure App Configuration-providern en robust återförsöksmekanism under den första konfigurationsbelastningen. Detta skyddar ditt program från tillfälliga nätverksproblem som annars kan förhindra lyckad start.

Du kan anpassa det här beteendet via Options.StartupOptions:

options := &azureappconfiguration.Options{
	StartupOptions: azureappconfiguration.StartupOptions{
		Timeout: 5 * time.Minute,
	},
}

appConfig, err := azureappconfiguration.Load(ctx, authOptions, options)

Nästa steg

Om du vill lära dig hur du använder Go-konfigurationsprovidern fortsätter du till följande självstudie.

Använda dynamisk konfiguration i Go Console-appen

Använda dynamisk konfiguration i Go Gin-webbappen

  • Last updated on