דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

אפשר גם להשתמש ב-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 מסוף

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

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

CLI של Firebase

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. כדי לאחזר גרסת תבנית שמורה:

מסוף Firebase

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

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

Firebase CLI

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

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

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

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

Firebase מסוף

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

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 Parameters, לוחצים על Change history.

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

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

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

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

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

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

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

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

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

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

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

מסוף Firebase

בכרטיסייה פרמטרים או תנאים, פותחים את תפריט ובוחרים באפשרות הורדת קובץ התצורה הנוכחי.Remote Config
כשמופיעה בקשה, לוחצים על 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

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

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

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

תהליך אימות התבנית כולל בדיקה של שגיאות כמו מפתחות כפולים לפרמטרים ולתנאים, שמות תנאים לא חוקיים או תנאים לא קיימים, או תגי ETag בפורמט שגוי. לדוגמה, בקשה שמכילה יותר ממספר המפתחות המותר – 2000 – תחזיר את הודעת השגיאה 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 מסוף

בכרטיסייה Remote Config Parameters or conditions, פותחים את תפריט ולוחצים על Publish from a file (פרסום מקובץ).
כשמופיעה בקשה לכך, לוחצים על Browse, עוברים לקובץ Remote Config שרוצים לפרסם ובוחרים אותו. לאחר מכן לוחצים על Select.
הקובץ יאומת, ואם הוא יסתיים בהצלחה, תוכלו ללחוץ על Publish (פרסום) כדי שההגדרות יהיו זמינות באופן מיידי לאפליקציות ולמשתמשים.

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

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

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