SDK client App Configuration JavaScript
Per migliorare la sicurezza delle applicazioni che utilizzano il 'ibm-appconfiguration-js-client-sdk, si raccomanda vivamente di utilizzare una APIKey criptata al posto della APIKey semplice nel metodo init. Questa
modifica è fondamentale per evitare l'esposizione di credenziali sensibili quando gli utenti ispezionano l'applicazione web. Se si utilizza già una APIKey semplice, aggiornare l'applicazione per generare e utilizzare la APIKey crittografata
secondo i passaggi indicati qui.
Panoramica
IBM Cloud App Configuration L'SDK del client JavaScript viene utilizzato per eseguire la valutazione dei flag delle funzionalità e delle proprietà nelle applicazioni web e per tracciare metriche personalizzate per la sperimentazione in base alla configurazione del servizio IBM Cloud App Configuration.
IBM Cloud App Configuration è un servizio centralizzato per la gestione e la configurazione di funzionalità su IBM Cloud per l'uso con applicazioni web e mobili, microservizi e ambienti distribuiti ambienti distribuiti.
Strumentate le vostre applicazioni web con il App Configuration JavaScript Client SDK e utilizzare la dashboard, la CLI o l'API di App Configuration per definire i flag o le proprietà delle funzioni, organizzate in raccolte e mirate ai segmenti. Attivare gli stati dei flag delle funzioni nel per attivare o disattivare le funzioni nell'applicazione o nell'ambiente, quando necessario. Eseguite esperimenti e misurate l'effetto dei flag delle funzionalità sugli utenti finali tracciando metriche personalizzate. È anche possibile gestire le proprietà delle applicazioni distribuite in modo centralizzato.
Compatibilità con i browser: L'SDK è supportato da tutti i principali browser. Il browser deve supportare l'API 'fetch().
Integrazione di SDK client per JavaScript
Installazione
Installa l'SDK. Usare il seguente codice per installare come modulo dal gestore di pacchetti.
npm install ibm-appconfiguration-js-client-sdk
È possibile importare l'SDK nel tag script facendo riferimento a un sito ospitato sul backend o a un CDN, come segue:
Esempio:
<script type="text/javascript" src="https://unpkg.com/ibm-appconfiguration-js-client-sdk/dist/appconfiguration.js"></script>
Inizializza l'SDK
Inizializza l'sdk per connetterti con la tua istanza del servizio App Configuration.
const region = AppConfiguration.REGION_US_SOUTH;
const guid = '<guid>';
const apikey = '<encrypted_apikey>';
const collectionId = 'airlines-webapp';
const environmentId = 'dev';
const appConfigClient = AppConfiguration.getInstance();
async function initialiseAppConfig() {
appConfigClient.init(region, guid, apikey);
await appConfigClient.setContext(collectionId, environmentId);
}
try {
await initialiseAppConfig();
console.log("app configuration sdk init successful");
} catch (e) {
console.error("failed to initialise app configuration sdk", e);
}
Nel frammento precedente, la funzione asincrona initialiseAppConfig() restituirà un oggetto Promise<void> che si risolve quando le configurazioni vengono recuperate correttamente. Altrimenti, lancia un errore
se non ha successo.
Si prevede che l'inizializzazione venga effettuata una sola volta.
Dopo che l'SDK è stato inizializzato con successo, il flag e le proprietà della funzione possono essere recuperati utilizzando l' appConfigClient, come mostrato nel seguente frammento di codice.
Espandere per visualizzare lo snippet di esempio
// other-file.js
const appConfigClient = AppConfiguration.getInstance();
const feature = appConfigClient.getFeature('online-check-in');
const result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result);
const property = appConfigClient.getProperty('check-in-charges');
const result = property.getCurrentValue(entityId, entityAttributes);
console.log(result);
dove,
- regione: Nome della regione in cui viene creata l'istanza del servizio App Configuration. Vedere l'elenco delle località supportate qui. Ad esempio:
us-south,au-sydecc. - guid: ID istanza del servizio App Configuration. Si ottiene dalla sezione credenziali di servizio della dashboard App Configuration.
- apikey: la APIKey crittografata generata come descritto qui.
- collectionId: ID della raccolta creata nell'istanza del servizio App Configuration nella sezione Collections.
- environmentId: ID dell'ambiente creato nell'istanza del servizio App Configuration nella sezione Environments.
Utilizzare sempre l'APIKey crittografata per evitare di esporre informazioni sensibili.
Assicurarsi di creare le credenziali del servizio con il ruolo 'Client SDK, che ha le autorizzazioni di accesso minime
adatte all'uso in applicazioni basate su browser.
Esempi per l'uso di API correlate a funzioni e proprietà
Vedi i seguenti esempi per l'utilizzo delle API correlate alla funzione.
Ottieni funzione singola
const feature = appConfigClient.getFeature('featureId'); // throws error incase the featureId is invalid or doesn't exist
console.log(`Feature Name ${feature.getFeatureName()} `);
console.log(`Feature Id ${feature.getFeatureId()} `);
console.log(`Feature Type ${feature.getFeatureDataType()} `);
Ottieni tutte le funzioni
const features = appConfigClient.getFeatures();
const feature = features['featureId'];
if (feature !== undefined) {
console.log(`Feature Name ${feature.getFeatureName()} `);
console.log(`Feature Id ${feature.getFeatureId()} `);
console.log(`Feature Type ${feature.getFeatureDataType()} `);
console.log(`Is feature enabled? ${feature.isEnabled()} `);
}
Valuta una funzione
Utilizzare il metodo 'feature.getCurrentValue(entityId, entityAttributes) per valutare il valore del flag della caratteristica. Questo metodo restituisce uno dei valori Abilitato / Disabilitato / Sovrascritto basato sulla valutazione.
Il tipo di dati del valore restituito corrisponde a quello dell'indicatore funzione.
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
entityId: ID dell'entità. Questo sarà un identificativo stringa relativo all'entità rispetto alla quale viene valutata la funzione. Ad esempio, un'entità può essere un'istanza di un'applicazione eseguita su un dispositivo mobile o un utente che accede all'applicazione web. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.entityAttributes: un oggetto JSON costituito dal nome attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se l'indicatore della funzione non è configurato con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per determinare se l'entità specificata soddisfa le regole di destinazione e restituisce il valore dell'indicatore della funzione appropriato.
Inviare metriche personalizzate
Registrate metriche personalizzate da utilizzare per la sperimentazione utilizzando la funzione di tracciamento.
appConfigClient.track(eventKey, entityId)
dove
eventKey: la chiave dell'evento per la metrica associata all'esperimento in corso. La chiave dell'evento nella metrica e la chiave dell'evento nel codice devono corrispondere esattamente.
Ottieni singola propriet ...
const property = appConfigClient.getProperty('propertyId'); // throws error incase the propertyId is invalid or doesn't exist
console.log(`Property Name ${property.getPropertyName()} `);
console.log(`Property Id ${property.getPropertyId()} `);
console.log(`Property Type ${property.getPropertyDataType()} `);
Ottieni tutte le proprietà
const properties = appConfigClient.getProperties();
const property = properties['propertyId'];
if (property !== undefined) {
console.log(`Property Name ${property.getPropertyName()} `);
console.log(`Property Id ${property.getPropertyId()} `);
console.log(`Property Type ${property.getPropertyDataType()} `);
}
Valuta una proprietà
Utilizzare il metodo property.getCurrentValue(entityId, entityAttributes) per valutare il valore della proprietà. Questo metodo restituisce il valore della proprietà predefinito o il relativo valore sovrascritto in base alla
valutazione. Il tipo di dati del valore restituito corrisponde a quello della proprietà.
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
entityId: ID dell'entità. Questo sarà un identificativo stringa relativo all'entità rispetto alla quale viene valutata la proprietà. Ad esempio, un'entità può essere un'istanza di un'applicazione eseguita su un dispositivo mobile o un utente che accede all'applicazione web. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.entityAttributes: un oggetto JSON costituito dal nome attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se la proprietà non è configurata con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per stabilire se l'entità specificata soddisfa le regole di destinazione e restituisce il valore della proprietà appropriato.
Registrazione
Impostare il livello di registrazione su uno dei seguenti: "debug" | "info" | "warning" | "error". Il livello di registrazione predefinito è info.
appConfigClient.setLogLevel('debug');
Tipi di dati supportati
Il servizio App Configuration consente di configurare il flag della funzione e le proprietà nei seguenti tipi di dati: Booleano, Numerico, stringa. Il tipo di dati String può avere il formato di una stringa di testo, JSON o YAML. L'SDK elabora ogni formato di conseguenza, come mostrato nella tabella seguente.
Visualizza tabella
| Valore della caratteristica o della proprietà | DataType | DataFormat | Tipo di dati restituiti ' da ' getCurrentValue() |
Output di esempio |
|---|---|---|---|---|
true |
BOOLEAN | non applicabile | boolean |
true |
25 |
NUMERIC | non applicabile | number |
25 |
| "una stringa di testo" | STRINGA | TESTO | string |
a string text |
{ |
STRINGA | JSON | JSON object |
{"firefox":{"name":"Firefox","pref_url":"about:config"}} |
uomini: |
STRINGA | YAML | string |
`"men:
|
Utilizzo del flag di funzionalità Esempio
const feature = appConfigClient.getFeature('json-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // JSON
// Example (traversing the returned JSON)
let result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key
const feature = appConfigClient.getFeature('yaml-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // YAML
feature.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)
Esempio di utilizzo della proprietà
const property = appConfigClient.getProperty('json-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // JSON
// Example (traversing the returned JSON)
let result = property.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key
const property = appConfigClient.getProperty('yaml-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // YAML
property.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)
Impostare un ascoltatore per le modifiche ai dati delle caratteristiche e delle proprietà
L'SDK fornisce un meccanismo basato sugli eventi per notificare in tempo reale le modifiche alla configurazione dei flag delle funzioni o delle proprietà. È possibile ascoltare l'evento 'configurationUpdate utilizzando lo stesso
appConfigClient.
appConfigClient.emitter.on('configurationUpdate', () => {
// **add your code**
// To find the effect of any configuration changes, you can call the feature or property related methods
// feature = appConfigClient.getFeature('online-check-in');
// newValue = feature.getCurrentValue(entityId, entityAttributes);
});
Esempi
Provate questa applicazione di esempio nella cartella esempi per saperne di più sulla valutazione delle caratteristiche e delle proprietà.
Licenza
Questo progetto è rilasciato sotto la licenza Apache 2.0. Il testo completo della licenza si trova in LICENZA