获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Modifier la configuration à distance par programme

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

À l'aide de l' API REST Remote Config ou des SDK d'administration décrits dans ce guide, vous pouvez contourner la gestion du modèle dans la console Firebase pour intégrer directement les modifications de Remote Config dans vos propres processus. Par exemple, avec les API backend Remote Config, vous pouvez :

  • Planification des mises à jour de Remote Config . En utilisant des appels d'API conjointement avec une tâche cron, vous pouvez modifier les valeurs de Remote Config de manière régulière.
  • Importez par lots les valeurs de configuration afin de passer efficacement de votre propre système propriétaire à Firebase Remote Config.
  • Utilisez Remote Config avec Cloud Functions pour Firebase , en modifiant les valeurs de 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 automatiquement cette promotion une fois que vous avez détecté qu'un nombre suffisant de personnes ont interagi avec la nouvelle fonctionnalité.

    Diagramme illustrant l'interaction du backend Remote Config 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 de Remote Config. Pour passer en revue certains codes qui effectuent ces tâches via l'API REST, consultez l'un de ces exemples d'application :

Modifier la configuration à distance à l'aide du SDK d'administration Firebase

Le SDK Admin est un ensemble de bibliothèques de serveur 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 de générer et de vérifier des jetons d'authentification Firebase, de lire et d'écrire à partir de la base de données en temps réel, etc. Pour en savoir plus sur les prérequis et la configuration du SDK Admin, consultez Ajouter le SDK Admin Firebase à 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 SDK Admin sans paramètres, le SDK utilise les informations d'identification par défaut de l'application Google et lit les options de la variable d'environnement FIREBASE_CONFIG . Si le contenu de la variable FIREBASE_CONFIG 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 entre sa création et le moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et gestion des versions pour plus d'informations.

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

Les paramètres et les valeurs de paramètres créés spécifiquement en tant que variantes dans une expérience de test A/B ne sont pas inclus dans les modèles exportés.

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 Remote Config. 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 apporté des modifications.

Modifier les conditions de configuration à distance

Vous pouvez modifier et ajouter par programmation des conditions et des valeurs conditionnelles de Remote Config. 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 apporté des modifications.

Les API backend de 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, consultez la référence d'expression conditionnelle .

Valider le modèle de configuration à distance

Facultativement, 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 vérifie les erreurs telles que les clés en double pour les paramètres et les conditions, les noms de condition invalides ou les conditions inexistantes, ou les etags mal formatés. Par exemple, une requête contenant plus que le nombre de clés autorisé (2 000) 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 d'un numéro au modèle qu'il a remplacé.

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

Les personnalisations et les conditions de Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limitations suivantes lorsque vous tentez de publier dans un autre projet :

  • Les personnalisations ne peuvent pas être importées d'un projet à l'autre.

    Par exemple, si des personnalisations sont activées dans votre projet et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet, mais vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

  • Les conditions peuvent être importées d'un projet à l'autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

    Par exemple, si vous avez un paramètre Remote Config qui utilise une condition qui spécifie une valeur de plateforme iOS , le modèle peut être publié dans un autre projet, car les valeurs de plateforme sont les mêmes pour tous les projets. Toutefois, s'il contient une condition qui repose sur un ID d'application ou une audience d'utilisateurs spécifique qui n'existe pas dans le projet cible, la validation échouera.

  • Si le modèle que vous envisagez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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 REST Remote Config sur https://firebaseremoteconfig.googleapis.com . Pour plus de détails, consultez la référence de l'API .

Obtenez un jeton d'accès pour authentifier et autoriser les demandes d'API

Les projets Firebase prennent en charge les comptes de service Google , que vous pouvez utiliser pour appeler les API du serveur Firebase à partir de votre serveur d'applications ou de votre 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 requêtes 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 soit définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS , soit transmettre explicitement le chemin d'accès à la clé du 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 sur le chemin d'accès au fichier JSON contenant 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) peuvent déterminer implicitement vos informations d'identification, ce qui vous permet 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 identifiants Firebase avec la bibliothèque Google Auth pour votre langue préférée afin de récupérer un jeton d'accès OAuth 2.0 de courte durée :

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 Jetons 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

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

Après l'expiration de votre jeton d'accès, 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 à Remote Config, demandez 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 entre sa création et le moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et gestion des versions 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.

Les paramètres et les valeurs de paramètres créés spécifiquement en tant que variantes dans une expérience de test A/B ne sont pas inclus dans les modèles exportés.

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 d'API renvoie le JSON suivant, ainsi qu'un en-tête séparé qui inclut un ETag que vous utilisez pour la requête suivante.

Valider le modèle de configuration à distance

En option, vous pouvez valider vos mises à jour avant de les publier. Validez les mises à jour du modèle en ajoutant à votre demande de publication 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 signifient que votre mise à jour a été validée 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 d'un numéro au modèle qu'il a remplacé.

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

Les personnalisations et les conditions de Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limitations suivantes lorsque vous tentez de publier dans un autre projet :

  • Les personnalisations ne peuvent pas être importées d'un projet à l'autre.

    Par exemple, si des personnalisations sont activées dans votre projet et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet, mais vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

  • Les conditions peuvent être importées d'un projet à l'autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

    Par exemple, si vous avez un paramètre Remote Config qui utilise une condition qui spécifie une valeur de plateforme iOS , le modèle peut être publié dans un autre projet, car les valeurs de plateforme sont les mêmes pour tous les projets. Toutefois, s'il contient une condition qui repose sur un ID d'application ou une audience d'utilisateurs spécifique qui n'existe pas dans le projet cible, la validation échouera.

  • Si le modèle que vous envisagez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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 commande curl , 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

Comme il s'agit d'une demande d'écriture, l' ETag est modifié par cette commande et un ETag mis à jour est fourni dans les en-têtes de réponse de la prochaine commande PUT .

Modifier les conditions de configuration à distance

Vous pouvez modifier par programmation les conditions et les valeurs conditionnelles de Remote Config. 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éfinissent d'abord un ensemble de conditions, puis définissent des valeurs par défaut et des valeurs de paramètre basées sur la condition (valeurs conditionnelles ) pour chaque paramètre. Il ajoute également une description facultative pour chaque élément ; comme les commentaires de code, ils 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 de 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, consultez la référence d'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 requête contenant plus que le nombre de clés autorisé (2 000) renverrait 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 d'incompatibilité 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 une commande GET pour obtenir un nouveau modèle et une nouvelle valeur ETag, mettre à jour le modèle, puis soumettre à l'aide de ce modèle et de la nouvelle valeur ETag.
  • Une commande PUT (demande de modèle de mise à jour de la configuration à distance) a été effectuée sans spécifier d'en-tête If-Match .
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 est survenue. Si cette erreur se produit, déposez un ticket d'assistance Firebase

Un code d'état de 200 signifie que le modèle de configuration à distance (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 auparavant 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 s'affichent comme prévu. Ceci est essentiel car l'ordre des conditions affecte la manière dont elles sont évaluées (la première condition évaluée comme true prend effet).

Utilisation 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 les mises à jour des ressources qui se chevauchent. Pour en savoir plus sur les ETags, consultez ETag - HTTP .

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

Vous pouvez contourner l'ETag, et la protection qu'il fournit, en forçant le modèle Remote Config à être mis à jour comme suit : If-Match: * Cependant, cette approche n'est pas recommandée car elle risque d'entraîner la perte des mises à jour de votre Remote 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 de clients d'API et d'utilisateurs de la console Firebase.

Pour obtenir des conseils sur la gestion des versions de modèle Remote Config, consultez Modèles et gestion des versions de Remote Config .

,

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

À l'aide de l' API REST Remote Config ou des SDK d'administration décrits dans ce guide, vous pouvez contourner la gestion du modèle dans la console Firebase pour intégrer directement les modifications de Remote Config dans vos propres processus. Par exemple, avec les API backend Remote Config, vous pouvez :

  • Planification des mises à jour de Remote Config . En utilisant des appels d'API conjointement avec une tâche cron, vous pouvez modifier les valeurs de Remote Config de manière régulière.
  • Importez par lots les valeurs de configuration afin de passer efficacement de votre propre système propriétaire à Firebase Remote Config.
  • Utilisez Remote Config avec Cloud Functions pour Firebase , en modifiant les valeurs de 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 automatiquement cette promotion une fois que vous avez détecté qu'un nombre suffisant de personnes ont interagi avec la nouvelle fonctionnalité.

    Diagramme illustrant l'interaction du backend Remote Config 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 de Remote Config. Pour passer en revue certains codes qui effectuent ces tâches via l'API REST, consultez l'un de ces exemples d'application :

Modifier la configuration à distance à l'aide du SDK d'administration Firebase

Le SDK Admin est un ensemble de bibliothèques de serveur 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 de générer et de vérifier des jetons d'authentification Firebase, de lire et d'écrire à partir de la base de données en temps réel, etc. Pour en savoir plus sur les prérequis et la configuration du SDK Admin, consultez Ajouter le SDK Admin Firebase à 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 SDK Admin sans paramètres, le SDK utilise les informations d'identification par défaut de l'application Google et lit les options de la variable d'environnement FIREBASE_CONFIG . Si le contenu de la variable FIREBASE_CONFIG 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 entre sa création et le moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et gestion des versions pour plus d'informations.

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

Les paramètres et les valeurs de paramètres créés spécifiquement en tant que variantes dans une expérience de test A/B ne sont pas inclus dans les modèles exportés.

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 Remote Config. 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 apporté des modifications.

Modifier les conditions de configuration à distance

Vous pouvez modifier et ajouter par programmation des conditions et des valeurs conditionnelles de Remote Config. 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 apporté des modifications.

Les API backend de 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, consultez la référence d'expression conditionnelle .

Valider le modèle de configuration à distance

Facultativement, 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 vérifie les erreurs telles que les clés en double pour les paramètres et les conditions, les noms de condition invalides ou les conditions inexistantes, ou les etags mal formatés. Par exemple, une requête contenant plus que le nombre de clés autorisé (2 000) 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 d'un numéro au modèle qu'il a remplacé.

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

Les personnalisations et les conditions de Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limitations suivantes lorsque vous tentez de publier dans un autre projet :

  • Les personnalisations ne peuvent pas être importées d'un projet à l'autre.

    Par exemple, si des personnalisations sont activées dans votre projet et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet, mais vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

  • Les conditions peuvent être importées d'un projet à l'autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

    Par exemple, si vous avez un paramètre Remote Config qui utilise une condition qui spécifie une valeur de plateforme iOS , le modèle peut être publié dans un autre projet, car les valeurs de plateforme sont les mêmes pour tous les projets. Toutefois, s'il contient une condition qui repose sur un ID d'application ou une audience d'utilisateurs spécifique qui n'existe pas dans le projet cible, la validation échouera.

  • Si le modèle que vous envisagez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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 REST Remote Config sur https://firebaseremoteconfig.googleapis.com . Pour plus de détails, consultez la référence de l'API .

Obtenez un jeton d'accès pour authentifier et autoriser les demandes d'API

Les projets Firebase prennent en charge les comptes de service Google , que vous pouvez utiliser pour appeler les API du serveur Firebase à partir de votre serveur d'applications ou de votre 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 requêtes 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 soit définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS , soit transmettre explicitement le chemin d'accès à la clé du 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 sur le chemin d'accès au fichier JSON contenant 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) peuvent déterminer implicitement vos informations d'identification, ce qui vous permet 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 identifiants Firebase avec la bibliothèque Google Auth pour votre langue préférée afin de récupérer un jeton d'accès OAuth 2.0 de courte durée :

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 Jetons 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

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

Après l'expiration de votre jeton d'accès, 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 à Remote Config, demandez 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 entre sa création et le moment où vous la remplacez par une mise à jour : 90 jours, avec une limite totale de 300 versions stockées. Voir Modèles et gestion des versions 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.

Les paramètres et les valeurs de paramètres créés spécifiquement en tant que variantes dans une expérience de test A/B ne sont pas inclus dans les modèles exportés.

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 d'API renvoie le JSON suivant, ainsi qu'un en-tête séparé qui inclut un ETag que vous utilisez pour la requête suivante.

Valider le modèle de configuration à distance

En option, vous pouvez valider vos mises à jour avant de les publier. Validez les mises à jour du modèle en ajoutant à votre demande de publication 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 signifient que votre mise à jour a été validée 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 d'un numéro au modèle qu'il a remplacé.

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

Les personnalisations et les conditions de Remote Config sont incluses dans les modèles téléchargés. Il est donc important de connaître les limitations suivantes lorsque vous tentez de publier dans un autre projet :

  • Les personnalisations ne peuvent pas être importées d'un projet à l'autre.

    Par exemple, si des personnalisations sont activées dans votre projet et que vous téléchargez et modifiez un modèle, vous pouvez le publier dans le même projet, mais vous ne pouvez pas le publier dans un autre projet, sauf si vous supprimez les personnalisations du modèle.

  • Les conditions peuvent être importées d'un projet à l'autre, mais notez que toutes les valeurs conditionnelles spécifiques (comme les ID d'application ou les audiences) doivent exister dans le projet cible avant la publication.

    Par exemple, si vous avez un paramètre Remote Config qui utilise une condition qui spécifie une valeur de plateforme iOS , le modèle peut être publié dans un autre projet, car les valeurs de plateforme sont les mêmes pour tous les projets. Toutefois, s'il contient une condition qui repose sur un ID d'application ou une audience d'utilisateurs spécifique qui n'existe pas dans le projet cible, la validation échouera.

  • Si le modèle que vous envisagez de publier contient des conditions qui reposent sur Google Analytics, Analytics doit être activé dans le projet cible.

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 commande curl , 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

Comme il s'agit d'une demande d'écriture, l' ETag est modifié par cette commande et un ETag mis à jour est fourni dans les en-têtes de réponse de la prochaine commande PUT .

Modifier les conditions de configuration à distance

Vous pouvez modifier par programmation les conditions et les valeurs conditionnelles de Remote Config. 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."
    }
  }
}

The modifications above first define a set of conditions, and then defines default values and condition-based parameter ( conditional values ) values for each parameter. It also adds an optional description for each element; like code comments, these are for developer use and are not displayed in the app. An ETag is also provided for version control purposes.

The Remote Config backend APIs provide several conditions and comparison operators that you can use to change the behavior and appearance of your app. To learn more about conditions and the operators supported for these conditions, see the conditional expression reference .

HTTP Error codes

Status Code Meaning
200 Successfully Updated
400 A validation error occurred. For example, a request containing more than the allowed number of keys—2000—would return 400 (Bad Request) with the error message, Param count too large . Also, this HTTPS Status Code can occur in these two situations:
  • A version mismatch error occurred because the set of values and conditions have been updated since you last retrieved an ETag value. To resolve this, you should use a GET command to get a fresh template and ETag value, update the template, and then submit using that template and the fresh ETag value.
  • A PUT command (Update Remote Config template request) was made without specifying an If-Match header.
401 An authorization error occurred (no access token was provided or the Firebase Remote Config REST API has not been added to your project in the Cloud Developer Console)
403 An authentication error occurred (the wrong access token was provided)
500 An internal error occurred. If this error occurs, file a Firebase support ticket

A status code of 200 means that the Remote Config template (parameters, values and conditions for the project) has been updated and is now available to apps that use this project. Other status codes indicate that the Remote Config template that existed previously is still in effect.

After you submit updates to your template, go to the Firebase console to verify that your changes appear as expected. This is critical because the ordering of conditions affects how they are evaluated (the first condition that evaluates true takes effect).

ETag usage and forced updates

The Remote Config REST API uses an entity tag (ETag) to prevent race conditions and overlapping updates to resources. To learn more about ETags, see ETag - HTTP .

For the REST API, Google recommends that you cache the ETag provided by the most recent GET command, and use that ETag value in the If-Match request header when issuing PUT commands. If your PUT command results in an HTTPS Status Code 409, you should issue a fresh GET command to acquire a new ETag and template to use with your next PUT command.

You can circumvent the ETag, and the protection from that it provides, by forcing the Remote Config template to be updated as follows: If-Match: * However, this approach is not recommended because it risks causing the loss of updates to your Remote Config template if multiple clients are updating the Remote Config template. This kind of conflict could occur with multiple clients using the API, or with conflicting updates from API clients and Firebase console users.

For guidance on managing Remote Config template versions, see Remote Config templates and versioning .