Ändern Sie Remote Config programmgesteuert

In diesem Dokument wird beschrieben, wie Sie den Satz von JSON-formatierten Parametern und Bedingungen, die als Remote Config-Vorlage bezeichnet werden, programmgesteuert lesen und ändern können. Auf diese Weise können Sie Vorlagenänderungen im Back-End vornehmen, die die Client-App mithilfe der Client-Bibliothek abrufen kann.

Mithilfe der Remote Config-REST-API oder der in diesem Handbuch beschriebenen Admin-SDKs können Sie die Verwaltung der Vorlage in der Firebase-Konsole umgehen, um Remote Config-Änderungen direkt in Ihre eigenen Prozesse zu integrieren. Mit Remote Config-Backend-APIs könnten Sie beispielsweise:

  • Planen von Remote Config-Updates . Durch die Verwendung von API-Aufrufen in Verbindung mit einem Cron-Job können Sie Remote Config-Werte regelmäßig ändern.
  • Batch-Import von Konfigurationswerten für einen effizienten Übergang von Ihrem eigenen proprietären System zu Firebase Remote Config.
  • Verwenden Sie Remote Config mit Cloud Functions for Firebase und ändern Sie Werte in Ihrer App basierend auf serverseitigen Ereignissen. Beispielsweise können Sie Remote Config verwenden, um eine neue Funktion in Ihrer App zu bewerben, und diese Werbung dann automatisch deaktivieren, sobald Sie feststellen, dass genügend Personen mit der neuen Funktion interagiert haben.

    Diagramm, das das Remote Config-Back-End zeigt, das mit benutzerdefinierten Tools und Servern interagiert

In den folgenden Abschnitten dieses Handbuchs werden Vorgänge beschrieben, die Sie mit den Remote Config-Back-End-APIs ausführen können. Um Code zu überprüfen, der diese Aufgaben über die REST-API ausführt, sehen Sie sich eine dieser Beispiel-Apps an:

Ändern Sie Remote Config mit dem Firebase Admin SDK

Das Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie aus privilegierten Umgebungen mit Firebase interagieren können. Neben der Durchführung von Updates für Remote Config ermöglicht das Admin SDK die Generierung und Überprüfung von Firebase-Authentifizierungstoken, das Lesen und Schreiben aus der Echtzeitdatenbank und so weiter. Weitere Informationen zu den Voraussetzungen und der Einrichtung des Admin SDK finden Sie unter Firebase Admin SDK zu Ihrem Server hinzufügen .

In einem typischen Remote Config-Flow erhalten Sie möglicherweise die aktuelle Vorlage, ändern einige der Parameter oder Parametergruppen und -bedingungen, validieren die Vorlage und veröffentlichen sie dann. Bevor Sie diese API-Aufrufe durchführen, müssen Sie Anfragen vom SDK autorisieren.

Initialisieren Sie das SDK und autorisieren Sie API-Anforderungen

Wenn Sie das Admin SDK ohne Parameter initialisieren, verwendet das SDK die Standardanmeldeinformationen der Google-Anwendung und liest Optionen aus der Umgebungsvariable FIREBASE_CONFIG . Wenn der Inhalt der Variable FIREBASE_CONFIG mit einem { beginnt, wird er als JSON-Objekt geparst. Andernfalls geht das SDK davon aus, dass die Zeichenfolge der Name einer JSON-Datei ist, die die Optionen enthält.

Zum Beispiel:

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

Holen Sie sich die aktuelle Remote-Konfigurationsvorlage

Beachten Sie bei der Arbeit mit Remote Config-Vorlagen, dass sie versioniert sind und dass jede Version eine begrenzte Lebensdauer von ihrer Erstellung bis zu dem Zeitpunkt hat, an dem Sie sie durch ein Update ersetzen: 90 Tage mit einem Gesamtlimit von 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung .

Sie können die Back-End-APIs verwenden, um die aktuelle aktive Version der Remote Config-Vorlage im JSON-Format abzurufen. So erhalten Sie die Vorlage:

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

Ändern Sie Remote Config-Parameter

Sie können Remote Config-Parameter und -Parametergruppen programmgesteuert ändern und hinzufügen. Beispielsweise könnten Sie einer vorhandenen Parametergruppe mit dem Namen "new_menu" einen Parameter hinzufügen, um die Anzeige saisonaler Informationen zu steuern:

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.")
        );

Mit der API können Sie neue Parameter und Parametergruppen erstellen oder Standardwerte, bedingte Werte und Beschreibungen ändern. In jedem Fall müssen Sie die Vorlage explizit veröffentlichen, nachdem Sie Änderungen vorgenommen haben.

Ändern Sie die Remote-Konfigurationsbedingungen

Sie können Remote Config-Bedingungen und bedingte Werte programmgesteuert ändern und hinzufügen. So fügen Sie beispielsweise eine neue Bedingung hinzu:

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 jedem Fall müssen Sie die Vorlage explizit veröffentlichen, nachdem Sie Änderungen vorgenommen haben.

Die Remote Config-Back-End-APIs stellen mehrere Bedingungen und Vergleichsoperatoren bereit, mit denen Sie das Verhalten und Erscheinungsbild Ihrer App ändern können. Weitere Informationen zu Bedingungen und den für diese Bedingungen unterstützten Operatoren finden Sie in der Referenz zu bedingten Ausdrücken .

Validieren Sie die Remote Config-Vorlage

Optional können Sie Ihre Updates validieren, bevor Sie sie veröffentlichen, wie hier gezeigt:

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

Dieser Validierungsprozess prüft auf Fehler wie doppelte Schlüssel für Parameter und Bedingungen, ungültige Bedingungsnamen oder nicht vorhandene Bedingungen oder falsch formatierte ETags. Beispielsweise würde eine Anfrage mit mehr als der zulässigen Anzahl von Schlüsseln – 2000 – die Fehlermeldung „ Param count too large “ zurückgeben.

Veröffentlichen Sie die Remote Config-Vorlage

Nachdem Sie eine Vorlage abgerufen und mit den gewünschten Aktualisierungen überarbeitet haben, können Sie sie veröffentlichen. Durch das Veröffentlichen einer Vorlage wie in diesem Abschnitt beschrieben wird die gesamte vorhandene Konfigurationsvorlage durch die aktualisierte Datei ersetzt, und der neuen aktiven Vorlage wird eine Versionsnummer zugewiesen, die um eine Nummer höher ist als die der ersetzten Vorlage.

Bei Bedarf können Sie die REST-API verwenden, um auf die vorherige Version zurückzusetzen . Um das Risiko von Fehlern in einem Update zu mindern, können Sie vor der Veröffentlichung validieren .

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

Ändern Sie Remote Config mithilfe der REST-API

In diesem Abschnitt werden die Hauptfunktionen der Remote Config-REST-API unter https://firebaseremoteconfig.googleapis.com beschrieben. Ausführliche Informationen finden Sie in der API-Referenz .

Rufen Sie ein Zugriffstoken ab, um API-Anforderungen zu authentifizieren und zu autorisieren

Firebase-Projekte unterstützen Google -Dienstkonten , mit denen Sie Firebase-Server-APIs von Ihrem App-Server oder Ihrer vertrauenswürdigen Umgebung aufrufen können. Wenn Sie Code lokal entwickeln oder Ihre Anwendung lokal bereitstellen, können Sie Anmeldeinformationen verwenden, die Sie über dieses Dienstkonto erhalten haben, um Serveranforderungen zu autorisieren.

Um ein Dienstkonto zu authentifizieren und für den Zugriff auf Firebase-Dienste zu autorisieren, müssen Sie eine private Schlüsseldatei im JSON-Format generieren.

So generieren Sie eine private Schlüsseldatei für Ihr Dienstkonto:

  1. Öffnen Sie in der Firebase-Konsole Einstellungen > Dienstkonten .

  2. Klicken Sie auf Neuen privaten Schlüssel generieren , und bestätigen Sie dann, indem Sie auf Schlüssel generieren klicken.

  3. Speichern Sie die JSON-Datei mit dem Schlüssel sicher.

Bei der Autorisierung über ein Dienstkonto haben Sie zwei Möglichkeiten, die Anmeldeinformationen für Ihre Anwendung bereitzustellen. Sie können entweder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS oder den Pfad zum Schlüssel des Dienstkontos explizit im Code übergeben. Die erste Option ist sicherer und wird dringend empfohlen.

So legen Sie die Umgebungsvariable fest:

Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Dateipfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält. Diese Variable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie also eine neue Sitzung öffnen, legen Sie die Variable erneut fest.

Linux oder macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Mit PowerShell:

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

Nachdem Sie die obigen Schritte ausgeführt haben, kann Application Default Credentials (ADC) Ihre Anmeldedaten implizit bestimmen, sodass Sie beim Testen oder Ausführen in Nicht-Google-Umgebungen Dienstkonto-Anmeldedaten verwenden können.

Verwenden Sie Ihre Firebase-Anmeldedaten zusammen mit der Google Auth-Bibliothek für Ihre bevorzugte Sprache, um ein kurzlebiges OAuth 2.0-Zugriffstoken abzurufen:

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 diesem Beispiel authentifiziert die Google API-Clientbibliothek die Anfrage mit einem JSON-Web-Token oder JWT. Weitere Informationen finden Sie unter JSON-Webtoken .

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

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

Nachdem Ihr Zugriffstoken abgelaufen ist, wird die Tokenaktualisierungsmethode automatisch aufgerufen, um ein aktualisiertes Zugriffstoken abzurufen.

Um den Zugriff auf Remote Config zu autorisieren, fordern Sie den Bereich https://www.googleapis.com/auth/firebase.remoteconfig an.

Ändern Sie die Remote Config-Vorlage

Beachten Sie bei der Arbeit mit Remote Config-Vorlagen, dass sie versioniert sind und dass jede Version eine begrenzte Lebensdauer von ihrer Erstellung bis zu dem Zeitpunkt hat, an dem Sie sie durch ein Update ersetzen: 90 Tage mit einem Gesamtlimit von 300 gespeicherten Versionen. Weitere Informationen finden Sie unter Vorlagen und Versionierung .

Holen Sie sich die aktuelle Remote-Konfigurationsvorlage

Sie können die Back-End-APIs verwenden, um die aktuelle aktive Version der Remote Config-Vorlage im JSON-Format abzurufen. Verwenden Sie die folgenden Befehle:

cURL

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

Dieser Befehl gibt die JSON-Nutzlast in eine Datei und die Header (einschließlich Etag) in eine separate Datei aus.

Rohe HTTP-Anforderung

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Dieser API-Aufruf gibt den folgenden JSON zurück, zusammen mit einem separaten Header, der ein ETag enthält, das Sie für die nachfolgende Anfrage verwenden.

Validieren Sie die Remote Config-Vorlage

Optional können Sie Ihre Updates validieren, bevor Sie sie veröffentlichen. Validieren Sie Vorlagenaktualisierungen, indem Sie an Ihre Veröffentlichungsanforderung den URL-Parameter ?validate_only=true anhängen. In der Antwort bedeutet ein Statuscode 200 und ein aktualisiertes Etag mit dem Suffix -0 , dass Ihr Update erfolgreich validiert wurde. Jede Nicht-200-Antwort weist darauf hin, dass die JSON-Daten Fehler enthalten, die Sie vor der Veröffentlichung korrigieren müssen.

Aktualisieren Sie die Remote Config-Vorlage

Nachdem Sie eine Vorlage abgerufen und den JSON-Inhalt mit den gewünschten Aktualisierungen überarbeitet haben, können Sie ihn veröffentlichen. Durch das Veröffentlichen einer Vorlage wie in diesem Abschnitt beschrieben wird die gesamte vorhandene Konfigurationsvorlage durch die aktualisierte Datei ersetzt, und der neuen aktiven Vorlage wird eine Versionsnummer zugewiesen, die um eine Nummer höher ist als die der ersetzten Vorlage.

Bei Bedarf können Sie die REST-API verwenden, um auf die vorherige Version zurückzusetzen . Um das Risiko von Fehlern in einem Update zu mindern, können Sie vor der Veröffentlichung validieren .

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

Für diesen curl Befehl können Sie den Inhalt angeben, indem Sie das Zeichen „@“ gefolgt vom Dateinamen verwenden.

Rohe HTTP-Anforderung

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

Da dies eine Schreibanforderung ist, wird das ETag durch diesen Befehl modifiziert und ein aktualisiertes ETag wird in den Antwortheadern des nächsten PUT -Befehls bereitgestellt.

Ändern Sie die Remote-Konfigurationsbedingungen

Sie können Remote Config-Bedingungen und bedingte Werte programmgesteuert ändern. Bei der REST-API müssen Sie die Vorlage direkt bearbeiten, um Bedingungen zu ändern, bevor Sie die Vorlage veröffentlichen.

{
  "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."
    }
  }
}

Die obigen Modifikationen definieren zuerst einen Satz von Bedingungen und definieren dann Standardwerte und bedingungsbasierte Parameterwerte ( bedingte Werte ) für jeden Parameter. Es fügt auch eine optionale Beschreibung für jedes Element hinzu; wie Codekommentare sind diese für Entwickler bestimmt und werden nicht in der App angezeigt. Zur Versionskontrolle wird auch ein ETag bereitgestellt.

Die Remote Config-Back-End-APIs stellen mehrere Bedingungen und Vergleichsoperatoren bereit, mit denen Sie das Verhalten und Erscheinungsbild Ihrer App ändern können. Weitere Informationen zu Bedingungen und den für diese Bedingungen unterstützten Operatoren finden Sie in der Referenz zu bedingten Ausdrücken .

HTTP-Fehlercodes

Statuscode Bedeutung
200 Erfolgreich aktualisiert
400 Es ist ein Validierungsfehler aufgetreten. Beispielsweise würde eine Anfrage mit mehr als der zulässigen Anzahl von Schlüsseln – 2000 – 400 (Bad Request) mit der Fehlermeldung „ Param count too large “ zurückgeben. Außerdem kann dieser HTTPS-Statuscode in diesen beiden Situationen auftreten:
  • Ein Versionsfehler ist aufgetreten, weil der Satz von Werten und Bedingungen aktualisiert wurde, seit Sie zuletzt einen ETag-Wert abgerufen haben. Um dies zu beheben, sollten Sie einen GET Befehl verwenden, um eine neue Vorlage und einen neuen ETag-Wert zu erhalten, die Vorlage aktualisieren und dann mit dieser Vorlage und dem neuen ETag-Wert senden.
  • Ein PUT -Befehl (Remote Config Template Request aktualisieren) wurde ohne Angabe eines If-Match Headers ausgeführt.
401 Ein Autorisierungsfehler ist aufgetreten (es wurde kein Zugriffstoken bereitgestellt oder die Firebase Remote Config REST API wurde Ihrem Projekt in der Cloud Developer Console nicht hinzugefügt)
403 Ein Authentifizierungsfehler ist aufgetreten (das falsche Zugriffstoken wurde bereitgestellt)
500 Ein interner Fehler ist aufgetreten. Wenn dieser Fehler auftritt, reichen Sie ein Firebase-Supportticket ein

Ein Statuscode von 200 bedeutet, dass die Remote Config-Vorlage (Parameter, Werte und Bedingungen für das Projekt) aktualisiert wurde und jetzt für Apps verfügbar ist, die dieses Projekt verwenden. Andere Statuscodes weisen darauf hin, dass die zuvor vorhandene Remote Config-Vorlage noch in Kraft ist.

Nachdem Sie Aktualisierungen an Ihrer Vorlage übermittelt haben, gehen Sie zur Firebase-Konsole, um zu überprüfen, ob Ihre Änderungen wie erwartet angezeigt werden. Dies ist wichtig, da die Reihenfolge der Bedingungen beeinflusst, wie sie ausgewertet werden (die erste Bedingung, die true auswertet, tritt in Kraft).

ETag-Nutzung und erzwungene Updates

Die Remote Config-REST-API verwendet ein Entity-Tag (ETag), um Race-Conditions und überlappende Aktualisierungen von Ressourcen zu verhindern. Weitere Informationen zu ETags finden Sie unter ETag - HTTP .

Für die REST-API empfiehlt Google, dass Sie das vom letzten GET -Befehl bereitgestellte ETag zwischenspeichern und diesen ETag-Wert im If-Match Anforderungsheader verwenden, wenn Sie PUT -Befehle ausgeben. Wenn Ihr PUT -Befehl zu einem HTTPS-Statuscode 409 führt, sollten Sie einen neuen GET -Befehl ausgeben, um ein neues ETag und eine Vorlage zur Verwendung mit Ihrem nächsten PUT Befehl abzurufen.

Sie können das ETag und den Schutz davor umgehen, indem Sie erzwingen, dass die Remote Config-Vorlage wie folgt aktualisiert wird: If-Match: * Dieser Ansatz wird jedoch nicht empfohlen, da dadurch das Risiko besteht, dass Aktualisierungen Ihrer Remote Config verloren gehen Vorlage, wenn mehrere Clients die Remote Config-Vorlage aktualisieren. Diese Art von Konflikt kann bei mehreren Clients auftreten, die die API verwenden, oder bei widersprüchlichen Updates von API-Clients und Benutzern der Firebase-Konsole.

Anleitungen zum Verwalten von Versionen von Remote Config-Vorlagen finden Sie unter Remote Config-Vorlagen und -Versionierung .