Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[appconfiguration] Update snippets #32487

Merged
merged 2 commits into from
Jan 9, 2025
Merged

[appconfiguration] Update snippets #32487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
65bf30d
[appconfiguration] Update snippets
mpodwysocki Jan 9, 2025
3409f22
Merge branch 'main' of https://github.com/Azure/azure-sdk-for-js into…
mpodwysocki Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions sdk/appconfiguration/app-configuration/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
<!-- dev-tool snippets ignore -->

# Release History

## 1.8.1 (Unreleased)
Expand All @@ -20,7 +22,7 @@

### Features Added

- Support `listLabels` method to list all the labels in the configuration setting store.
- Support `listLabels` method to list all the labels in the configuration setting store.

Example:

Expand All @@ -39,9 +41,10 @@ const allProdTags = client.listConfigurationSettings({
tagsFilter: ["production=prod*"],
});
```

See [`listConfigurationSettings.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/listConfigurationSettings.ts) for more information now how to use this feature.
- Add `tagsFilter` in `ConfigurationSettingsFilter` so that you can create snapshot by filtering configuration settings tags.

- Add `tagsFilter` in `ConfigurationSettingsFilter` so that you can create snapshot by filtering configuration settings tags.

## 1.6.1 (2024-07-11)

Expand All @@ -65,13 +68,10 @@ See [`listConfigurationSettings.ts`](https://github.com/Azure/azure-sdk-for-js/t

### Features Added

- With the new API version `2023-10-01`, the configuration snapshot feature is generally available.

This feature allows you to create snapshots by specifying key and label filters. These filters help capture the necessary configuration settings from your App Configuration instance, creating an immutable, composed view of the configuration store.

- With the new API version `2023-10-01`, the configuration snapshot feature is generally available.
This feature allows you to create snapshots by specifying key and label filters. These filters help capture the necessary configuration settings from your App Configuration instance, creating an immutable, composed view of the configuration store.
The filtered configuration settings are stored as a snapshot with the name provided during its creation.
`AppConfigurationClient` is enhanced to support new operations such as create, list archive, and recover operations with snapshots.

`AppConfigurationClient` is enhanced to support new operations such as create, list archive, and recover operations with snapshots.
See [`snapshot.ts`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/appconfiguration/app-configuration/samples/v1/typescript/src/snapshot.ts) for more information now how to use snapshots.

### Bugs Fixed
Expand Down Expand Up @@ -101,6 +101,7 @@ See [`listConfigurationSettings.ts`](https://github.com/Azure/azure-sdk-for-js/t
## 1.4.1 (2023-04-24)

### Features Added

- Added dependency on `@azure/logger` to help with debugging. [#23860](https://github.com/Azure/azure-sdk-for-js/pull/23860)

### Bugs Fixed
Expand Down
225 changes: 144 additions & 81 deletions sdk/appconfiguration/app-configuration/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,15 +61,14 @@ Authentication via service principal is done by:

Using [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#defaultazurecredential)

```javascript
const azureIdentity = require("@azure/identity");
const appConfig = require("@azure/app-configuration");

const credential = new azureIdentity.DefaultAzureCredential();
const client = new appConfig.AppConfigurationClient(
endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
credential
);
```ts snippet:ReadmeSampleCreateClient_Node
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);
```

More information about `@azure/identity` can be found [here](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md)
Expand All @@ -78,14 +77,16 @@ More information about `@azure/identity` can be found [here](https://github.com/

To authenticate with a resource in a [Sovereign Cloud](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud), you will need to set the `authorityHost` in the credential options or via the `AZURE_AUTHORITY_HOST` environment variable.

```javascript
const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");
```ts snippet:AuthenticatingWithAzureSovereignCloud
import { AppConfigurationClient } from "@azure/app-configuration";
import { DefaultAzureCredential, AzureAuthorityHosts } from "@azure/identity";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.azure.cn";
// Create an AppConfigurationClient that will authenticate through AAD in the China cloud
const client = new AppConfigurationClient(
endpoint, // ex: <https://<your appconfig resource>.azconfig.azure.cn>
new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina })
endpoint,
new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina }),
);
```

Expand All @@ -101,8 +102,11 @@ az appconfig credential list -g <resource-group-name> -n <app-configuration-reso

And in code you can now create your App Configuration client with the **connection string** you got from the Azure CLI:

```typescript
const client = new AppConfigurationClient("<connection string>");
```ts snippet:ReadmeSampleCreateClientWithConnectionString
import { AppConfigurationClient } from "@azure/app-configuration";

const connectionString = "Endpoint=https://example.azconfig.io;XXX=YYYY;YYY=ZZZZ";
const client = new AppConfigurationClient(connectionString);
```

## Key concepts
Expand All @@ -117,9 +121,17 @@ The client follows a simple design methodology - [`ConfigurationSetting`](https:

This means this pattern works:

```typescript
```ts snippet:ConfigurationSettingPattern
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const setting = await client.getConfigurationSetting({
key: "hello"
key: "hello",
});

setting.value = "new value!";
Expand All @@ -136,101 +148,134 @@ await client.deleteConfigurationSetting(setting);

or, for example, re-getting a setting:

```typescript
```ts snippet:ReGetSetting
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

let setting = await client.getConfigurationSetting({
key: "hello"
key: "hello",
});

// re-get the setting
setting = await client.getConfigurationSetting(setting);
```

The `2022-11-01-preview` API version supports configuration snapshots: immutable, point-in-time copies of a configuration store. Snapshots can be created with filters that determine which key-value pairs are contained within the snapshot, creating an immutable, composed view of the configuration store. This feature enables applications to hold a consistent view of configuration, ensuring that there are no version mismatches to individual settings due to reading as updates were made. For example, this feature can be used to create "release configuration snapshots" within an App Configuration. See [the _create and get a snapshot_ section](#create-and-get-a-setting) in the example below.
The `2022-11-01-preview` API version supports configuration snapshots: immutable, point-in-time copies of a configuration store. Snapshots can be created with filters that determine which key-value pairs are contained within the snapshot, creating an immutable, composed view of the configuration store. This feature enables applications to hold a consistent view of configuration, ensuring that there are no version mismatches to individual settings due to reading as updates were made. For example, this feature can be used to create "release configuration snapshots" within an App Configuration. See [the _create and get a snapshot_ section](#create-and-get-a-setting) in the example below.

## Examples

### Create and get a setting

```javascript
const appConfig = require("@azure/app-configuration");

const client = new appConfig.AppConfigurationClient(
"<App Configuration connection string goes here>"
);
```ts snippet:CreateSetting
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.setConfigurationSetting({
key: "testkey",
value: "testvalue",
// Labels allow you to create variants of a key tailored
// for specific use-cases like supporting multiple environments.
// https://docs.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
label: "optional-label",
});

async function run() {
const newSetting = await client.setConfigurationSetting({
key: "testkey",
value: "testvalue",
// Labels allow you to create variants of a key tailored
// for specific use-cases like supporting multiple environments.
// https://docs.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
label: "optional-label"
});

const retrievedSetting = await client.getConfigurationSetting({
key: "testkey",
label: "optional-label"
});

console.log("Retrieved value:", retrievedSetting.value);
}
const retrievedSetting = await client.getConfigurationSetting({
key: "testkey",
label: "optional-label",
});

run().catch((err) => console.log("ERROR:", err));
console.log("Retrieved value:", retrievedSetting.value);
```

### Create a snapshot

`beginCreateSnapshot` gives you the poller to poll for the snapshot creation.

```javascript
const { AppConfigurationClient } = require("@azure/app-configuration");

const client = new AppConfigurationClient(
"<App Configuration connection string goes here>"
);
`beginCreateSnapshot` gives you the poller to poll for the snapshot creation.

```ts snippet:CreateSnapshot
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

async function run() {
const key = "testkey";
const value = "testvalue";
const label = "optional-label";
// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

await client.addConfigurationSetting({
key,
value,
label
});
const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const poller = await client.beginCreateSnapshot({
name:"testsnapshot",
retentionPeriod: 2592000,
filters: [{keyFilter: key, labelFilter: label}],
});
const snapshot = await poller.pollUntilDone();
}
await client.addConfigurationSetting({
key,
value,
label,
});

run().catch((err) => console.log("ERROR:", err));
const poller = await client.beginCreateSnapshot({
name: "testsnapshot",
retentionPeriod: 2592000,
filters: [{ keyFilter: key, labelFilter: label }],
});
const snapshot = await poller.pollUntilDone();
```

You can also use `beginCreateSnapshotAndWait` to have the result of the creation directly after the polling is done.
```js
const snapshot = await client.beginCreateSnapshotAndWait({
name:"testsnapshot",

```ts snippet:CreateSnapshotAndWait
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const key = "testkey";
const value = "testvalue";
const label = "optional-label";

const snapshot = await client.beginCreateSnapshotAndWait({
name: "testsnapshot",
retentionPeriod: 2592000,
filters: [{keyFilter: key, labelFilter: label}],
filters: [{ keyFilter: key, labelFilter: label }],
});
```

### Get a snapshot

```js
```ts snippet:GetSnapshot
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshot = await client.getSnapshot("testsnapshot");
console.log("Retrieved snapshot:", retrievedSnapshot);
```

### List the `ConfigurationSetting` in the snapshot
```javascript

```ts snippet:ListSnapshotSettings
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const retrievedSnapshotSettings = await client.listConfigurationSettingsForSnapshot("testsnapshot");

for await (const setting of retrievedSnapshotSettings) {
Expand All @@ -239,7 +284,16 @@ for await (const setting of retrievedSnapshotSettings) {
```

### List all snapshots from the service
```javascript

```ts snippet:ListSnapshots
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

const snapshots = await client.listSnapshots();

for await (const snapshot of snapshots) {
Expand All @@ -248,7 +302,16 @@ for await (const snapshot of snapshots) {
```

### Recover and archive the snapshot
```javascript

```ts snippet:RecoverAndArchiveSnapshot
import { DefaultAzureCredential } from "@azure/identity";
import { AppConfigurationClient } from "@azure/app-configuration";

// The endpoint for your App Configuration resource
const endpoint = "https://example.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

// Snapshot is in ready status
const archivedSnapshot = await client.archiveSnapshot("testsnapshot");
console.log("Snapshot updated status is:", archivedSnapshot.status);
Expand All @@ -264,8 +327,8 @@ console.log("Snapshot updated status is:", recoverSnapshot.status);

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:

```javascript
const { setLogLevel } = require("@azure/logger");
```ts snippet:SetLogLevel
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```
Expand All @@ -274,7 +337,7 @@ For more detailed instructions on how to enable logs, you can look at the [@azur

### React Native support

React Native does not support some JavaScript API used by this SDK library so you need to provide polyfills for them. Please see our [React Native sample with Expo](https://github.com/Azure/azure-sdk-for-js/blob/main/samples/frameworks/react-native/appconfigBasic/README.md#add-polyfills) for more details.
React Native does not support some JavaScript API used by this SDK library so you need to provide polyfills for them. Please see our [React Native sample with Expo](https://github.com/Azure/azure-sdk-for-js/blob/main/samples/frameworks/react-native/appconfigBasic/README.md#add-polyfills) for more details.

## Next steps

Expand Down
Loading
Loading