From 9f9cbc409649eebd099c36efbeb68d37adb10d75 Mon Sep 17 00:00:00 2001 From: Richard Park Date: Thu, 5 Sep 2019 09:07:00 -0700 Subject: [PATCH] Adding documentation for appconfig --- .../review/app-configuration.api.md | 10 +- .../src/appConfigCredential.ts | 14 ++- .../app-configuration/src/index.ts | 95 +++++++++++++++++++ .../app-configuration/test/index.spec.ts | 32 ++++++- 4 files changed, 136 insertions(+), 15 deletions(-) diff --git a/sdk/appconfiguration/app-configuration/review/app-configuration.api.md b/sdk/appconfiguration/app-configuration/review/app-configuration.api.md index e0026786e94e..2eacf0a0c391 100644 --- a/sdk/appconfiguration/app-configuration/review/app-configuration.api.md +++ b/sdk/appconfiguration/app-configuration/review/app-configuration.api.md @@ -16,23 +16,16 @@ export type AddConfigurationSettingOptions = ModelConfigurationClientCreateOrUpd // @public (undocumented) export type AddConfigurationSettingsResponse = ModelCreateOrUpdateConfigurationSettingResponse; -// @public (undocumented) +// @public export class AppConfigurationClient { constructor(connectionString: string); constructor(uri: string, credential: TokenCredential); - // (undocumented) addConfigurationSetting(key: string, configSettings: AddConfigurationSettingConfig, options?: AddConfigurationSettingOptions): Promise; - // (undocumented) deleteConfigurationSetting(key: string, options: DeleteConfigurationSettingOptions): Promise; - // (undocumented) getConfigurationSetting(key: string, options?: GetConfigurationSettingOptions): Promise; - // (undocumented) listConfigurationSettings(options?: ListConfigurationSettingsOptions): Promise; - // (undocumented) listRevisions(options?: ListRevisionsOptions): Promise; - // (undocumented) setConfigurationSetting(key: string, configSettings: SetConfigurationSettingConfig, options?: SetConfigurationSettingOptions): Promise; - // (undocumented) updateConfigurationSetting(key: string, configSettings: UpdateConfigurationSettingConfig, options?: UpdateConfigurationSettingOptions): Promise; } @@ -50,7 +43,6 @@ export type DeleteConfigurationSettingResponse = ModelDeleteConfigurationSetting // @public (undocumented) export interface ETagOption { - // (undocumented) etag?: string; } diff --git a/sdk/appconfiguration/app-configuration/src/appConfigCredential.ts b/sdk/appconfiguration/app-configuration/src/appConfigCredential.ts index 2133154b5ed1..b147a6244461 100644 --- a/sdk/appconfiguration/app-configuration/src/appConfigCredential.ts +++ b/sdk/appconfiguration/app-configuration/src/appConfigCredential.ts @@ -1,6 +1,10 @@ import * as crypto from "crypto"; import { ServiceClientCredentials, WebResource, URLBuilder } from "@azure/core-http"; +/** + * @internal + * @ignore + */ export class AppConfigCredential implements ServiceClientCredentials { private credential: string; private secret: string; @@ -10,6 +14,12 @@ export class AppConfigCredential implements ServiceClientCredentials { this.secret = secret; } + /** + * Signs a request with the values provided in the credential and secret parameter. + * + * @param {WebResource} webResource The WebResource to be signed. + * @returns {Promise} The signed request object. + */ signRequest(webResource: WebResource): Promise { const verb = webResource.method.toUpperCase() const utcNow = new Date().toUTCString(); @@ -29,8 +39,8 @@ export class AppConfigCredential implements ServiceClientCredentials { const decodedSecret = Buffer.from(this.secret, "base64"); var signature = crypto.createHmac("sha256", decodedSecret) - .update(stringToSign) - .digest("base64"); + .update(stringToSign) + .digest("base64"); webResource.headers.set("x-ms-date", utcNow); webResource.headers.set("x-ms-content-sha256", contentHash); diff --git a/sdk/appconfiguration/app-configuration/src/index.ts b/sdk/appconfiguration/app-configuration/src/index.ts index 0f15c35bb951..d9fadb23be73 100644 --- a/sdk/appconfiguration/app-configuration/src/index.ts +++ b/sdk/appconfiguration/app-configuration/src/index.ts @@ -47,31 +47,52 @@ const deserializationContentTypes = { } export interface ETagOption { + /** + * Entity tag (etag) of the object + */ etag?: string; } export type AddConfigurationSettingConfig = Pick>; export type AddConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams; export type AddConfigurationSettingsResponse = ModelCreateOrUpdateConfigurationSettingResponse; + export type DeleteConfigurationSettingOptions = ModelConfigurationClientDeleteConfigurationSettingOptionalParams & ETagOption; export type DeleteConfigurationSettingResponse = ModelDeleteConfigurationSettingResponse; + export type GetConfigurationSettingOptions = ModelConfigurationClientGetConfigurationSettingOptionalParams; export type GetConfigurationSettingResponse = ModelGetConfigurationSettingResponse; + export type ListConfigurationSettingsOptions = ModelConfigurationClientListConfigurationSettingsOptionalParams; export type ListConfigurationSettingsResponse = ModelListConfigurationSettingsResponse; + export type ListRevisionsOptions = ModelConfigurationClientListRevisionsOptionalParams; export type ListRevisionsResponse = ModelListRevisionsResponse; + export type SetConfigurationSettingConfig = Pick>; export type SetConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams; export type SetConfigurationSettingResponse = ModelCreateOrUpdateConfigurationSettingResponse; + export type UpdateConfigurationSettingConfig = Pick>; export type UpdateConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams; export type UpdateConfigurationSettingResponse = ModelCreateOrUpdateConfigurationSettingResponse; +/** + * Client for the Azure App Configuration service. + */ export class AppConfigurationClient { private client: ConfigurationClient; + /** + * Initializes a new instance of the AppConfigurationClient class. + * @param connectionString Connection string needed for a client to connect to Azure. + */ constructor(connectionString: string); + /** + * Initializes a new instance of the AppConfigurationClient class. + * @param uri The base URI for the Azure service + * @param credential The credentials to use for authentication. + */ constructor(uri: string, credential: TokenCredential); constructor(uriOrConnectionString: string, credential?: TokenCredential) { const regexMatch = uriOrConnectionString.match(ConnectionStringRegex); @@ -91,6 +112,18 @@ export class AppConfigurationClient { } } + /** + * Add a setting into the Azure App Configuration service, failing if it + * already exists. + * + * Example usage: + * ```ts + * const result = await client.addConfigurationSetting("MyKey", { label: "MyLabel", value: "MyValue" }); + * ``` + * @param key The name of the key. + * @param configSettings A configuration value. + * @param options Optional parameters for the request. + */ addConfigurationSetting(key: string, configSettings: AddConfigurationSettingConfig, options: AddConfigurationSettingOptions = {}): Promise { // add the custom header if-none-match=* to only add the key-value if it doesn't already exist // create a copy of the options to avoid modifying the user's options @@ -105,6 +138,16 @@ export class AppConfigurationClient { return this.client.createOrUpdateConfigurationSetting(configSettings, key, options); } + /** + * Delete a setting from the Azure App Configuration service + * + * Example usage: + * ```ts + * const deletedSetting = await client.deleteConfigurationSetting("MyKey", { label: "MyLabel" }); + * ``` + * @param key The name of the key. + * @param options Optional parameters for the request. + */ deleteConfigurationSetting(key: string, options: DeleteConfigurationSettingOptions): Promise { // hoist the etag into a custom header to ensure this update fails if the setting has been updated options = { ...options }; @@ -118,18 +161,58 @@ export class AppConfigurationClient { return this.client.deleteConfigurationSetting(key, options); } + /** + * Gets a setting from the Azure App Configuration service. + * + * Example code: + * ```ts + * const setting = await client.getConfigurationSetting("MyKey", { label: "MyLabel" }); + * ``` + * @param key The name of the key. + * @param options Optional parameters for the request. + */ getConfigurationSetting(key: string, options?: GetConfigurationSettingOptions): Promise { return this.client.getConfigurationSetting(key, options); } + /** + * Lists settings from the Azure App Configuration service, optionally filtered by label, + * accept date time or name. + * + * Example code: + * ```ts + * const allSettingsWithLabel = await client.listConfigurationSettings({ label: "MyLabel" }); + * ``` + * @param options Optional parameters for the request. + */ listConfigurationSettings(options?: ListConfigurationSettingsOptions): Promise { return this.client.listConfigurationSettings(options); } + /** + * Lists revisions of a set of keys within the Azure App Configuration service. + * + * Example code: + * ```ts + * const revisionsForMyKey = await client.listRevisions({ key: ["MyKey"] }); + * ``` + * @param options Optional parameters for the request. + */ listRevisions(options?: ListRevisionsOptions): Promise { return this.client.listRevisions(options); } + /** + * Sets the value of a key in the Azure App Configuration service, allowing for an optional etag. + * @param key The name of the key. + * @param configSettings A configuration value. + * @param options Optional parameters for the request. + * + * Example code: + * ```ts + * let result = await client.setConfigurationSetting("MyKey", { value: "MyValue" }); + * ``` + */ setConfigurationSetting(key: string, configSettings: SetConfigurationSettingConfig, options: SetConfigurationSettingOptions = {}): Promise { // hoist the etag into a custom header to ensure this update fails if the setting has been updated options = { ...options }; @@ -148,6 +231,17 @@ export class AppConfigurationClient { return this.client.createOrUpdateConfigurationSetting(configSettings, key, { ...options, customHeaders }); } + /** + * Updates the value of a key in the Azure App Configuration service. + * + * Example code: + * ```ts + * await client.updateConfigurationSetting("MyKey", { label: "MyLabel", value: "MyValue" }); + * ``` + * @param key The name of the key. + * @param configSettings A configuration value. + * @param options Optional parameters for the request. + */ async updateConfigurationSetting(key: string, configSettings: UpdateConfigurationSettingConfig, options: UpdateConfigurationSettingOptions = {}): Promise { // retrieve existing configuration, and populate configSettings for missing fields that aren't null const existingConfigurationSettings = await this.getConfigurationSetting(key, { @@ -156,6 +250,7 @@ export class AppConfigurationClient { }); const updateConfigSettings = { ...configSettings }; + if (typeof updateConfigSettings.value === "undefined") { updateConfigSettings.value = existingConfigurationSettings.value; } diff --git a/sdk/appconfiguration/app-configuration/test/index.spec.ts b/sdk/appconfiguration/app-configuration/test/index.spec.ts index 3816cb007f0f..cd45277c54ef 100644 --- a/sdk/appconfiguration/app-configuration/test/index.spec.ts +++ b/sdk/appconfiguration/app-configuration/test/index.spec.ts @@ -35,10 +35,19 @@ describe("AppConfigurationClient", () => { }); describe("addConfigurationSetting", () => { + it("sample works", async () => { + const key = `addConfigSample-${Date.now()}`; + let result = await client.setConfigurationSetting(key, { + value: "MyValue" + }); + + assert.equal(key, result.key); + }); + it("adds a configuration setting", async () => { const key = `addConfigTest-${Date.now()}`; - const label = "test"; - const value = "foo"; + const label = "MyLabel"; + const value = "MyValue"; const result = await client.addConfigurationSetting(key, { label, value }); settings.push({ key, label }); @@ -73,8 +82,8 @@ describe("AppConfigurationClient", () => { describe("deleteConfigurationSetting", () => { it("deletes an existing configuration setting", async () => { const key = `deleteConfigTest-${Date.now()}`; - const label = "test"; - const value = "foo"; + const label = "MyLabel"; + const value = "MyValue"; // create configuration const result = await client.addConfigurationSetting(key, { label, value }); @@ -251,6 +260,21 @@ describe("AppConfigurationClient", () => { assert.equal(result.length, 2); }); + + it("sample code works", async () => { + const key = `listRevisionsSample-${Date.now()}`; + + // create a new setting + await client.addConfigurationSetting(key, { value: "foo1" }); + + // update it with a new value + await client.setConfigurationSetting(key, { value: "foo2" }); + + // retrieves all revisions matching that label + const result = await client.listRevisions({ key: [key] }); + + assert.equal(result.length, 2); + }) }); describe("setConfigurationSetting", () => {