azappconfig

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2023 License: MIT Imports: 12 Imported by: 9

README

Azure App Configuration Client Module for Go

Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely. It allows you to create and manage application configuration settings and retrieve their revisions from a specific point in time.

Source code | Package (pkg.go.dev) | Product documentation

Getting started

Install the module

Install azappconfig with go get:

go get github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig
Prerequisites
  • An Azure subscription
  • A supported Go version (the Azure SDK supports the two most recent Go releases)
  • A Configuration store. If you need to create one, see the App Configuration documentation for instructions on doing so in the Azure Portal or with the Azure CLI.
Authentication

Azure App Configuration supports authenticating with Azure Active Directory and connection strings. To authenticate with Azure Active Directory, use the azappconfig.NewClient constructor and to authenticate with a connection string, use the azappconfig.NewClientFromConnectionString constructor. For simplicity, the examples demonstrate authenticating with a connection string.

See the azidentity documentation for more information about possible Azure Active Directory credential types.

Key concepts

A Setting is the fundamental resource within a Configuration Store. In its simplest form, it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways.

The Label property of a Setting provides a way to separate Settings into different dimensions. These dimensions are user defined and can take any form. Some common examples of dimensions to use for a label include regions, semantic versions, or environments. Many applications have a required set of configuration keys that have varying values as the application exists across different dimensions.

For example, MaxRequests may be 100 in "NorthAmerica" and 200 in "WestEurope". By creating a Setting named MaxRequests with a label of "NorthAmerica" and another, only with a different value, with a "WestEurope" label, an application can seamlessly retrieve Settings as it runs in these two dimensions.

Examples

Examples for various scenarios can be found on pkg.go.dev or in the example*_test.go files in our GitHub repo for azappconfig.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddSettingOptions 

type AddSettingOptions struct {
	// Configuration setting content type.
	ContentType *string

	// Configuration setting label.
	Label *string
}

AddSettingOptions contains the optional parameters for the AddSetting method.

type AddSettingResponse 

type AddSettingResponse struct {
	Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

AddSettingResponse contains the response from AddSetting method.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the struct for interacting with an Azure App Configuration instance.

func NewClient 

func NewClient(endpoint string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error)

NewClient returns a pointer to a Client object affinitized to an endpoint.

Example 
package main

import (
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	credential, err := azidentity.NewDefaultAzureCredential(nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	client, err := azappconfig.NewClient("https://my-app-config.azconfig.io", credential, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = client // ignore

}

Output:

func NewClientFromConnectionString 

func NewClientFromConnectionString(connectionString string, options *ClientOptions) (*Client, error)

NewClientFromConnectionString parses the connection string and returns a pointer to a Client object.

Example 
package main

import (
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = client // ignore

}

Output:

func (*Client) AddSetting 

func (c *Client) AddSetting(ctx context.Context, key string, value *string, options *AddSettingOptions) (AddSettingResponse, error)

AddSetting creates a configuration setting only if the setting does not already exist in the configuration store.

  • ctx controls the lifetime of the HTTP operation
  • key is the name of the setting to create
  • value is the value for the setting. pass nil if the setting doesn't have a value
  • options contains the optional values. can be nil
Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	// Create configuration setting
	resp, err := client.AddSetting(context.TODO(), "example-key", to.Ptr("example-value"), &azappconfig.AddSettingOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

}

Output:

func (*Client) DeleteSetting 

func (c *Client) DeleteSetting(ctx context.Context, key string, options *DeleteSettingOptions) (DeleteSettingResponse, error)

DeleteSetting deletes a configuration setting from the configuration store.

Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	// Delete configuration setting
	resp, err := client.DeleteSetting(context.TODO(), "example-key", &azappconfig.DeleteSettingOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

}

Output:

func (*Client) GetSetting 

func (c *Client) GetSetting(ctx context.Context, key string, options *GetSettingOptions) (GetSettingResponse, error)

GetSetting retrieves an existing configuration setting from the configuration store.

Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	// Get configuration setting
	resp, err := client.GetSetting(context.TODO(), "example-key", &azappconfig.GetSettingOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

}

Output:

func (*Client) NewListRevisionsPager 

func (c *Client) NewListRevisionsPager(selector SettingSelector, options *ListRevisionsOptions) *runtime.Pager[ListRevisionsPageResponse]

NewListRevisionsPager creates a pager that retrieves the revisions of one or more configuration setting entities that match the specified setting selector.

Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	pager := client.NewListRevisionsPager(azappconfig.SettingSelector{
		KeyFilter:   to.Ptr("*"),
		LabelFilter: to.Ptr("*"),
		Fields:      azappconfig.AllSettingFields(),
	}, nil)

	for pager.More() {
		page, err := pager.NextPage(context.TODO())

		if err != nil {
			//  TODO: Update the following line with your application specific error handling logic
			log.Fatalf("ERROR: %s", err)
		}

		for _, setting := range page.Settings {
			// each page contains all of the returned settings revisions that match the provided [SettingSelector]

			_ = setting // ignore
		}
	}

}

Output:

func (*Client) NewListSettingsPager added in v0.4.1 

func (c *Client) NewListSettingsPager(selector SettingSelector, options *ListSettingsOptions) *runtime.Pager[ListSettingsPageResponse]

NewListSettingsPager creates a pager that retrieves setting entities that match the specified setting selector.

func (*Client) SetReadOnly 

func (c *Client) SetReadOnly(ctx context.Context, key string, isReadOnly bool, options *SetReadOnlyOptions) (SetReadOnlyResponse, error)

SetReadOnly sets an existing configuration setting to read only or read write state in the configuration store.

Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	// Set configuration setting read only
	resp, err := client.SetReadOnly(context.TODO(), "example-key", true, &azappconfig.SetReadOnlyOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

	// Remove read only status
	resp, err = client.SetReadOnly(context.TODO(), "example-key", false, &azappconfig.SetReadOnlyOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

}

Output:

func (*Client) SetSetting 

func (c *Client) SetSetting(ctx context.Context, key string, value *string, options *SetSettingOptions) (SetSettingResponse, error)

SetSetting creates a configuration setting if it doesn't exist or overwrites the existing setting in the configuration store.

  • ctx controls the lifetime of the HTTP operation
  • key is the name of the setting to create
  • value is the value for the setting. pass nil if the setting doesn't have a value
  • options contains the optional values. can be nil
Example 
package main

import (
	"context"
	"log"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig"
)

func main() {
	connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING")
	if connectionString == "" {
		return
	}

	client, err := azappconfig.NewClientFromConnectionString(connectionString, nil)

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	// Set configuration setting
	resp, err := client.SetSetting(context.TODO(), "example-key", to.Ptr("example-new-value"), &azappconfig.SetSettingOptions{
		Label: to.Ptr("example-label"),
	})

	if err != nil {
		//  TODO: Update the following line with your application specific error handling logic
		log.Fatalf("ERROR: %s", err)
	}

	_ = resp // TODO: do something with resp

}

Output:

func (*Client) SetSyncToken added in v0.6.0 

func (c *Client) SetSyncToken(syncToken SyncToken) error

SetSyncToken is used to set a sync token from an external source. SyncTokens are required to be in the format "<id>=<value>;sn=<sn>". Multiple SyncTokens must be comma delimited.

type ClientOptions 

type ClientOptions struct {
	azcore.ClientOptions
}

ClientOptions are the configurable options on a Client.

type DeleteSettingOptions 

type DeleteSettingOptions struct {
	// Configuration setting label.
	Label *string

	// If set, and the configuration setting exists in the configuration store,
	// delete the setting if the passed-in ETag is the same as the setting's ETag in the configuration store.
	OnlyIfUnchanged *azcore.ETag
}

DeleteSettingOptions contains the optional parameters for the DeleteSetting method.

type DeleteSettingResponse 

type DeleteSettingResponse struct {
	Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

DeleteSettingResponse contains the response from DeleteSetting method.

type GetSettingOptions 

type GetSettingOptions struct {
	// The setting will be retrieved exactly as it existed at the provided time.
	AcceptDateTime *time.Time

	// Configuration setting label.
	Label *string

	// If set, only retrieve the setting from the configuration store if setting has changed
	// since the client last retrieved it with the ETag provided.
	OnlyIfChanged *azcore.ETag
}

GetSettingOptions contains the optional parameters for the GetSetting method.

type GetSettingResponse 

type GetSettingResponse struct {
	Setting

	// Contains the timestamp of when the configuration setting was last modified.
	LastModified *time.Time

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

GetSettingResponse contains the configuration setting retrieved by GetSetting method.

type ListRevisionsOptions 

type ListRevisionsOptions struct {
}

ListRevisionsOptions contains the optional parameters for the NewListRevisionsPager method.

type ListRevisionsPageResponse added in v0.6.0 

type ListRevisionsPageResponse struct {
	// Contains the configuration settings returned that match the setting selector provided.
	Settings []Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

ListRevisionsPageResponse contains the configuration settings returned by ListRevisionsPager.

type ListSettingsOptions added in v0.4.1 

type ListSettingsOptions struct {
}

ListSettingsOptions contains the optional parameters for the NewListSettingsPager method.

type ListSettingsPageResponse added in v0.6.0 

type ListSettingsPageResponse struct {
	// Contains the configuration settings returned that match the setting selector provided.
	Settings []Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

ListSettingsPageResponse contains the configuration settings returned by ListRevisionsPager.

type SetReadOnlyOptions 

type SetReadOnlyOptions struct {
	// Configuration setting label.
	Label *string

	// If set, and the configuration setting exists in the configuration store, update the setting
	// if the passed-in configuration setting ETag is the same version as the one in the configuration store.
	OnlyIfUnchanged *azcore.ETag
}

SetReadOnlyOptions contains the optional parameters for the SetReadOnly method.

type SetReadOnlyResponse 

type SetReadOnlyResponse struct {
	Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

SetReadOnlyResponse contains the response from SetReadOnly method.

type SetSettingOptions 

type SetSettingOptions struct {
	// Configuration setting content type.
	ContentType *string

	// Configuration setting label.
	Label *string

	// If set, and the configuration setting exists in the configuration store, overwrite the setting
	// if the passed-in ETag is the same version as the one in the configuration store.
	OnlyIfUnchanged *azcore.ETag
}

SetSettingOptions contains the optional parameters for the SetSetting method.

type SetSettingResponse 

type SetSettingResponse struct {
	Setting

	// SyncToken contains the value returned in the Sync-Token header.
	SyncToken SyncToken
}

SetSettingResponse contains the response from SetSetting method.

type Setting 

type Setting struct {
	// The primary identifier of the configuration setting.
	// A Key is used together with a Label to uniquely identify a configuration setting.
	Key *string

	// The configuration setting's value.
	Value *string

	// A value used to group configuration settings.
	// A Label is used together with a Key to uniquely identify a configuration setting.
	Label *string

	// The content type of the configuration setting's value.
	// Providing a proper content-type can enable transformations of values when they are retrieved by applications.
	ContentType *string

	// An ETag indicating the state of a configuration setting within a configuration store.
	ETag *azcore.ETag

	// A dictionary of tags used to assign additional properties to a configuration setting.
	// These can be used to indicate how a configuration setting may be applied.
	Tags map[string]string

	// The last time a modifying operation was performed on the given configuration setting.
	LastModified *time.Time

	// A value indicating whether the configuration setting is read only.
	// A read only configuration setting may not be modified until it is made writable.
	IsReadOnly *bool
}

Setting is a setting, defined by a unique combination of a Key and Label.

type SettingFields 

type SettingFields = generated.SettingFields

SettingFields are fields to retrieve from a configuration setting. 

const (
	// The primary identifier of a configuration setting.
	SettingFieldsKey SettingFields = generated.SettingFieldsKey

	// A label used to group configuration settings.
	SettingFieldsLabel SettingFields = generated.SettingFieldsLabel

	// The value of the configuration setting.
	SettingFieldsValue SettingFields = generated.SettingFieldsValue

	// The content type of the configuration setting's value.
	SettingFieldsContentType SettingFields = generated.SettingFieldsContentType

	// An ETag indicating the version of a configuration setting within a configuration store.
	SettingFieldsETag SettingFields = generated.SettingFieldsEtag

	// The last time a modifying operation was performed on the given configuration setting.
	SettingFieldsLastModified SettingFields = generated.SettingFieldsLastModified

	// A value indicating whether the configuration setting is read-only.
	SettingFieldsIsReadOnly SettingFields = generated.SettingFieldsLocked

	// A list of tags that can help identify what a configuration setting may be applicable for.
	SettingFieldsTags SettingFields = generated.SettingFieldsTags
)

func AllSettingFields 

func AllSettingFields() []SettingFields

AllSettingFields returns a collection of all setting fields to use in SettingSelector.

type SettingSelector 

type SettingSelector struct {
	// Key filter that will be used to select a set of configuration setting entities.
	KeyFilter *string

	// Label filter that will be used to select a set of configuration setting entities.
	LabelFilter *string

	// Indicates the point in time in the revision history of the selected configuration setting entities to retrieve.
	// If set, all properties of the configuration setting entities in the returned group will be exactly what they were at this time.
	AcceptDateTime *time.Time

	// The fields of the configuration setting to retrieve for each setting in the retrieved group.
	Fields []SettingFields
}

SettingSelector is a set of options that allows selecting a filtered set of configuration setting entities from the configuration store, and optionally allows indicating which fields of each setting to retrieve.

type SyncToken added in v0.6.0 

type SyncToken = exported.SyncToken

SyncToken contains data used in the Sync-Token header. See Azure App Configuration documentation for more information on sync tokens.

Source Files

View all Source files

Directories

Path Synopsis
auth
exported
generated
synctoken

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.