Questo documento descrive come leggere e modificare in modo programmatico l'insieme di parametri e condizioni in formato JSON noto come modello Remote Config. Ciò consente di apportare modifiche al modello il backend che l'app client può recuperare utilizzando la libreria client.
Utilizzando l'API REST di Remote Config o i Admin SDK descritti in questa guida, puoi bypassare la gestione del modello nella console Firebase per integrare direttamente le modifiche di Remote Config nei tuoi processi. Ad esempio, con Remote Config API di backend, potresti:
- Pianificazione degli aggiornamenti Remote Config. Utilizzando le chiamate API insieme a un cron job, puoi modificare i valori Remote Config in base a una pianificazione regolare.
- Importa i valori di configurazione in gruppo per una transizione efficiente dal tuo sistema proprietario a Firebase Remote Config.
Utilizza Remote Config con Cloud Functions for Firebase, modificando i valori nell'app in base agli eventi che si verificano lato server. Ad esempio, puoi utilizzare Remote Config per promuovere una nuova funzionalità nella tua app e disattivare automaticamente la promozione quando rilevi che un numero sufficiente di utenti ha interagito con la nuova funzionalità.
Le seguenti sezioni di questa guida descrivono le operazioni che puoi eseguire con le API di backend Remote Config. Per esaminare del codice che esegue queste attività tramite l'API REST, consulta una di queste app di esempio:
- Guida rapida di Java dell'API REST di Firebase Remote Config
- Guida rapida di Node.js dell'API REST di Firebase Remote Config
- Guida rapida di Python dell'API REST di Firebase Remote Config
Modificare Remote Config utilizzando l'SDK Firebase Admin
Admin SDK è un insieme di librerie server che ti consente di interagire con Firebase da ambienti con privilegi. Oltre a eseguire aggiornamenti su Remote Config, Admin SDK consente la generazione e la verifica di token di autenticazione Firebase, la lettura e la scrittura da Realtime Database e così via. Per scoprire di più sui Admin SDKprerequisiti e sulla configurazione, consulta Aggiungere l'SDK Firebase Admin al server.
In un flusso Remote Config tipico, potresti recuperare il modello corrente, modificare alcuni parametri o gruppi di parametri e condizioni, convalidare il modello e poi pubblicarlo. Prima di effettuare queste chiamate API, devi autorizzare le richieste dall'SDK.
Inizializza l'SDK e autorizza le richieste API
Quando viene inizializzato Admin SDK senza parametri, l'SDK utilizza
le credenziali predefinite dell'applicazione Google
e legge le opzioni dalla variabile di ambiente FIREBASE_CONFIG.
Se i contenuti della variabile FIREBASE_CONFIG iniziano con un {, sarà
analizzato come oggetto JSON. In caso contrario, l'SDK presuppone che la stringa sia
il nome di un file JSON contenente le opzioni.
Ad esempio:
Node.js
const admin = require('firebase-admin');
admin.initializeApp();Java
FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
.setCredentials(GoogleCredentials.fromStream(serviceAccount))
.build();
FirebaseApp.initializeApp(options);Ottieni il modello Remote Config corrente
Quando lavori con i modelli di Remote Config, tieni presente che questi viene eseguito il controllo delle versioni e che ogni versione ha una durata limitata creazione al momento della sostituzione con un aggiornamento: 90 giorni, con un limite totale su 300 versioni archiviate. Per ulteriori informazioni, consulta la sezione Modelli e versionamento.
Puoi utilizzare le API di backend per ottenere la versione attiva corrente del Modello Remote Config in formato JSON.
I parametri e i valori parametro creati specificatamente come varianti in un A/B Testing esperimento non è incluso nei modelli esportati.
Per scaricare il modello:
Node.js
function getTemplate() {
var config = admin.remoteConfig();
config.getTemplate()
.then(function (template) {
console.log('ETag from server: ' + template.etag);
var templateStr = JSON.stringify(template);
fs.writeFileSync('config.json', templateStr);
})
.catch(function (err) {
console.error('Unable to get template');
console.error(err);
});
}Java
Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());Modificare i parametri di Remote Config
Puoi modificare e aggiungere in modo programmatico i parametri Remote Config. gruppi di parametri. Ad esempio, a un gruppo di parametri esistente denominato "new_menu" Per controllare la visualizzazione delle informazioni stagionali, puoi aggiungere un parametro:
Node.js
function addParameterToGroup(template) {
template.parameterGroups['new_menu'].parameters['spring_season'] = {
defaultValue: {
useInAppDefault: true
},
description: 'spring season menu visibility.',
};
}Java
template.getParameterGroups().get("new_menu").getParameters()
.put("spring_season", new Parameter()
.setDefaultValue(ParameterValue.inAppDefault())
.setDescription("spring season menu visibility.")
);L'API consente di creare nuovi parametri e gruppi di parametri oppure di modificare valori predefiniti, valori condizionali e descrizioni. In tutti i casi, devi pubblicare esplicitamente il modello dopo e apportare modifiche.
Modificare le condizioni di Remote Config
Puoi modificare e aggiungere Remote Config condizioni e valori condizionali in modo programmatico. Ad esempio, per aggiungere una nuova condizione:
Node.js
function addNewCondition(template) {
template.conditions.push({
name: 'android_en',
expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
tagColor: 'BLUE',
});
}Java
template.getConditions().add(new Condition("android_en",
"device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));In tutti i casi, devi pubblicare esplicitamente il modello dopo e apportare modifiche.
Le API di backend Remote Config forniscono diverse condizioni e confronti che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. A scoprire di più sulle condizioni e sugli operatori supportati per queste condizioni, consulta il riferimento all'espressione condizionale.
Convalida il modello Remote Config
Facoltativamente, puoi convalidare gli aggiornamenti prima di pubblicarli, come mostrato:
Node.js
function validateTemplate(template) {
admin.remoteConfig().validateTemplate(template)
.then(function (validatedTemplate) {
// The template is valid and safe to use.
console.log('Template was valid and safe to use');
})
.catch(function (err) {
console.error('Template is invalid and cannot be published');
console.error(err);
});
}Java
try {
Template validatedTemplate = FirebaseRemoteConfig.getInstance()
.validateTemplateAsync(template).get();
System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
if (e.getCause() instanceof FirebaseRemoteConfigException) {
FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
System.out.println("Template is invalid and cannot be published");
System.out.println(rcError.getMessage());
}
}Questo processo di convalida
verifica la presenza di errori come chiavi duplicate per parametri e condizioni,
nomi di condizioni non validi, condizioni inesistenti oppure etag con formattazione errata.
Ad esempio, una richiesta contenente più del numero consentito di chiavi (2000) restituirà il messaggio di errore Param count too large.
Pubblica il modello Remote Config
Dopo aver recuperato un modello e averlo rivisto con gli aggiornamenti che preferisci, puoi pubblicarlo. La pubblicazione di un modello come descritto sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione di uno superiore a modello che ha sostituito.
Se necessario, puoi utilizzare l'API REST per eseguire il rollback alla versione precedente. Per ridurre il rischio di errori in un aggiornamento, puoi convalidare prima della pubblicazione.
Remote Config Le personalizzazioni e le condizioni sono incluse nei modelli scaricati, pertanto è importante tenere presente le seguenti limitazioni quando si tenta di pubblicare in un progetto diverso:
Le personalizzazioni non possono essere importate da un progetto all'altro.
Ad esempio, se nel progetto hai attivato le personalizzazioni e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non in un altro progetto, a meno che non elimini le personalizzazioni dal modello.
Le condizioni possono essere importate da un progetto all'altro, ma tieni presente che qualsiasi valori condizionali specifici (come ID app o segmenti di pubblico), devono esistere in il progetto di destinazione prima della pubblicazione.
Ad esempio, se hai un parametro Remote Config che utilizza una condizione che specifica un valore della piattaforma
iOS, il modello può essere pubblicato in un altro progetto, perché i valori della piattaforma sono gli stessi per qualsiasi progetto. Tuttavia, se contiene una condizione che si basa su un ID app o un segmento di pubblico specifico che non esiste nel progetto di destinazione, la convalida non andrà a buon fine.Se il modello che intendi pubblicare contiene condizioni basate su Google Analytics, Google Analytics deve essere attivato nel progetto di destinazione.
Node.js
function publishTemplate() {
var config = admin.remoteConfig();
var template = config.createTemplateFromJSON(
fs.readFileSync('config.json', 'UTF8'));
config.publishTemplate(template)
.then(function (updatedTemplate) {
console.log('Template has been published');
console.log('ETag from server: ' + updatedTemplate.etag);
})
.catch(function (err) {
console.error('Unable to publish template.');
console.error(err);
});
}Java
try {
Template publishedTemplate = FirebaseRemoteConfig.getInstance()
.publishTemplateAsync(template).get();
System.out.println("Template has been published");
// See the ETag of the published template.
System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
if (e.getCause() instanceof FirebaseRemoteConfigException) {
FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
System.out.println("Unable to publish template.");
System.out.println(rcError.getMessage());
}
}Modificare Remote Config utilizzando l'API REST
Questa sezione descrive le funzionalità principali
Remote Config API REST in https://firebaseremoteconfig.googleapis.com.
Per informazioni dettagliate, consulta il riferimento API.
Ottieni un token di accesso per autenticare e autorizzare le richieste API
I progetti Firebase supportano Google account di servizio, che puoi utilizzare per chiamare Firebase le API server dal server delle app o dall'ambiente attendibile. Se stai sviluppando o eseguendo il deployment della tua applicazione on-premise, puoi utilizzare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste del server.
Per autenticare un account di servizio e autorizzarlo per accedere ai servizi Firebase, devi generare un file di chiave privata in JSON formato.
Per generare un file di chiave privata per il tuo account di servizio:
Nella console Firebase, apri Impostazioni > Account di servizio.
Fai clic su Genera nuova chiave privata, poi conferma facendo clic su Genera chiave.
Archivia in modo sicuro il file JSON contenente la chiave.
Quando esegui l'autorizzazione tramite un account di servizio, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS o passare esplicitamente il percorso della chiave dell'account di servizio nel codice. La prima opzione è più sicura ed è vivamente consigliata.
Per impostare la variabile di ambiente:
Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.
Linux o macOS
export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"
Windows
Con PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"
Dopo aver completato i passaggi precedenti, le credenziali predefinite dell'applicazione (ADC) possono determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account servizio durante i test o l'esecuzione in ambienti non Google.
Utilizza le tue credenziali Firebase insieme alla libreria di autenticazione Google per la tua lingua preferita per recuperare un token di accesso OAuth 2.0 di breve durata:
Node.js
function getAccessToken() {
return admin.credential.applicationDefault().getAccessToken()
.then(accessToken => {
return accessToken.access_token;
})
.catch(err => {
console.error('Unable to get access token');
console.error(err);
});
}
In questo esempio, la libreria client dell'API di Google autentica la richiesta con un token web JSON o JWT. Per ulteriori informazioni, consulta Token web JSON.
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = ServiceAccountCredentials.from_json_keyfile_name(
'service-account.json', SCOPES)
access_token_info = credentials.get_access_token()
return access_token_info.access_token
Java
public static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refreshAccessToken();
return googleCredentials.getAccessToken().getTokenValue();
}
Dopo la scadenza del token di accesso, viene chiamato il metodo di aggiornamento del token per recuperare un token di accesso aggiornato.
Per autorizzare l'accesso a Remote Config, richiedi l'ambito
https://www.googleapis.com/auth/firebase.remoteconfig.
Modifica il modello Remote Config
Quando lavori con i modelli di Remote Config, tieni presente che questi viene eseguito il controllo delle versioni e che ogni versione ha una durata limitata creazione al momento della sostituzione con un aggiornamento: 90 giorni, con un limite totale su 300 versioni archiviate. Per ulteriori informazioni, consulta la sezione Modelli e versionamento.
Recupera il modello corrente di Remote Config
Puoi utilizzare le API di backend per ottenere la versione attiva corrente del Modello Remote Config in formato JSON.
I parametri e i valori parametro creati specificatamente come varianti in un A/B Testing esperimento non è incluso nei modelli esportati.
Usa i seguenti comandi:
cURL
curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename
Questo comando genera il payload JSON in un file e le intestazioni (incluso l'Etag) in un file separato.
Richiesta HTTP non elaborata
Host: firebaseremoteconfig.googleapis.com GET /v1/projects/my-project-id/remoteConfig HTTP/1.1 Authorization: Bearer token Accept-Encoding: gzip
Questa chiamata API restituisce il seguente JSON, insieme a un'intestazione separata che includa un eTag che utilizzi per successiva richiesta.
Convalida il modello Remote Config
Se vuoi, puoi convalidare gli aggiornamenti prima di pubblicarli.
Convalida gli aggiornamenti del modello aggiungendo alla richiesta di pubblicazione il parametro URL ?validate_only=true.
Nella risposta, un codice di stato 200 e un tag elettronico aggiornato con il suffisso -0.
significa che l'aggiornamento è stato convalidato correttamente. Qualsiasi risposta diversa da 200 indica che i dati JSON contengono errori che devi correggere prima della pubblicazione.
Aggiorna il modello Remote Config
Dopo aver recuperato un modello e rivisto i contenuti JSON con gli aggiornamenti che preferisci, puoi pubblicarlo. La pubblicazione di un modello come descritto sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione di uno superiore a modello che ha sostituito.
Se necessario, puoi utilizzare l'API REST per eseguire il rollback alla versione precedente. Per ridurre il rischio di errori in un aggiornamento, puoi convalidare prima della pubblicazione.
Remote Config Le personalizzazioni e le condizioni sono incluse nei modelli scaricati, pertanto è importante tenere presente le seguenti limitazioni quando si tenta di pubblicare in un progetto diverso:
Le personalizzazioni non possono essere importate da un progetto all'altro.
Ad esempio, se nel progetto hai attivato le personalizzazioni e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non in un altro progetto, a meno che non elimini le personalizzazioni dal modello.
Le condizioni possono essere importate da un progetto all'altro, ma tieni presente che qualsiasi valori condizionali specifici (come ID app o segmenti di pubblico), devono esistere in il progetto di destinazione prima della pubblicazione.
Ad esempio, se hai un parametro Remote Config che utilizza una condizione che specifica un valore della piattaforma
iOS, il modello può essere pubblicato in un altro progetto, perché i valori della piattaforma sono gli stessi per qualsiasi progetto. Tuttavia, se contiene una condizione che si basa su un ID app o un segmento di pubblico specifico che non esiste nel progetto di destinazione, la convalida non andrà a buon fine.Se il modello che intendi pubblicare contiene condizioni basate su Google Analytics, Google Analytics deve essere attivato nel progetto di destinazione.
cURL
curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename
Per questo comando curl, puoi specificare i contenuti utilizzando il carattere "@" seguito dal nome file.
Richiesta HTTP non elaborata
Host: firebaseremoteconfig.googleapis.com PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1 Content-Length: size Content-Type: application/json; UTF8 Authorization: Bearer token If-Match: expected ETag Accept-Encoding: gzip JSON_HERE
Poiché si tratta di una richiesta di scrittura, l'ETag
viene modificato da questo comando e viene fornito un ETag aggiornato
del comando PUT successivo.
Modificare le condizioni di Remote Config
Puoi modificare in modo programmatico le condizioni e i valori condizionali Remote Config. Con l'API REST, devi modificare direttamente il modello per modificare le condizioni prima di pubblicarlo.
{
"conditions": [{
"name": "android_english",
"expression": "device.os == 'android' && device.country in ['us', 'uk']",
"tagColor": "BLUE"
}, {
"name": "tenPercent",
"expression": "percent <= 10",
"tagColor": "BROWN"
}],
"parameters": {
"welcome_message": {
"defaultValue": {
"value": "Welcome to this sample app"
},
"conditionalValues": {
"tenPercent": {
"value": "Welcome to this new sample app"
}
},
"description": "The sample app's welcome message"
},
"welcome_message_caps": {
"defaultValue": {
"value": "false"
},
"conditionalValues": {
"android_english": {
"value": "true"
}
},
"description": "Whether the welcome message should be displayed in all capital letters."
}
}
}
Le modifiche descritte in precedenza definiscono prima un insieme di condizioni definisce i valori predefiniti e il parametro basato sulla condizione (valori condizionali) per ogni parametro. Aggiunge inoltre una descrizione facoltativa per ogni elemento; come i commenti al codice, sono destinati agli sviluppatori e non vengono visualizzati nell'app. Un ETag è anche ai fini del controllo della versione.
Le API di backend Remote Config forniscono diverse condizioni e confronti Operatori che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. A scoprire di più sulle condizioni e sugli operatori supportati per queste condizioni, consulta il riferimento all'espressione condizionale.
Codici di errore HTTP
| Codice di stato | Significato |
|---|---|
| 200 | Aggiornamento completato |
| 400 | Si è verificato un errore di convalida. Ad esempio, una richiesta contenente più di
consentito (2000) restituisce 400 (Richiesta non valida) con
il messaggio di errore: Param count too large.
Inoltre, questo codice di stato HTTPS può verificarsi nelle due situazioni seguenti:
|
| 401 | Si è verificato un errore di autorizzazione (non è stato fornito alcun token di accesso oppure L'API REST Firebase Remote Config non è stata aggiunta al progetto in Cloud Developer Console) |
| 403 | Si è verificato un errore di autenticazione (è stato fornito il token di accesso errato) |
| 500 | Si è verificato un errore interno. Se si verifica questo errore, invia un ticket di assistenza Firebase |
Un codice di stato pari a 200 indica che il modello Remote Config (parametri, valori e condizioni per il progetto) è stato aggiornato ed è ora disponibile per le app che utilizzano questo progetto. Altri codici di stato indicano che il modello Remote Config esistente in precedenza è ancora in vigore.
Dopo aver inviato gli aggiornamenti al modello, vai alla console Firebase per verificare che le modifiche vengano visualizzate come previsto. Questo aspetto è fondamentale perché
l'ordine delle condizioni influisce sul modo in cui vengono valutate (la prima condizione che
valuta l'applicazione di true).
Utilizzo di ETag e aggiornamenti forzati
L'API REST Remote Config utilizza un tag entità (ETag) per evitare condizioni di gara e aggiornamenti sovrapposti alle risorse. Per scoprire di più sugli ETag, consulta ETag - HTTP.
Per l'API REST, Google consiglia di memorizzare nella cache
l'ETag fornito dal comando GET più recente e utilizza quel valore ETag
nell'intestazione della richiesta If-Match durante l'invio di comandi PUT. Se PUT
genera un codice di stato HTTPS 409, devi emettere un nuovo codice GET
per acquisire un nuovo ETag e un nuovo modello da usare con il prossimo comando PUT.
È possibile eludere l'ETag e la protezione che fornisce,
forzando l'aggiornamento del modello Remote Config come segue: If-Match: *
Tuttavia, questo approccio è sconsigliato perché rischia di causare la perdita
aggiornamenti al modello Remote Config se più clienti stanno aggiornando il
Modello Remote Config. Questo tipo di conflitto potrebbe verificarsi con più
client che utilizzano l'API o con aggiornamenti in conflitto da parte di client API e
Firebase utenti della console.
Per indicazioni su come gestire le versioni dei modelli Remote Config, consulta Modelli e versionamento di Remote Config.