תבניות הגדרת תצורה מרחוק וניהול גרסאות


תבניות Remote Config הן קבוצות של תנאים ופרמטרים בפורמט JSON שיצרתם לפרויקט Firebase. שלך אפשר ליצור תבניות לקוח, שממנה האפליקציה מאחזרת ערכים, servers, שמהם לקוחות השרתים יכולים לאחזר ערכים.

בקטע הזה נדון בתבניות לקוח. למידע נוסף על תגים ספציפיים לשרת תבניות, לוחצים תבניות לשרתים.

אפשר לשנות ולנהל את התבנית באמצעות מסוף Firebase, שבו תוכן התבנית מוצג בפורמט גרפי בכרטיסיות פרמטרים וגם הכרטיסיות תנאים.

אפשר גם להשתמש ב-API ל-REST וב-Admin SDK של Remote Config או ב-CLI של Firebase כדי לשנות ולנהל את תבנית הלקוח.

דוגמה לקובץ תבנית של שרת:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

אפשר לבצע את המשימות הבאות לניהול גרסאות באמצעות מסוף Firebase:

  • הצגת רשימה של כל גרסאות התבניות השמורות
  • אחזור של גרסה ספציפית
  • חזרה לגרסת לקוח ספציפית
  • מחיקת תבניות Remote Config מהדף Change history

המגבלה הכוללת היא 300 גרסאות שמאוחסנות לכל החיים לכל סוג של תבנית (300 תבניות לקוח ו-300 תבניות שרת), כולל מספרי גרסאות שמאוחסנים של תבניות שנמחקו. אם מפרסמים יותר מ-300 גרסאות של תבניות לכל סוג תבנית במהלך החיים של הפרויקט, הגרסאות המוקדמות ביותר נמחקות כדי לשמור על מספר מקסימלי של 300 גרסאות של אותו סוג.

בכל פעם שמעדכנים את הפרמטרים, Remote Config יוצרת תבנית Remote Config חדשה עם גרסה, ושומרת את התבנית הקודמת כגרסה שאפשר לאחזר או לחזור אליה לפי הצורך. מספרי הגרסאות נספרים ברצף מהערך הראשוני שמאוחסן על ידי Remote Config. כל התבניות כוללות שדה version כפי שמוצג, שמכיל מטא-נתונים בנושא גרסה ספציפית.

אפשר למחוק תבניות Remote Config לפי הצורך מהדףהיסטוריית שינוייםבמסוף Remote Config.

ניהול גרסאות של תבניות Remote Config

בקטע הזה מוסבר איך לנהל גרסאות של Remote Config תבנית.

הצגת רשימה של כל הגרסאות השמורות של התבנית Remote Config

אפשר לאחזר רשימה של כל הגרסאות השמורות של התבנית Remote Config. ככה עושים את זה:

Firebase console

בכרטיסייה פרמטרים, מסמנים את התיבה 'שעון' הסמל שמוצג בפינה השמאלית העליונה. פעולה זו פותחת את היסטוריית שינויים שבו מפורטים כל הגרסאות המאוחסנות של התבניות בתפריט הרשימה מצד שמאל.

הפרטים המוצגים עבור כל גרסה שמורה כוללים מידע על מקור השינויים הוא במסוף, ב-API ל-REST, מחזרה למצב קודם, או אם הם היו שינויים מצטברים כתוצאה משמירה כפויה של התבנית.

Firebase CLI

firebase remoteconfig:versions:list

אפשר להשתמש באפשרות --limit כדי להגביל את מספר הגרסאות שמוחזרות. מעבר '0' כדי לאחזר את כל הגרסאות.

Node.js

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Java

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

REST

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

רשימת התבניות כוללת מטא-נתונים לכל הגרסאות המאוחסנות, כולל זמן העדכון, המשתמש שביצע אותו ואיך הוא בוצע. הנה דוגמה לרכיב גרסה:

```json
{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]
}
```

אחזור של גרסה ספציפית של התבנית Remote Config

אפשר לאחזר כל גרסה ספציפית של התבנית Remote Config ששמורה. כדי לאחזר תבנית שמורה version:

Firebase console

כברירת מחדל, חלונית הפרטים הכרטיסייה היסטוריית שינויים מציג את התבנית הפעילה הנוכחית. לצפייה פרטים עבור גרסה אחרת ברשימה, בחר אותה מהתפריט הימני.

כדי להציג את ההבדלים המפורטים בין הגרסה שנבחרה כרגע לבין כל גרסה אחרת ששמורה, מעבירים את העכבר מעל תפריט ההקשר של גרסה שלא נבחרה ובוחרים באפשרות השוואה לגרסה שנבחרה.

CLI של Firebase

firebase remoteconfig:get -v VERSION_NUMBER

אפשר גם לכתוב את הפלט לקובץ מסוים באמצעות -o, FILENAME.

Node.js

כדי לאחזר את הגרסה האחרונה של התבנית, מעבירים את הערך getTemplate() ללא ארגומנטים. כדי לאחזר גרסה ספציפית, משתמשים ב-getTemplateAtVersion().

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

REST

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

הפרמטר ?version_number של כתובת האתר חוקי רק עבור פעולות של GET; אי אפשר להשתמש בו כדי לציין מספרי גרסאות לעדכונים. תוצאה דומה בקשה בלי ?version_number יאחזר את התבנית הפעילה הנוכחית.

חזרה לגרסה ספציפית שנשמרה של התבנית Remote Config

אפשר לחזור לגרסה כלשהי של התבנית ששמורה. כדי להחזיר תבנית למצב קודם:

מסוף Firebase

לגרסאות קודמות של התבנית שעומדות בדרישות להחזרה לאחור, יופיע לחצן אפשרות להחזרה לאחור לגרסה הזו בפינה השמאלית העליונה של הדף היסטוריית השינויים. לוחצים ומאשרים את הפעולה הזו רק אם אתם בטוחים שאתם רוצים לחזור לגרסה הזו ולהשתמש בערכים האלה מיד בכל האפליקציות והמשתמשים.

CLI של Firebase

firebase remoteconfig:rollback -v VERSION_NUMBER

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Java

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

REST

כדי לחזור לגרסה הקודמת של תבנית Remote Config ששמורה, שולחים בקשת HTTP POST עם השיטה המותאמת אישית :rollback, ובגוף הבקשה מציינים את הגרסה הספציפית שרוצים להחיל. לדוגמה:

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

התגובה מכילה את התוכן של התבנית השמורה שפעילה עכשיו, כולל מטא-נתונים של גרסה חדשה.

חשוב לזכור שפעולת ההחזרה למצב הקודם יוצרת בפועל גרסה ממוספרת חדשה. לדוגמה, אם חוזרים לגרסה 6 מגרסה 10, נוצרת למעשה עותק חדש של גרסה 6, ששונה מהגרסה המקורית רק במספר הגרסה שהוא 11. גרסת המקור 6 עדיין מאוחסנת, בהנחה שהתוקף שלה לא פג, וגרסה 11 הופכת לתבנית הפעילה.

מחיקת תבנית של Remote Config

אפשר למחוק תבניות Remote Config במסוף Firebase. שפת תרגום מחיקת תבנית Remote Config:

1. מליגות ה-Remote Config פרמטרים דף, ללחוץ היסטוריית שינויים.
  1. עוברים לתבנית שרוצים למחוק ולוחצים על עוד, ואז בוחרים מחיקה.

  2. כשמתבקשים לאשר את המחיקה, לוחצים על מחיקה.

הורדה ופרסום של תבניות Remote Config

אפשר להוריד ולפרסם Remote Config תבניות כדי לשלב אותן בקרת מקורות ומערכות build, עדכוני הגדרות אוטומטיים, ושמירת פרמטרים והערכים מסונכרנים בין פרויקטים מרובים.

אפשר להוריד את התבנית Remote Config הפעילהמהמסוף Firebase. לאחר מכן אפשר לעדכן את ייצאתם קובץ JSON ומפרסמים אותו באותו פרויקט, או מפרסמים אותו פרויקט קיים.

נניח שיש לכם כמה פרויקטים שמייצגים שלבים שונים במחזור החיים של פיתוח התוכנה, כמו סביבות פיתוח, בדיקה, Staging וייצור. במקרה כזה, אפשר לקדם תבנית שנבדקה במלואה את סביבת ה-Staging לסביבת הייצור באמצעות הורדה שלה פרויקט Staging ופרסום שלו בפרויקט הייצור.

אפשר להשתמש בשיטה הזו גם כדי להעביר הגדרות מפרויקט אחד אל אחר, או לאכלס פרויקט חדש עם פרמטרים וערכים של הפרויקט הקיים.

פרמטרים וערכים של פרמטרים שנוצרו במיוחד כוריאנטים בניסוי A/B Testing לא נכללים בתבניות שיוצאו.

כדי לייצא ולייבא Remote Config תבניות:

  1. מורידים את תבנית התצורה העדכנית של Remote Config.
  2. מאמתים את התבנית Remote Config.
  3. מפרסמים את התבנית Remote Config.

מורידים את התבנית הנוכחית של הגדרת תצורה מרחוק

צריך להשתמש בקוד הבא כדי להוריד את תבנית Remote Config הפעילה ב: פורמט JSON:

מסוף Firebase

  1. בכרטיסייה Remote Config Parameters or Conditions, פותחים את Menu ובוחרים באפשרות Download current config file.
  2. כשמוצגת בקשה, לוחצים על Download config file, בוחרים את המיקום שבו רוצים לשמור את הקובץ ולוחצים על Save.

CLI של Firebase

firebase remoteconfig:get -o filename

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

REST

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

הפקודה הזו מפיקה את המטען הייעודי (payload) של JSON לקובץ אחד, ואת הכותרות. (כולל ה-ETag) לקובץ headers נפרד.

אימות התבנית של Remote Config

אפשר לאמת את עדכוני התבניות לפני שמפרסמים אותם באמצעות Firebase Admin SDK או ה-API ל-REST. התבניות מאומתות גם כשמנסים כדי לפרסם מה-CLI של Firebase או ממסוף Firebase.

תהליך אימות התבנית כולל בדיקה של שגיאות כמו מפתחות כפולים לפרמטרים ולתנאים, שמות תנאים לא חוקיים או תנאים לא קיימים, או תגי ETag בפורמט שגוי. לדוגמה, בקשה שמכילה יותר מהמותר מספר המפתחות — 2,000 — יחזיר את הודעת השגיאה, Param count too large.

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

REST

כדי לאמת עדכוני תבנית, מצרפים את הפרמטר ?validate_only=true של כתובת האתר לבקשת הפרסום שלך:

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?validate_only=true -d @filename

אם התבנית אומתה בהצלחה, פקודת ה-curl תחזיר את הערך תבנית JSON ששלחתם, ובקובץ headers השמור תראו סטטוס HTTP/2 200 ו-ETag מעודכן עם הסיומת -0. אם התבנית לא אומתה, תקבלו את הודעת השגיאה של האימות בתגובת ה-JSON, וקובץ headers יכיל תגובה שאינה 200 (וללא ETag).

פרסום התבנית Remote Config

אחרי שמורידים תבנית, מבצעים את השינויים הנדרשים בתוכן ה-JSON ומאמתים אותו, אפשר לפרסם אותה בפרויקט.

פרסום תבנית מחליף את כל תבנית התצורה הקיימת עם מעודכן וכל גרסה של התבנית עולה בשורה אחת. מכיוון שההגדרות כוללות מוחלפות, אם מוחקים פרמטר מקובץ ה-JSON ומפרסמים אותו, הפרמטר נמחק מהשרת ולא זמין יותר ללקוחות.

אחרי הפרסום, השינויים בפרמטרים ובערכים יהיו זמינים מיד לאפליקציות ולמשתמשים שלכם. במקרה הצורך, אפשר חזרה לגרסה קודמת.

כדי לפרסם את התבנית, משתמשים בפקודות הבאות:

Firebase console

  1. מתוך Remote Config פרמטרים או תנאים , פותחים את התפריט, ובוחרים באפשרות פרסום מקובץ.
  2. כשמופיעה בקשה, לוחצים על עיון, עוברים אל קובץ Remote Config שרוצים לפרסם ולוחצים על בחירה.
  3. הקובץ יאומת, ואם התהליך יסתיים בהצלחה, תוכלו ללחוץ על פרסום כדי שההגדרות יהיו זמינות באופן מיידי לאפליקציות ולמשתמשים שלכם.

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

REST

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

בפקודה curl הזו, אפשר לציין את התוכן באמצעות התו "@" ואחריו שם הקובץ.

Remote Config התאמות אישיות ותנאים כלולים התבניות שהורדתם, לכן חשוב לשים לב לנקודות הבאות מגבלות כשמנסים לפרסם בפרויקט אחר:

  • אי אפשר לייבא התאמות אישיות מפרויקט לפרויקט.

    לדוגמה, אם הפעלתם התאמות אישיות בפרויקט והורדתם תבנית ועיצבתם אותה, תוכלו לפרסם אותה באותו פרויקט, אבל לא תוכלו לפרסם אותה בפרויקט אחר אלא אם תמחקו את ההתאמות האישיות מהתבנית.

  • אפשר לייבא את התנאים מפרויקט לפרויקט, אבל חשוב לזכור ערכים מותנים ספציפיים (כמו מזהי אפליקציות או קהלים), צריכים להתקיים ב- בפרויקט היעד לפני הפרסום.

    לדוגמה, אם יש לכם פרמטר Remote Config שמשתמש בתנאי שמציין ערך פלטפורמה של iOS, אפשר לפרסם את התבנית בפרויקט אחר כי ערכי הפלטפורמה זהים בכל פרויקט. עם זאת, אם התנאים מכילים תנאי שמסתמך על מזהה אפליקציה ספציפי או על משתמש ספציפי קהל שלא קיים בפרויקט היעד, האימות ייכשל.

  • אם התבנית שאתם מתכננים לפרסם מכילה תנאים שמסתמכים על Google Analytics, צריך להפעיל את Analytics בפרויקט היעד.

הורדת Remote Config ברירות מחדל של תבניות

יכול להיות שהאפליקציה לא תמיד תהיה מחוברת לאינטרנט, ולכן צריך להגדיר ערכים שמוגדרים כברירת מחדל באפליקציה בצד הלקוח לכל הפרמטרים של Remote Config. כדאי גם לסנכרן מדי פעם את ברירת המחדל של לקוח האפליקציה וערכי פרמטר ברירת מחדל של Remote Config בקצה העורפי, כי עשוי להשתנות עם הזמן.

כפי שמתואר בקישורים הספציפיים לפלטפורמה בסוף הקטע הזה, אפשר להגדיר את הגדרות ברירת המחדל האלה באופן ידני באפליקציה, או לשפר את התהליך על ידי הורדת קבצים שמכילים רק את הצמדים של מפתח/ערך לכל הפרמטרים ואת ערכי ברירת המחדל שלהם בתבנית Remote Config הפעילה. לאחר מכן אפשר כוללים את הקובץ הזה בפרויקט ומגדירים את האפליקציה לייבא את הערכים האלה.

ניתן להוריד את הקבצים האלה בפורמט XML עבור אפליקציות ל-Android, פורמט של רשימת נכסים (plist) לאפליקציות ל-iOS ו-JSON לאפליקציות אינטרנט.

מומלץ להוריד מדי פעם את הגדרות ברירת המחדל של Remote Config לפני השקת אפליקציה חדשה, כדי לוודא שהאפליקציה והקצה העורפי של Remote Config יישארו מסונכרנים.

כדי להוריד קובץ שמכיל את ברירת המחדל של התבנית:

REST

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

משתמשים ב-XML, ב-PLIST או ב-JSON בתור הערך של format, בהתאם לפורמט הקובץ שרוצים להוריד.

מסוף Firebase

  1. בכרטיסייה Parameters, פותחים את Menu ובוחרים באפשרות Download default values.
  2. כשתתבקשו, לחצו על לחצן הבחירה של הקובץ. הפורמט שרוצים להוריד, ואז לוחצים על הורדת הקובץ.

מידע נוסף על ייבוא ערכי ברירת מחדל של Remote Config לאפליקציה זמין במאמרים הבאים: