Sdílet prostřednictvím

Zprostředkovatel konfigurace Go

Azure App Configuration je spravovaná služba, která vývojářům pomáhá jednoduše a bezpečně centralizovat konfigurace aplikací. Knihovna zprostředkovatele konfigurace Go umožňuje načítat konfiguraci z úložiště Azure App Configuration Store spravovaným způsobem. Tato klientská knihovna přidává další funkce nad sadu Azure SDK for Go.

Konfigurace načtení

Zprostředkovatel Azure App Configuration Go umožňuje načíst konfigurační hodnoty z Azure App Configuration Storu do aplikací Go. Můžete se připojit pomocí ověřování Microsoft Entra ID nebo připojovacího řetězce.

Pokud chcete použít zprostředkovatele konfigurace Go, nainstalujte balíček:

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

Load Zavoláte funkci z azureappconfiguration balíčku, která načte konfiguraci z Azure App Configuration. Funkce Load přijímá možnosti ověřování a možnosti konfigurace pro přizpůsobení chování načítání.

K ověření vaší služby App Configuration Store můžete použít DefaultAzureCredential, nebo jakoukoli jinou implementaci přihlašovacích údajů tokenu. Postupujte podle pokynů, aby vaše přihlašovací údaje byly přiřazeny k roli Čtenář dat konfigurace aplikace.

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

Načtení konkrétních hodnot klíče pomocí selektorů

Ve výchozím nastavení poskytovatel konfigurace načte všechny hodnoty klíče bez popisku z App Configuration. Hodnoty klíče můžete selektivně načíst tak, že nakonfigurujete Selectors pole ve Options struktuře.

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)

Struktura Selector podporuje následující pole:

  • KeyFilter: Určuje, které konfigurační klíče se mají zahrnout. Použijte přesné shody, porovnávání předpon s *více klíči oddělenými čárkami.
  • LabelFilter: Vybere hodnoty klíče s konkrétním popiskem. Pokud jsou prázdné, načte hodnoty klíče bez popisku.

Poznámka:

Pokud více selektorů zahrnuje překrývající se klíče, budou mít pozdější selektory přednost před dřívějšími.

Filtry značek

Parametr TagFilters vybere hodnoty klíčů s konkrétními značkami. Hodnota klíče se načte pouze v případě, že obsahuje všechny značky a odpovídající hodnoty zadané ve filtrech.

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)

Poznámka:

Znaky hvězdička (), čárka (*,) a zpětné lomítko (\) jsou vyhrazeny a musí být uchvácené zpětným lomítkem při použití ve filtru značek.

Oříznutí předpony z klíčů

Při načítání konfiguračních hodnot s konkrétními předponami můžete tyto TrimKeyPrefixes předpony odebrat z klíčů v konfiguraci. Tím se ve vaší aplikaci vytvoří čistější konfigurační klíče při zachování organizovanosti ve vašem úložišti konfigurace aplikací.

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)

Pokud například úložiště App Configuration obsahuje klíč s názvem TestApp:Settings:Message, bude v aplikaci přístupný jako Settings:Message po oříznutí předpony TestApp: .

Zpracování typu obsahu JSON

Hodnoty klíčů JSON můžete vytvořit v App Configuration. Při čtení hodnoty klíče s typem "application/json" obsahu ho poskytovatel konfigurace parsuje do vnořených struktur. Další informace najdete v tématu Použití typu obsahu k ukládání hodnot klíčů JSON v App Configuration.

Poznámka:

Počínaje verzí 1.2.0 poskytovatel konfigurace umožňuje komentáře definované v JSONC v klíč-hodnotách s typem obsahu application/json.

Využití konfigurace

Typ AzureAppConfiguration vrácený Load funkcí poskytuje několik metod pro přístup k vašim konfiguračním datům:

Odstrukturování do struktur

Metoda Unmarshal poskytuje typově bezpečný způsob, jak načíst hodnoty konfigurace do struktur Go. Tento přístup brání chybám za běhu v chybně zatypovaných konfiguračních klíčích a usnadňuje údržbu kódu. Metoda přijímá volitelný ConstructionOptions parametr pro přizpůsobení způsobu mapování konfiguračních klíčů na pole struktury.

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

Vlastní oddělovače klíčů

Způsob mapování konfiguračních klíčů na pole struktury můžete přizpůsobit pomocí ConstructionOptions. To je užitečné, když konfigurační klíče používají jiné oddělovače než výchozí tečka (.):

// 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)
}

Struktura ConstructionOptions podporuje následující oddělovače: ., ,, ;, -_, , __, , /. :. Pokud není zadaný, použije se výchozí oddělovač . .

Získání nezpracovaných bajtů JSON

Metoda GetBytes načte vaši konfiguraci jako nezpracovaná data JSON a nabízí flexibilitu pro integraci s knihovnami pro zpracování JSON nebo konfiguračními architekturami, jako je viper. Tato metoda také přijímá volitelný ConstructionOptions parametr pro řízení mapování hierarchie klíčů.

// 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)
}

Aktualizace konfigurace

Konfigurace aktualizace umožňuje aplikaci načíst nejnovější hodnoty z App Configuration Storu, aniž by se museli restartovat. Možnosti aktualizace můžete nakonfigurovat pomocí RefreshOptions pole ve struktuře Options . Načtená konfigurace se aktualizuje, když se na serveru zjistí jakákoli změna vybraných hodnot klíčů. Ve výchozím nastavení se používá interval aktualizace 30 sekund, ale můžete ho Interval přepsat vlastností.

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)

Samotné nastavení RefreshOptions nebude automaticky aktualizovat konfiguraci. K aktivaci aktualizace je potřeba volat Refresh metodu AzureAppConfiguration instance.

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

Tento návrh zabraňuje zbytečným požadavkům na konfiguraci aplikace, když je vaše aplikace nečinná. Měli byste zahrnout volání, Refresh ve kterém dojde k aktivitě vaší aplikace. To se označuje jako aktualizace konfigurace řízené aktivitami. Můžete například volat Refresh při zpracování příchozího požadavku nebo uvnitř iterace, kde provádíte složitou úlohu.

Poznámka:

I když volání aktualizace z nějakého důvodu selže, bude vaše aplikace dál používat konfiguraci uloženou v mezipaměti. Další pokus se provede, když se předá nakonfigurovaný interval aktualizace a aktivita vaší aplikace aktivuje volání aktualizace. Volání Refresh je no-op před uplynutím nakonfigurovaného intervalu aktualizace, takže jeho dopad na výkon je minimální, i když se volá často.

Aktualizace klíče sentinel

Klíč sentinelu je klíč, který aktualizujete po dokončení změny všech ostatních klíčů. Poskytovatel konfigurace monitoruje klíč sentinelu místo všech vybraných klíčových hodnot. Když se zjistí změna, aplikace aktualizuje všechny konfigurační hodnoty.

Tento přístup je užitečný při aktualizaci více hodnot klíče. Aktualizací klíče sentinelu až po dokončení všech ostatních změn konfigurace zajistíte, že vaše aplikace znovu načte konfiguraci jen jednou a zachová konzistenci.

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: "",
			},
		},
	},
}

Zpětná volání vlastní aktualizace

Metoda OnRefreshSuccess zaregistruje funkci zpětného volání, která se spustí při každé úspěšné aktualizaci konfigurace a zjištění skutečných změn.

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

Hlavní příznaky

Příznaky funkcí v Azure App Configuration poskytují moderní způsob řízení dostupnosti funkcí ve vašich aplikacích. Na rozdíl od běžných konfiguračních hodnot musí být příznaky funkcí explicitně načteny pomocí FeatureFlagOptions pole ve struktuře 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)

Návod

Pokud není zadán FeatureFlagOptionsžádný selektor , načte všechny příznaky funkcí bez popisku v App Configuration Storu. Výchozí interval aktualizace příznaků funkcí je 30 sekund.

Důležité

Pokud chcete efektivně využívat a spravovat příznaky funkcí načtené ze služby Azure App Configuration, nainstalujte a použijte featuremanagement balíček. Tato knihovna poskytuje strukturovaný způsob řízení chování funkcí ve vaší aplikaci.

Správa funkcí

Knihovna Feature Management Go poskytuje strukturovaný způsob vývoje a zveřejnění funkcí aplikace na základě příznaků funkcí. Knihovna pro správu funkcí je navržená tak, aby fungovala ve spojení s knihovnou zprostředkovatele konfigurace.

Pokud chcete používat příznaky funkcí s knihovnou pro správu funkcí, nainstalujte požadované balíčky:

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

Následující příklad ukazuje, jak integrovat knihovnu správy funkcí s poskytovatelem konfigurace, aby dynamicky kontrolovali dostupnost funkcí:

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

Další informace o tom, jak používat knihovnu pro správu funkcí Go, najdete v rychlém startu s příznakem funkce.

Referenční informace ke službě Key Vault

konfigurace Aplikace Azure podporuje odkazování na tajné kódy uložené ve službě Azure Key Vault. V App Configuration můžete vytvořit klíče, které se mapují na tajné kódy uložené ve službě Key Vault, ale po načtení se k nim dají přistupovat stejně jako k jakékoli jiné konfiguraci.

Knihovna zprostředkovatele konfigurace načítá odkazy na službu Key Vault stejně jako u všech dalších klíčů uložených v App Configuration. Přístup ke službě Key Vault je potřeba nakonfigurovat pomocí KeyVaultOptions pole ve struktuře Options .

Připojení ke službě Key Vault

Přístup ke službě Key Vault můžete nakonfigurovat zadáním přihlašovacích údajů, které se můžou ověřit v instancích služby Key Vault.

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)

Překladač vlastních tajných kódů

Pokud výchozí přístup založený na přihlašovacích údajích není vhodný, můžete také poskytnout vlastní funkci překladače tajných kódů pro zpracování odkazů služby Key Vault:

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)
		},
	},
}

Důležité

Pokud vaše aplikace načte hodnoty klíčů obsahující odkazy služby Key Vault bez správné konfigurace služby Key Vault, během operace načítání se vrátí chyba . Ujistěte se, že jste správně nakonfigurovali přístup ke službě Key Vault nebo překladač tajných kódů.

Aktualizace tajných kódů služby Key Vault

Azure App Configuration umožňuje konfigurovat intervaly aktualizace tajných kódů nezávisle na cyklu aktualizace konfigurace. To je důležité pro zabezpečení, protože zatímco referenční identifikátor URI služby Key Vault v konfiguraci aplikace zůstává beze změny, může se v rámci vašich postupů zabezpečení obměňovat základní tajný klíč ve službě Key Vault.

Pokud chcete zajistit, aby vaše aplikace vždy používala nejaktuálnější hodnoty tajných kódů, nakonfigurujte RefreshOptions pole ve struktuře 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)

Snímek

Snímek je pojmenovaná, neměnná podmnožina klíčů a hodnot v úložišti App Configuration. Hodnoty klíčů, které tvoří snímek, se vyberou během vytváření prostřednictvím filtrů klíčů a popisků. Po vytvoření snímku se zaručuje, že hodnoty klíče v rámci zůstanou beze změny.

Položku SnapshotName ve struktuře Selector můžete nakonfigurovat tak, aby načítala hodnoty klíčů ze snímku.

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

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

Geografická replikace

Informace o použití geografické replikace najdete v tématu Povolení geografické replikace.

Opakovaný pokus o spuštění

Načítání konfigurace je kritická operace během spouštění aplikace. Kvůli zajištění spolehlivosti implementuje poskytovatel azure App Configuration robustní mechanismus opakování během počátečního zatížení konfigurace. To pomáhá chránit vaši aplikaci před přechodnými problémy se sítí, které by jinak mohly bránit úspěšnému spuštění.

Toto chování můžete přizpůsobit pomocí Options.StartupOptionspříkazu :

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

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

Další kroky

Pokud chcete zjistit, jak používat zprostředkovatele konfigurace Go, pokračujte následujícím kurzem.

Použití dynamické konfigurace v aplikaci konzoly Go

Použití dynamické konfigurace ve webové aplikaci Go Gin

  • Last updated on