Dostawca konfiguracji języka Go

Usługa Azure App Configuration to usługa zarządzana, która pomaga deweloperom w prosty i bezpieczny sposób scentralizować konfigurację aplikacji. Biblioteka dostawcy konfiguracji języka Go umożliwia ładowanie konfiguracji z magazynu usługi Azure App Configuration w zarządzany sposób. Ta biblioteka klienta dodaje dodatkowe funkcje w oparciu o zestaw Azure SDK dla języka Go.

Ładowanie konfiguracji

Dostawca języka Go usługi Azure App Configuration umożliwia ładowanie wartości konfiguracji ze sklepu Azure App Configuration do aplikacji języka Go. Możesz nawiązać połączenie przy użyciu uwierzytelniania microsoft Entra ID lub parametrów połączenia.

Aby użyć dostawcy konfiguracji języka Go, zainstaluj pakiet:

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

Load Wywołasz funkcję z azureappconfiguration pakietu, aby załadować konfigurację z usługi Azure App Configuration. Funkcja Load akceptuje opcje uwierzytelniania i opcje konfiguracji, aby dostosować zachowanie ładowania.

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

package main

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

	"github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
)

func main() {
	ctx := context.Background()
	
	// Get the connection string from environment variable
	connectionString := os.Getenv("AZURE_APPCONFIG_CONNECTION_STRING")
	
	// Set up authentication options
	authOptions := azureappconfiguration.AuthenticationOptions{
		ConnectionString: connectionString,
	}

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

Ładowanie określonych klucz-wartości przy użyciu selektorów

Domyślnie dostawca konfiguracji ładuje wszystkie wartości klucza bez etykiety z usługi App Configuration. Możesz selektywnie załadować wartości klucz-wartość, konfigurując Selectors pole w Options strukturę.

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 obsługuje następujące pola:

• KeyFilter: określa klucze konfiguracji do uwzględnienia. Użyj dokładnych dopasowań, dopasowywania prefiksów z *rozdzielanymi przecinkami wielu kluczy.
• LabelFilter: wybiera wartości klucza z określoną etykietą. Jeśli jest pusty, ładuje wartości kluczy bez etykiety.

Filtry tagów

Parametr TagFilters wybiera wartości klucza z określonymi tagami. Wartość-klucz jest ładowana tylko wtedy, gdy zawiera wszystkie tagi i odpowiednie wartości określone w filtrach.

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)

Przycinanie prefiksu z kluczy

Podczas ładowania wartości konfiguracji z określonymi prefiksami można użyć TrimKeyPrefixes opcji usuwania tych prefiksów z kluczy w konfiguracji. Umożliwia to tworzenie bardziej przejrzystych kluczy konfiguracji w aplikacji, jednocześnie zachowując porządek w magazynie App Configuration.

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)

Jeśli na przykład magazyn usługi App Configuration zawiera klucz o nazwie TestApp:Settings:Message, będzie dostępny w aplikacji jako Settings:Message po usunięciu prefiksu TestApp:.

Obsługa typów zawartości JSON

Możesz utworzyć wartości kluczy JSON w usłudze App Configuration. Gdy odczytuje się klucz-wartość z typem "application/json" zawartości, dostawca konfiguracji przeanalizuje go w zagnieżdżonych strukturach. Aby uzyskać więcej informacji, zobacz Use content type to store JSON key-values in App Configuration (Używanie typu zawartości do przechowywania wartości kluczy JSON w usłudze App Configuration).

Korzystanie z konfiguracji

AzureAppConfiguration Typ zwracany przez Load funkcję udostępnia kilka metod uzyskiwania dostępu do danych konfiguracji:

Unmarshal do struktur

Metoda Unmarshal zapewnia bezpieczny typ sposób ładowania wartości konfiguracji do struktur języka Go. Takie podejście uniemożliwia błędy środowiska uruchomieniowego z błędnie wtypowanych kluczy konfiguracji i sprawia, że kod jest bardziej konserwowalny. Metoda akceptuje opcjonalny ConstructionOptions parametr, aby dostosować sposób mapowania kluczy konfiguracji na pola 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)
}

Niestandardowe separatory kluczy

Możesz dostosować sposób mapowania kluczy konfiguracji na pola struktury przy użyciu polecenia ConstructionOptions. Jest to przydatne, gdy klucze konfiguracji używają różnych separatorów niż domyślna kropka (.):

// 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 obsługuje następujące separatory: ., , ,;, -, ___, , /, . : Jeśli nie zostanie określony, zostanie użyty separator . domyślny.

Pobieranie nieprzetworzonych bajtów JSON

Metoda GetBytes pobiera konfigurację jako nieprzetworzone dane JSON, zapewniając elastyczność integracji z bibliotekami przetwarzania JSON lub strukturami konfiguracji, takimi jak viper. Ta metoda akceptuje również opcjonalny ConstructionOptions parametr służący do kontrolowania mapowania hierarchii kluczy.

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

Odświeżanie konfiguracji

Konfigurowanie odświeżania umożliwia aplikacji ściąganie najnowszych wartości ze sklepu App Configuration bez konieczności ponownego uruchamiania. Opcje odświeżania RefreshOptions można skonfigurować przy użyciu pola w Options ramach struktury. Załadowana konfiguracja zostanie zaktualizowana po wykryciu dowolnej zmiany wybranych wartości kluczy na serwerze. Domyślnie jest używany interwał odświeżania wynoszący 30 sekund, ale można go zastąpić właściwością Interval .

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)

Skonfigurowanie RefreshOptions samej konfiguracji nie spowoduje automatycznego odświeżenia konfiguracji. Aby wyzwolić odświeżanie, należy wywołać Refresh metodę w wystąpieniu AzureAppConfiguration .

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

Ten projekt uniemożliwia niepotrzebne żądania do usługi App Configuration, gdy aplikacja jest bezczynna. Należy dołączyć Refresh wywołanie, w którym występuje działanie aplikacji. Jest to nazywane odświeżaniem konfiguracji opartej na działaniach. Można na przykład wywołać Refresh metodę przetwarzania żądania przychodzącego lub wewnątrz iteracji, w której wykonujesz złożone zadanie.

Odświeżanie klucza sentinel

Klucz sentinel to klucz aktualizowany po zakończeniu zmiany wszystkich innych kluczy. Dostawca konfiguracji monitoruje klucz strażnika zamiast wszystkich wybranych wartości klucza. Po wykryciu zmiany aplikacja odświeża wszystkie wartości konfiguracji.

Takie podejście jest przydatne podczas aktualizowania wielu par klucz-wartość. Aktualizując klucz sentinel dopiero po zakończeniu wszystkich innych zmian konfiguracji, upewnij się, że aplikacja ponownie ładuje konfigurację tylko raz, zachowując spójność.

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

Wywołanie zwrotne odświeżania niestandardowego

Metoda OnRefreshSuccess rejestruje funkcję wywołania zwrotnego, która będzie wykonywana po pomyślnym odświeżeniu konfiguracji i wykryciu rzeczywistych zmian.

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

Przełączniki funkcji

Flagi funkcji w Azure App Configuration zapewniają nowoczesny sposób kontrolowania dostępności funkcji w aplikacjach. W przeciwieństwie do zwykłych wartości konfiguracji flagi funkcji muszą być jawnie ładowane przy użyciu FeatureFlagOptions pola w Options strukturę.

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)

Zarządzanie funkcjami

Biblioteka Języka Go zarządzania funkcjami zapewnia ustrukturyzowany sposób tworzenia i uwidaczniania funkcji na podstawie flag funkcji. Biblioteka zarządzania funkcjami jest przeznaczona do pracy w połączeniu z biblioteką dostawcy konfiguracji.

Aby używać flag funkcji z biblioteką zarządzania funkcjami, zainstaluj wymagane pakiety:

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

W poniższym przykładzie pokazano, jak zintegrować bibliotekę zarządzania funkcjami z dostawcą konfiguracji, aby dynamicznie kontrolować dostępność funkcji:

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

Aby uzyskać więcej informacji na temat korzystania z biblioteki zarządzania funkcjami języka Go, przejdź do przewodnika Szybki start flagi funkcji.

Dokumentacja usługi Key Vault

aplikacja systemu Azure Configuration obsługuje odwoływanie się do wpisów tajnych przechowywanych w usłudze Azure Key Vault. W usłudze App Configuration można tworzyć klucze mapowane na wpisy tajne przechowywane w usłudze Key Vault, ale można uzyskać dostęp do dowolnej innej konfiguracji po załadowaniu.

Biblioteka dostawcy konfiguracji pobiera odwołania do usługi Key Vault, podobnie jak w przypadku innych kluczy przechowywanych w usłudze App Configuration. Musisz skonfigurować dostęp do usługi Key Vault przy użyciu KeyVaultOptions pola w Options ramach struktury.

Nawiązywanie połączenia z usługą Key Vault

Dostęp do usługi Key Vault można skonfigurować, podając poświadczenia, które mogą uwierzytelniać się w wystąpieniach usługi 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)

Niestandardowy moduł rozpoznawania wpisów tajnych

Możesz również udostępnić niestandardową funkcję rozpoznawania wpisów tajnych do obsługi odwołań usługi Key Vault, gdy domyślne podejście oparte na poświadczeniach nie jest odpowiednie:

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

Odświeżanie sekretów Key Vault

Usługa Azure App Configuration umożliwia konfigurowanie interwałów odświeżania tajnych danych niezależnie od cyklu odświeżania konfiguracji. Ma to kluczowe znaczenie dla bezpieczeństwa, ponieważ identyfikator URI odwołania do Key Vault w App Configuration pozostaje niezmieniony, podczas gdy ukryty sekret w Key Vault może być rotowany w ramach praktyk bezpieczeństwa.

Aby upewnić się, że aplikacja zawsze używa najbardziej bieżących wartości wpisów tajnych, skonfiguruj RefreshOptions pole w KeyVaultOptions strukturę.

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)

Migawka

Migawka jest nazwanym, niezmiennym podzbiorem wartości kluczy sklepu App Configuration. Wartości klucza tworzące migawkę są wybierane w czasie tworzenia za pomocą filtrów kluczy i etykiet. Po utworzeniu migawki gwarantowane są wartości kluczy w ramach programu .

Można skonfigurować pole SnapshotName w strukturze Selector do ładowania wartości kluczy z migawki.

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

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

Geo-replication

Aby uzyskać informacje na temat korzystania z replikacji geograficznej, przejdź do tematu Włączanie replikacji geograficznej.

Ponów próbę ponownego uruchamiania

Ładowanie konfiguracji jest operacją krytyczną podczas uruchamiania aplikacji. Aby zapewnić niezawodność, dostawca usługi Azure App Configuration implementuje niezawodny mechanizm ponawiania prób podczas początkowego ładowania konfiguracji. Pomaga to chronić aplikację przed przejściowymi problemami z siecią, które w przeciwnym razie mogą uniemożliwić pomyślne uruchomienie.

To zachowanie można dostosować za pomocą polecenia Options.StartupOptions:

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

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

Dalsze kroki

Aby dowiedzieć się, jak używać dostawcy konfiguracji języka Go, przejdź do następującego samouczka.