forked from Azure/azure-sdk-for-go
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Prepare azappconfig for v1.0.0 release (Azure#21747)
* Prepare azappconfig for v1.0.0 release Cleaned up README and added testable examples. * skip examples when there's no connection string * remove testable output checks * remove printing from testable examples
- Loading branch information
1 parent
cb9008f
commit 9f29c7c
Showing
6 changed files
with
311 additions
and
322 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,329 +1,46 @@ | ||
| # Azure App Configuration client library for Go | ||
| # 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][appconfig_client_src] | [Package (pkg.go.dev)][goget_azappconfig] | [Product documentation][appconfig_docs] | ||
| [Source code][azappconfig_src] | [Package (pkg.go.dev)][azappconfig] | [Product documentation][appconfig_docs] | ||
|
|
||
| ## Getting started | ||
| ### Install packages | ||
| Install [azappconfig][goget_azappconfig] with `go get`: | ||
| ```Bash | ||
| go get github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig | ||
| ``` | ||
|
|
||
| ### Prerequisites | ||
| * An [Azure subscription][azure_sub] | ||
| * Go version 1.18 or higher | ||
| * An App Configuration store. If you need to create one, you can use the [Azure Cloud Shell][azure_cloud_shell] to create one with these commands (replace `"my-resource-group"` and `"my-app-config"` with your own, unique | ||
| names): | ||
|
|
||
| (Optional) if you want a new resource group to hold the Azure App Configuration: | ||
| ```sh | ||
| az group create --name my-resource-group --location westus2 | ||
| ``` | ||
|
|
||
| Create the Key Vault: | ||
| ```Bash | ||
| az appconfig create --resource-group my-resource-group --name my-app-config --location westus2 | ||
| ``` | ||
| ### Install the module | ||
|
|
||
| Output: | ||
| ```json | ||
| { | ||
| "creationDate": "...", | ||
| "endpoint": "https://my-app-config.azconfig.io", | ||
| "id": "/subscriptions/.../resourceGroups/my-resource-group/providers/Microsoft.AppConfiguration/configurationStores/my-app-config", | ||
| "location": "westus2", | ||
| "name": "my-app-config", | ||
| "provisioningState": "Succeeded", | ||
| "resourceGroup": "my-resource-group", | ||
| "tags": {}, | ||
| "type": "Microsoft.AppConfiguration/configurationStores" | ||
| } | ||
| ``` | ||
| Install `azappconfig` with `go get`: | ||
|
|
||
| > The `"endpoint"` property is the `endpointUrl` used by [Client][appconfig_client_src] | ||
|
|
||
| ### Authenticate the client | ||
| This document demonstrates using the connection string. However, [Client][appconfig_client_src] accepts any [azidentity][azure_identity] credential. See the [azidentity][azure_identity] documentation for more information about other credentials. | ||
|
|
||
| #### Create a client | ||
| Constructing the client requires your App Configuration connection string, which you can get from the Azure Portal. | ||
| ```Bash | ||
| export APPCONFIGURATION_CONNECTION_STRING="Endpoint=https://my-app-config.azconfig.io;Id=...;Secret=..." | ||
| ``` | ||
|
|
||
| ```go | ||
| import ( | ||
| "os" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| ) | ||
| client, err = azappconfig.NewClientFromConnectionString(os.Getenv("APPCONFIGURATION_CONNECTION_STRING"), nil) | ||
| ``` | ||
|
|
||
| Or, using Default Azure Credential from Azure Identity: | ||
|
|
||
| ```go | ||
| import ( | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azidentity" | ||
| ) | ||
| credential, err := azidentity.NewDefaultAzureCredential(nil) | ||
| client, err = azappconfig.NewClient("https://my-app-config.azconfig.io", credential, nil) | ||
| ``` | ||
|
|
||
| ## Examples | ||
| This section contains code snippets covering common tasks: | ||
| * [Add a configuration setting](#add-a-configuration-setting "Add a configuration setting") | ||
| * [Get a configuration setting](#get-a-configuration-setting "Get a configuration setting") | ||
| * [Set a configuration setting](#set-a-configuration-setting "Set a configuration setting") | ||
| * [Set a configuration setting read only](#set-a-configuration-setting-read-only "Set a configuration setting read only") | ||
| * [List configuration setting revisions](#list-configuration-setting-revisions "List configuration setting revisions") | ||
| * [Delete a configuration setting](#set-a-configuration-setting "Delete a configuration setting") | ||
|
|
||
| ### Add a configuration setting | ||
|
|
||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| func ExampleAddConfigurationSetting() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| // Create configuration setting | ||
| resp, err := client.AddSetting( | ||
| context.TODO(), | ||
| "key", | ||
| to.Ptr("value"), | ||
| &azappconfig.AddSettingOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| fmt.Println(*resp.Value) | ||
| } | ||
| ``` | ||
| ### Get a configuration setting | ||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| func ExampleGetConfigurationSetting() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| // Get configuration setting | ||
| resp, err := client.GetSetting( | ||
| context.TODO(), | ||
| "key", | ||
| &azappconfig.GetSettingOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| fmt.Println(*resp.Value) | ||
| } | ||
| ``` | ||
| ### Set a configuration setting | ||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| func ExampleSetConfigurationSetting() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| // Set configuration setting | ||
| resp, err := client.SetSetting( | ||
| context.TODO(), | ||
| "key", | ||
| to.Ptr("new_value"), | ||
| &azappconfig.SetSettingOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| fmt.Println(*resp.Value) | ||
| } | ||
| ``` | ||
| ### Set a configuration setting read only | ||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| func ExampleSetConfigurationSettingReadOnly() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| // Set configuration setting read only | ||
| resp, err := client.SetReadOnly( | ||
| context.TODO(), | ||
| "key", | ||
| true, | ||
| &azappconfig.SetReadOnlyOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| fmt.Println(*resp.Value) | ||
| fmt.Println(*resp.IsReadOnly) | ||
| // Remove read only status | ||
| resp, err := client.SetReadOnly( | ||
| context.TODO(), | ||
| "key", | ||
| false, | ||
| &azappconfig.SetReadOnlyOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| fmt.Println(*resp.Value) | ||
| fmt.Println(*resp.IsReadOnly) | ||
| } | ||
| go get github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig | ||
| ``` | ||
|
|
||
| ### List configuration setting revisions | ||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| ### Prerequisites | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| * An [Azure subscription][azure_sub] | ||
| * 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][appconfig_portal] or with the [Azure CLI][appconfig_cli]. | ||
|
|
||
| func ExampleListRevisions() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| ### Authentication | ||
|
|
||
| revPgr := client.NewListRevisionsPager( | ||
| azappconfig.SettingSelector{ | ||
| KeyFilter: to.Ptr("*"), | ||
| LabelFilter: to.Ptr("*"), | ||
| Fields: azappconfig.AllSettingFields(), | ||
| }, | ||
| nil) | ||
| Azure App Configuration supports authenticating with Azure Active Directory and connection strings. To authenticate with Azure Active Directory, use the [azappconfig.NewClient][azappconfig_newclient] constructor and to authenticate with a connection string, use the [azappconfig.NewClientFromConnectionString][azappconfig_newclientfromconnectionstring] constructor. For simplicity, the examples demonstrate authenticating with a connection string. | ||
|
|
||
| for revPgr.More() { | ||
| if revResp, revErr := revPgr.NextPage(context.TODO()); revErr == nil { | ||
| for _, setting := range revResp.Settings { | ||
| fmt.Println(*setting.Key) | ||
| fmt.Println(*setting.Label) | ||
| fmt.Println(*setting.Value) | ||
| fmt.Println(*setting.IsReadOnly) | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| See the [azidentity][azure_identity] documentation for more information about possible Azure Active Directory credential types. | ||
|
|
||
| ### Delete a configuration setting | ||
| ## Key concepts | ||
|
|
||
| ```go | ||
| import ( | ||
| "fmt" | ||
| "os" | ||
| A [Setting][azappconfig_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. | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| ) | ||
| The [Label][label_concept] 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. | ||
|
|
||
| func ExampleDeleteConfigurationSetting() { | ||
| connectionString := os.Getenv("APPCONFIGURATION_CONNECTION_STRING") | ||
| client, err := azappconfig.NewClientFromConnectionString(connectionString, nil) | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| 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. | ||
|
|
||
| // Delete configuration setting | ||
| resp, err := client.DeleteSetting( | ||
| context.TODO(), | ||
| "key", | ||
| &azappconfig.DeleteSettingOptions{ | ||
| Label: to.Ptr("label"), | ||
| }) | ||
| ## Examples | ||
|
|
||
| if err != nil { | ||
| panic(err) | ||
| } | ||
| fmt.Println(*resp.Key) | ||
| fmt.Println(*resp.Label) | ||
| } | ||
| ``` | ||
| Examples for various scenarios can be found on [pkg.go.dev][azappconfig_examples] or in the `example*_test.go` files in our GitHub repo for [azappconfig][azappconfig_src]. | ||
|
|
||
| ## 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. | ||
|
|
@@ -339,12 +56,18 @@ For more information, see the | |
| [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or | ||
| contact [email protected] with any additional questions or comments. | ||
|
|
||
| [azure_cloud_shell]: https://shell.azure.com/bash | ||
| [azure_identity]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity | ||
| [azure_sub]: https://azure.microsoft.com/free/ | ||
| [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ | ||
| [appconfig_docs]: https://docs.microsoft.com/azure/azure-app-configuration/ | ||
| [goget_azappconfig]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig | ||
| [appconfig_client_src]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/data/azappconfig/client.go | ||
|  | ||
| [appconfig_docs]: https://learn.microsoft.com/azure/azure-app-configuration/ | ||
| [appconfig_portal]: https://learn.microsoft.com/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-portal | ||
| [appconfig_cli]: https://learn.microsoft.com/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-cli | ||
| [label_concept]: https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys | ||
| [azappconfig]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig | ||
| [azappconfig_newclient]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig#NewClient | ||
| [azappconfig_newclientfromconnectionstring]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig#NewClientFromConnectionString | ||
| [azappconfig_examples]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig#pkg-examples | ||
| [azappconfig_setting]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig#Setting | ||
| [azappconfig_src]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/data/azappconfig | ||
|
|
||
|  | ||
Oops, something went wrong.