Catch up on everthing we announced at this year's Firebase Summit. Learn more

Modifica la configurazione remota in modo programmatico

Questo documento descrive come è possibile programatically leggere e modificare il set di parametri e condizioni di JSON-formattati noto come il modello di configurazione remota . Ciò consente di apportare modifiche al modello nel back-end che l'app client può recuperare utilizzando la libreria client.

Utilizzando l' API REST Config a distanza o l' Admin SDK descritto in questa guida, è possibile ignorare la gestione del modello nella console Firebase di integrare direttamente Remote Config trasforma in vostri processi. Ad esempio, con le API di backend di Remote Config, puoi:

  • Pianificazione degli aggiornamenti Configurazione remota. Utilizzando le chiamate API insieme a un cron job, puoi modificare i valori di Remote Config a intervalli regolari.
  • I valori di importazione di configurazione lotto per la transizione in modo efficiente dal proprio sistema proprietario di Firebase Remote Config.
  • Utilizzare Config a distanza con funzioni cloud per Firebase, modifica dei valori nel vostro app in base agli eventi che accadono sul lato server. Ad esempio, puoi utilizzare Remote Config per promuovere una nuova funzionalità nella tua app e quindi disattivare automaticamente tale promozione quando rilevi che un numero sufficiente di persone ha interagito con la nuova funzionalità.

    Diagramma che mostra il backend di Remote Config che interagisce con strumenti e server personalizzati

Le sezioni seguenti di questa guida descrivono le operazioni che è possibile eseguire con le API di backend di Remote Config. Per esaminare del codice che esegue queste attività tramite l'API REST, vedere una di queste app di esempio:

Modifica la configurazione remota utilizzando l'SDK di amministrazione di Firebase

L'Admin SDK è un insieme di librerie di server che ti consentono di interagire con Firebase da ambienti privilegiati. Oltre a eseguire aggiornamenti a Remote Config, l'Admin SDK consente la generazione e la verifica dei token di autenticazione Firebase, la lettura e la scrittura da Realtime Database e così via. Per ulteriori informazioni sui prerequisiti Admin SDK e configurazione, vedere Aggiungere il Firebase Admin SDK al server .

In un tipico flusso di Remote Config, potresti ottenere il modello corrente, modificare alcuni parametri o gruppi di parametri e condizioni, convalidare il modello e quindi pubblicarlo. Prima di effettuare tali chiamate API, devi autorizzare le richieste dall'SDK.

Inizializza l'SDK e autorizza le richieste API

Quando si inizializza l'Admin SDK senza parametri, l'SDK utilizza Google Application credenziali predefinite e legge opzioni dal FIREBASE_CONFIG variabile d'ambiente. Se il contenuto del FIREBASE_CONFIG variabile inizia con un { verrà analizzato come un oggetto JSON. In caso contrario, l'SDK presuppone che la stringa sia il nome di un file JSON contenente le opzioni.

Per esempio:

Nodo.js

const admin = require('firebase-admin');
admin.initializeApp();

Giava

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Ottieni il modello di configurazione remota corrente

Quando lavori con i modelli di Remote Config, tieni presente che sono dotati di versione e che ogni versione ha una durata limitata dal momento della creazione al momento in cui la sostituisci con un aggiornamento: 90 giorni, con un limite totale di 300 versioni archiviate. Vedere Modelli e versioni per ulteriori informazioni.

Puoi utilizzare le API di backend per ottenere la versione attiva corrente del modello Remote Config in formato JSON. Per ottenere il modello:

Nodo.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);
      });
}

Giava

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

Modifica i parametri di configurazione remota

È possibile modificare e aggiungere a livello di programmazione parametri di Remote Config e gruppi di parametri. Ad esempio, a un gruppo di parametri esistente denominato "nuovo_menu" è possibile aggiungere un parametro per controllare la visualizzazione delle informazioni stagionali:

Nodo.js

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

Giava

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 o modificare valori predefiniti, valori condizionali e descrizioni. In tutti i casi, è necessario pubblicare esplicitamente il modello dopo aver apportato modifiche.

Modifica le condizioni di configurazione remota

È possibile modificare e aggiungere a livello di codice condizioni e valori condizionali di Remote Config. Ad esempio, per aggiungere una nuova condizione:

Nodo.js

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

Giava

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

In tutti i casi, è necessario pubblicare esplicitamente il modello dopo aver apportato modifiche.

Le API di backend di Remote Config forniscono diverse condizioni e operatori di confronto che puoi usare per modificare il comportamento e l'aspetto della tua app. Per saperne di più sulle condizioni e gli operatori supportati per queste condizioni, vedere il riferimento espressione condizionale .

Convalida il modello di configurazione remota

Facoltativamente, puoi convalidare i tuoi aggiornamenti prima di pubblicarli, come mostrato:

Nodo.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);
      });
}

Giava

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 o condizioni inesistenti o tag formattati in modo errato. Ad esempio, una richiesta contenente oltre il numero consentito di chiavi-2000-restituirebbe il messaggio di errore, Param count too large .

Pubblica il modello di configurazione remota

Dopo aver recuperato un modello e averlo rivisto con gli aggiornamenti desiderati, puoi pubblicarlo. La pubblicazione di un modello come descritto in questa sezione sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione maggiore di un numero rispetto al modello che ha sostituito.

Se necessario, è possibile utilizzare l'API REST per rollback alla versione precedente . Per mitigare il rischio di errori in un aggiornamento, è possibile convalidare prima della pubblicazione .

Nodo.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);
      });
}

Giava

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());
  }
}

Modifica la configurazione remota utilizzando l'API REST

Questa sezione descrive le principali funzionalità delle API REST Config remoto a https://firebaseremoteconfig.googleapis.com . Per tutti i dettagli, vedere il riferimento API .

Ottieni un token di accesso per autenticare e autorizzare le richieste API

Progetti Firebase supportano Google account di servizio , che è possibile utilizzare per chiamare le API di server Firebase dal server app o ambiente attendibile. Se stai sviluppando codice in locale o distribuendo la tua applicazione in locale, puoi usare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste del server.

Per autenticare un account di servizio e autorizzarlo ad accedere ai servizi Firebase, devi generare un file di chiave privata in formato JSON.

Per generare un file di chiave privata per il tuo account di servizio:

  1. Nella console Firebase, aprire Impostazioni> Account di servizio .

  2. Fare clic su Genera nuova chiave privata, quindi confermare facendo clic su Genera chiave.

  3. Archivia in modo sicuro il file JSON contenente la chiave.

Quando si autorizza tramite un account di servizio, sono disponibili due opzioni per fornire le credenziali alla propria applicazione. O si può impostare la GOOGLE_APPLICATION_CREDENTIALS variabile d'ambiente, oppure si può passare in modo esplicito il percorso della chiave account di servizio nel codice. La prima opzione è più sicura ed è fortemente consigliata.

Per impostare la variabile d'ambiente:

Impostare la variabile d'ambiente GOOGLE_APPLICATION_CREDENTIALS al percorso del file JSON che contiene il codice di account di servizio. Questa variabile si applica solo alla tua 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"

finestre

Con PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Dopo aver completato i passaggi precedenti, Application Default Credentials (ADC) è in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account di servizio durante il test o l'esecuzione in ambienti non Google.

Utilizzare le credenziali Firebase insieme al Auth Biblioteca di Google per la vostra lingua preferita per recuperare una vita breve accesso OAuth 2.0 token:

nodo.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, vedere JSON gettoni web .

Pitone

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

Giava

private 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 automaticamente il metodo di aggiornamento del token per recuperare un token di accesso aggiornato.

Per autorizzare l'accesso alla configurazione remota, richiedere l'ambito https://www.googleapis.com/auth/firebase.remoteconfig .

Modifica il modello di configurazione remota

Quando lavori con i modelli di Remote Config, tieni presente che sono dotati di versione e che ogni versione ha una durata limitata dal momento della creazione al momento in cui la sostituisci con un aggiornamento: 90 giorni, con un limite totale di 300 versioni archiviate. Vedere Modelli e versioni per ulteriori informazioni.

Ottieni il modello di configurazione remota corrente

Puoi utilizzare le API di backend per ottenere la versione attiva corrente del modello Remote Config in formato JSON. Usa i seguenti comandi:

arricciare

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Questo comando restituisce 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, con un colpo di testa separato che include un ETag che si utilizza per la successiva richiesta.

Convalida il modello di configurazione remota

Facoltativamente, puoi convalidare i tuoi aggiornamenti prima di pubblicarli. Aggiornamenti dei modelli Convalida aggiungendo alla vostra richiesta pubblicare il parametro URL ?validate_only=true . In risposta, un codice di stato 200 e un ETAG 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 è necessario correggere prima della pubblicazione.

Aggiorna il modello di configurazione remota

Dopo aver recuperato un modello e rivisto il contenuto JSON con gli aggiornamenti desiderati, puoi pubblicarlo. La pubblicazione di un modello come descritto in questa sezione sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione maggiore di un numero rispetto al modello che ha sostituito.

Se necessario, è possibile utilizzare l'API REST per rollback alla versione precedente . Per mitigare il rischio di errori in un aggiornamento, è possibile convalidare prima della pubblicazione .

arricciare

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 curl dei comandi, è possibile specificare il contenuto utilizzando il carattere "@", seguito dal nome del 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 una versione aggiornata ETag sono fornite nelle intestazioni di risposta del prossimo PUT comando.

Modifica le condizioni di configurazione remota

È possibile modificare a livello di codice le condizioni e i valori condizionali di Remote Config. Con l'API REST, è necessario modificare direttamente il modello per modificare le condizioni prima di pubblicare il modello.

{
  "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 sopra primo definiscono un insieme di condizioni, e quindi definisce i valori predefiniti e parametri basata sulle condizioni (valori condizionali) valori per ciascun parametro. Aggiunge anche una descrizione facoltativa per ogni elemento; come i commenti al codice, questi sono per l'uso da parte degli sviluppatori e non vengono visualizzati nell'app. Un ETag è prevista anche per scopi di controllo di versione.

Le API di backend di Remote Config forniscono diverse condizioni e operatori di confronto che puoi usare per modificare il comportamento e l'aspetto della tua app. Per saperne di più sulle condizioni e gli operatori supportati per queste condizioni, vedere il riferimento espressione condizionale .

Codici di errore HTTP

Codice di stato Significato
200 Aggiornato con successo
400 Si è verificato un errore di convalida. Ad esempio, una richiesta contenente oltre il numero consentito di chiavi-2000-restituirebbe 400 (Richiesta non valida) con il messaggio di errore, Param count too large . Inoltre, questo codice di stato HTTPS può verificarsi in queste due situazioni:
  • Si è verificato un errore di mancata corrispondenza della versione perché l'insieme di valori e condizioni è stato aggiornato dall'ultima volta che hai recuperato un valore ETag. Per risolvere questo problema, è necessario utilizzare un GET comando per ottenere un modello fresco e il valore ETag, aggiornare il modello e quindi inviare utilizzando tale modello e il valore ETag fresca.
  • Un PUT di comando (Remote Update richiesta template di configurazione) è stata fatta senza specificare un If-Match intestazione.
401 Si è verificato un errore di autorizzazione (non è stato fornito alcun token di accesso o l'API REST di Firebase Remote Config non è stata aggiunta al progetto nella 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, presentare una richiesta di assistenza Firebase

Un codice di stato di 200 significa 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 di configurazione remota esistente in precedenza è ancora attivo.

Dopo aver inviato gli aggiornamenti al modello, vai alla console Firebase per verificare che le modifiche vengano visualizzate come previsto. Questo è fondamentale perché l'ordinamento delle condizioni influisce come vengono valutati (la prima condizione che restituisce true ha effetto).

Utilizzo di ETag e aggiornamenti forzati

L'API REST di Remote Config utilizza un tag di entità (ETag) per prevenire race condition e aggiornamenti sovrapposti alle risorse. Per ulteriori informazioni su ETags, vedere ETag - HTTP .

Per l'API REST, Google consiglia di memorizzare nella cache i ETag fornito dalla più recente GET comando e utilizzare tale valore ETag in If-Match intestazione di richiesta al momento del rilascio PUT comandi. Se i PUT risultati del comando in un HTTPS Stato codice 409, si dovrebbe rilasciare una nuova GET comando per acquisire una nuova ETag e modello da utilizzare con il vostro prossimo PUT comando.

È possibile aggirare l'ETag, e la protezione da che esso fornisce, forzando il modello di configurazione remota di essere aggiornato come segue: If-Match: * Tuttavia, non è raccomandato questo approccio perché rischia di provocare la perdita di aggiornamenti al tuo Config a distanza modello se più client stanno aggiornando il modello di configurazione remota. Questo tipo di conflitto potrebbe verificarsi con più client che utilizzano l'API o con aggiornamenti in conflitto da client API e utenti della console Firebase.

Per la guida su come gestire le versioni dei modelli di configurazione remoto, vedere i modelli a distanza di configurazione e il controllo delle versioni .