Ä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.

  

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:

• Firebase Remote Config REST API Java-Schnellstart
• Firebase Remote Config REST API Node.js Schnellstart
• Firebase Remote Config REST API Python-Schnellstart

Ä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:

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

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.

Parameter und Parameterwerte, die speziell als Varianten in einem A/B-Testing-Experiment erstellt wurden, sind nicht in exportierten Vorlagen enthalten.

So erhalten Sie die Vorlage:

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

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:

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

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:

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

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:

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

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 .

Remote Config-Personalisierungen und -Bedingungen sind in heruntergeladenen Vorlagen enthalten, daher ist es wichtig, die folgenden Einschränkungen zu beachten, wenn Sie versuchen, in einem anderen Projekt zu veröffentlichen:

• Personalisierungen können nicht von Projekt zu Projekt importiert werden.

  Wenn Sie beispielsweise Personalisierungen in Ihrem Projekt aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie in demselben Projekt veröffentlichen, aber Sie können sie nicht in einem anderen Projekt veröffentlichen, es sei denn, Sie löschen die Personalisierungen aus der Vorlage.

• Bedingungen können von Projekt zu Projekt importiert werden, aber beachten Sie, dass alle spezifischen Bedingungswerte (wie App-IDs oder Zielgruppen) vor der Veröffentlichung im Zielprojekt vorhanden sein sollten.

  Wenn Sie beispielsweise einen Remote Config-Parameter haben, der eine Bedingung verwendet, die einen Plattformwert von iOS angibt, kann die Vorlage in einem anderen Projekt veröffentlicht werden, da die Plattformwerte für alle Projekte gleich sind. Wenn es jedoch eine Bedingung enthält, die auf einer bestimmten App-ID oder Benutzerzielgruppe basiert, die im Zielprojekt nicht vorhanden ist, schlägt die Validierung fehl.

• Wenn die Vorlage, die Sie veröffentlichen möchten, Bedingungen enthält, die auf Google Analytics basieren, muss Analytics im Zielprojekt aktiviert sein.

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

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 festlegen 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.

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

$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:

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

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
configure.py

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

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.

Parameter und Parameterwerte, die speziell als Varianten in einem A/B-Testing-Experiment erstellt wurden, sind nicht in exportierten Vorlagen enthalten.

Verwenden Sie die folgenden Befehle:

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

Host: firebaseremoteconfig.googleapis.com

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

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 .

Remote Config-Personalisierungen und -Bedingungen sind in heruntergeladenen Vorlagen enthalten, daher ist es wichtig, die folgenden Einschränkungen zu beachten, wenn Sie versuchen, in einem anderen Projekt zu veröffentlichen:

• Personalisierungen können nicht von Projekt zu Projekt importiert werden.

  Wenn Sie beispielsweise Personalisierungen in Ihrem Projekt aktiviert haben und eine Vorlage herunterladen und bearbeiten, können Sie sie in demselben Projekt veröffentlichen, aber Sie können sie nicht in einem anderen Projekt veröffentlichen, es sei denn, Sie löschen die Personalisierungen aus der Vorlage.

• Bedingungen können von Projekt zu Projekt importiert werden, aber beachten Sie, dass alle spezifischen Bedingungswerte (wie App-IDs oder Zielgruppen) vor der Veröffentlichung im Zielprojekt vorhanden sein sollten.

  Wenn Sie beispielsweise einen Remote Config-Parameter haben, der eine Bedingung verwendet, die einen Plattformwert von iOS angibt, kann die Vorlage in einem anderen Projekt veröffentlicht werden, da die Plattformwerte für alle Projekte gleich sind. Wenn es jedoch eine Bedingung enthält, die auf einer bestimmten App-ID oder Benutzerzielgruppe basiert, die im Zielprojekt nicht vorhanden ist, schlägt die Validierung fehl.

• Wenn die Vorlage, die Sie veröffentlichen möchten, Bedingungen enthält, die auf Google Analytics basieren, muss Analytics im Zielprojekt aktiviert sein.

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

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

Ä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

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 .