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

Modifier la configuration à distance par programmation

Ce document décrit la façon dont vous pouvez lire et modifier programatically l'ensemble des paramètres et des conditions au format JSON connu sous le nom modèle Config à distance . Cela vous permet d'apporter des modifications de modèle sur le backend que l'application cliente peut récupérer à l'aide de la bibliothèque cliente.

Utilisation de l' API à distance Config REST ou l' administrateur SDKs décrit dans ce guide, vous pouvez contourner la gestion du modèle dans la console Firebase pour intégrer directement à distance Config change dans vos propres processus. Par exemple, avec les API backend Remote Config, vous pouvez :

  • Planification des mises à jour à distance Config. En utilisant des appels d'API en conjonction avec une tâche cron, vous pouvez modifier les valeurs de Remote Config régulièrement.
  • Batch valeurs de configuration d'importation afin de la transition efficace de votre propre système propriétaire à distance Firebase Config.
  • Utilisez Config à distance avec des fonctions Cloud pour Firebase, l' évolution des valeurs dans votre application en fonction des événements qui se produisent côté serveur. Par exemple, vous pouvez utiliser Remote Config pour promouvoir une nouvelle fonctionnalité dans votre application, puis désactiver cette promotion automatiquement une fois que vous avez détecté que suffisamment de personnes ont interagi avec la nouvelle fonctionnalité.

    Diagramme montrant le backend Remote Config interagissant avec des outils et des serveurs personnalisés

Les sections suivantes de ce guide décrivent les opérations que vous pouvez effectuer avec les API backend Remote Config. Pour passer en revue certains codes qui effectuent ces tâches via l'API REST, consultez l'un de ces exemples d'applications :

Modifier la configuration à distance à l'aide du SDK Firebase Admin

Le SDK Admin est un ensemble de bibliothèques de serveurs qui vous permettent d'interagir avec Firebase à partir d'environnements privilégiés. En plus d'effectuer des mises à jour de Remote Config, le SDK Admin permet la génération et la vérification de jetons d'authentification Firebase, la lecture et l'écriture à partir de la base de données en temps réel, etc. Pour en savoir plus sur les conditions préalables et la configuration d' administration SDK, consultez Ajouter le Firebase Administrateur SDK à votre serveur .

Dans un flux de configuration à distance typique, vous pouvez obtenir le modèle actuel, modifier certains paramètres ou groupes de paramètres et conditions, valider le modèle, puis le publier. Avant d'effectuer ces appels d'API, vous devez autoriser les requêtes du SDK.

Initialiser le SDK et autoriser les requêtes API

Lorsque vous initialisez le Admin SDK sans paramètre, le SDK utilise informations d' FIREBASE_CONFIG identification par défaut Google application et lit les options de la FIREBASE_CONFIG variable d'environnement. Si le contenu de la FIREBASE_CONFIG variable commence par un { il sera analysé comme un objet JSON. Sinon, le SDK suppose que la chaîne est le nom d'un fichier JSON contenant les options.

Par exemple:

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

Obtenir le modèle de configuration à distance actuel

Lorsque vous travaillez avec des modèles Remote Config, gardez à l'esprit qu'ils sont versionnés et que chaque version a une durée de vie limitée depuis sa création jusqu'au moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et Versioning pour plus d' informations.

Vous pouvez utiliser les API backend pour obtenir la version active actuelle du modèle Remote Config au format JSON. Pour obtenir le modèle :

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

Modifier les paramètres de configuration à distance

Vous pouvez modifier et ajouter par programmation des paramètres et des groupes de paramètres de configuration à distance. Par exemple, à un groupe de paramètres existant nommé "nouveau_menu", vous pouvez ajouter un paramètre pour contrôler l'affichage des informations saisonnières :

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 vous permet de créer de nouveaux paramètres et groupes de paramètres, ou de modifier les valeurs par défaut, les valeurs conditionnelles et les descriptions. Dans tous les cas, vous devez explicitement publier le modèle après avoir effectué des modifications.

Modifier les conditions de configuration à distance

Vous pouvez modifier et ajouter par programmation des conditions de configuration à distance et des valeurs conditionnelles. Par exemple, pour ajouter une nouvelle condition :

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

Dans tous les cas, vous devez explicitement publier le modèle après avoir effectué des modifications.

Les API backend Remote Config fournissent plusieurs conditions et opérateurs de comparaison que vous pouvez utiliser pour modifier le comportement et l'apparence de votre application. Pour en savoir plus sur les conditions et les opérateurs pris en charge pour ces conditions, voir la référence de l' expression conditionnelle .

Valider le modèle de configuration à distance

En option, vous pouvez valider vos mises à jour avant de les publier, comme indiqué :

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

Ce processus de validation recherche les erreurs telles que les clés en double pour les paramètres et les conditions, les noms de condition non valides ou les conditions inexistantes, ou les etags mal formatés. Par exemple, une demande contenant plus que le nombre autorisé de clés-2000 renverrait le message d'erreur, Param count too large .

Publier le modèle de configuration à distance

Après avoir récupéré un modèle et l'avoir révisé avec les mises à jour souhaitées, vous pouvez ensuite le publier. La publication d'un modèle comme décrit dans cette section remplace l'intégralité du modèle de configuration existant par le fichier mis à jour, et le nouveau modèle actif se voit attribuer un numéro de version supérieur à celui du modèle qu'il a remplacé.

Si nécessaire, vous pouvez utiliser l'API REST pour faire reculer à la version précédente . Afin d' atténuer le risque d'erreurs dans une mise à jour, vous pouvez valider avant de publier .

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

Modifier la configuration à distance à l'aide de l'API REST

Cette section décrit les principales fonctionnalités de l'API à distance Config REST https://firebaseremoteconfig.googleapis.com . Pour plus de détails complète, consultez la référence API .

Obtenez un jeton d'accès pour authentifier et autoriser les requêtes API

Projets Firebase soutiennent Google comptes de service , que vous pouvez utiliser pour appeler les API de serveur Firebase à partir de votre serveur d'applications ou de l' environnement de confiance. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser les informations d'identification obtenues via ce compte de service pour autoriser les demandes du serveur.

Pour authentifier un compte de service et l'autoriser à accéder aux services Firebase, vous devez générer un fichier de clé privée au format JSON.

Pour générer un fichier de clé privée pour votre compte de service :

  1. Dans la console Firebase, ouvrez Paramètres> Comptes de service .

  2. Cliquez sur Générer une nouvelle clé privée, puis confirmez en cliquant sur Générer la clé.

  3. Stockez en toute sécurité le fichier JSON contenant la clé.

Lors de l'autorisation via un compte de service, vous avez deux choix pour fournir les informations d'identification à votre application. Vous pouvez définir la GOOGLE_APPLICATION_CREDENTIALS variable d'environnement, ou vous pouvez passer explicitement le chemin à la clé de compte de service dans le code. La première option est plus sécurisée et est fortement recommandée.

Pour définir la variable d'environnement :

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS au chemin du fichier du fichier JSON qui contient la clé de votre compte de service. Cette variable ne s'applique qu'à votre session shell actuelle, donc si vous ouvrez une nouvelle session, définissez à nouveau la variable.

Linux ou macOS

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

les fenêtres

Avec PowerShell :

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

Une fois que vous avez terminé les étapes ci-dessus, les informations d'identification par défaut de l'application (ADC) sont capables de déterminer implicitement vos informations d'identification, vous permettant d'utiliser les informations d'identification du compte de service lors des tests ou de l'exécution dans des environnements autres que Google.

Utilisez vos informations d' identification Firebase avec la bibliothèque Google Auth pour votre langue préférée pour récupérer un accès OAuth 2.0 courte durée jeton:

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

Dans cet exemple, la bibliothèque cliente de l'API Google authentifie la demande avec un jeton Web JSON ou JWT. Pour plus d' informations, consultez JSON jetons web .

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

Une fois votre jeton d'accès expiré, la méthode d'actualisation du jeton est appelée automatiquement pour récupérer un jeton d'accès mis à jour.

Pour autoriser l' accès à distance Config, demander la portée https://www.googleapis.com/auth/firebase.remoteconfig .

Modifier le modèle de configuration à distance

Lorsque vous travaillez avec des modèles Remote Config, gardez à l'esprit qu'ils sont versionnés et que chaque version a une durée de vie limitée depuis sa création jusqu'au moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et Versioning pour plus d' informations.

Obtenir le modèle de configuration à distance actuel

Vous pouvez utiliser les API backend pour obtenir la version active actuelle du modèle Remote Config au format JSON. Utilisez les commandes suivantes :

boucle

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

Cette commande génère la charge utile JSON dans un fichier et les en-têtes (y compris l'Etag) dans un fichier séparé.

Requête HTTP brute

Host: firebaseremoteconfig.googleapis.com

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

Cet appel API renvoie le JSON suivant, avec un en- tête séparée qui comprend un ETag que vous utilisez pour la demande ultérieure.

Valider le modèle de configuration à distance

En option, vous pouvez valider vos mises à jour avant de les publier. Valider les mises à jour du modèle en adjoignant à votre demande de publier le paramètre d'URL ?validate_only=true . Dans la réponse, un code d'état 200 et un ETAG mis à jour avec le suffixe -0 signifie que votre mise à jour a été validé avec succès. Toute réponse autre que 200 indique que les données JSON contiennent des erreurs que vous devez corriger avant la publication.

Mettre à jour le modèle de configuration à distance

Après avoir récupéré un modèle et révisé le contenu JSON avec les mises à jour souhaitées, vous pouvez ensuite le publier. La publication d'un modèle comme décrit dans cette section remplace l'intégralité du modèle de configuration existant par le fichier mis à jour, et le nouveau modèle actif se voit attribuer un numéro de version supérieur à celui du modèle qu'il a remplacé.

Si nécessaire, vous pouvez utiliser l'API REST pour faire reculer à la version précédente . Afin d' atténuer le risque d'erreurs dans une mise à jour, vous pouvez valider avant de publier .

boucle

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

Pour cette curl commande, vous pouvez spécifier le contenu en utilisant le caractère « @ », suivi du nom de fichier.

Requête HTTP brute

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

Parce que ceci est une demande d'écriture, le ETag est modifié par cette commande et une ETag mise à jour est fournie dans les en- têtes de réponse de la prochaine PUT commande.

Modifier les conditions de configuration à distance

Vous pouvez modifier par programmation les conditions et les valeurs conditionnelles de la configuration à distance. Avec l'API REST, vous devez éditer le modèle directement pour modifier les conditions avant de publier le modèle.

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

Les modifications ci - dessus d'abord définir un ensemble de conditions, et définit alors les valeurs des valeurs par défaut et des paramètres sur la base de conditions (valeurs conditionnelles) pour chaque paramètre. Il ajoute également une description facultative pour chaque élément ; comme les commentaires de code, ceux-ci sont destinés aux développeurs et ne sont pas affichés dans l'application. Un ETag est également fourni à des fins de contrôle de version.

Les API backend Remote Config fournissent plusieurs conditions et opérateurs de comparaison que vous pouvez utiliser pour modifier le comportement et l'apparence de votre application. Pour en savoir plus sur les conditions et les opérateurs pris en charge pour ces conditions, voir la référence de l' expression conditionnelle .

Codes d'erreur HTTP

Code d'état Sens
200 Mise à jour réussie
400 Une erreur de validation s'est produite. Par exemple, une demande contenant plus que le nombre autorisé de clés-2000-retournerait 400 (Bad Request) avec le message d'erreur, Param count too large . De plus, ce code d'état HTTPS peut se produire dans ces deux situations :
  • Une erreur de non-concordance de version s'est produite car l'ensemble de valeurs et de conditions a été mis à jour depuis la dernière récupération d'une valeur ETag. Pour résoudre ce problème, vous devez utiliser un GET commande pour obtenir un modèle frais et à valeur ETag, mettre à jour le modèle, puis soumettre en utilisant ce modèle et la valeur ETag frais.
  • A PUT commande (Mise à jour demande de modèle Config à distance) a été faite sans spécifier If-Match en- tête.
401 Une erreur d'autorisation s'est produite (aucun jeton d'accès n'a été fourni ou l'API REST Firebase Remote Config n'a pas été ajoutée à votre projet dans la Cloud Developer Console)
403 Une erreur d'authentification s'est produite (le mauvais jeton d'accès a été fourni)
500 Une erreur interne a eu lieu. Si cette erreur se produit, déposer un ticket de support Firebase

Un code d'état de 200 signifie que le modèle Remote Config (paramètres, valeurs et conditions du projet) a été mis à jour et est désormais disponible pour les applications qui utilisent ce projet. D'autres codes d'état indiquent que le modèle de configuration à distance qui existait précédemment est toujours en vigueur.

Après avoir soumis les mises à jour de votre modèle, accédez à la console Firebase pour vérifier que vos modifications apparaissent comme prévu. Ceci est important car l'ordre des conditions affecte la façon dont elles sont évaluées (la première condition qui évalue true prend effet).

Utilisation d'ETag et mises à jour forcées

L'API REST Remote Config utilise une balise d'entité (ETag) pour empêcher les conditions de concurrence et le chevauchement des mises à jour des ressources. Pour en savoir plus sur ETags, voir ETag - HTTP .

Pour l'API REST, Google vous recommande de mettre en cache le ETag fourni par la plus récente GET commande, et utiliser cette valeur ETag dans le If-Match - tête de requête lors de l' émission PUT commandes. Si votre PUT commande se traduit par un HTTPS Code d' état 409, vous devez émettre une nouvelle GET commande pour acquérir un nouveau ETag et modèle à utiliser avec votre prochaine PUT commande.

Vous pouvez contourner le ETag et la protection de celui qu'il fournit, en forçant le modèle de configuration à distance pour être mis à jour comme suit: If-Match: * Cependant, cette approche est déconseillée car elle risque de provoquer la perte de mises à jour de votre télécommande Config modèle si plusieurs clients mettent à jour le modèle de configuration à distance. Ce type de conflit peut se produire avec plusieurs clients utilisant l'API ou avec des mises à jour conflictuelles des clients API et des utilisateurs de la console Firebase.

Pour obtenir des conseils sur la gestion des versions de modèle Config à distance, voir modèles Config à distance et versioning .