שנה את התצורה מרחוק בתכנות

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

באמצעות ממשק API לתצורות REST מרחוק או ערכות SDK Admin המתוארות במדריך זה, אתה יכול לעקוף ניהול התבנית במסוף Firebase לשלב ישירות מרחוק Config משנה לתוך תהליכים משלך. לדוגמה, עם ממשקי API של תוכנת גב תומכת מרחוק, אתה יכול:

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

החלקים הבאים במדריך זה מתארים פעולות שניתן לבצע עם ממשקי ה- API של הגדרות מרחוק. לעיון בקוד המבצע משימות אלה באמצעות ממשק ה- REST, עיין באחת האפליקציות לדוגמה:

שנה תצורה מרחוק באמצעות ה- SDK לניהול ה- Firebase

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

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

אתחל את ה- SDK ואשר בקשות API

כשאתה לאתחל את SDK של ניהול ללא פרמטרים, ערכת פיתוח התוכנה משתמשת אישורים ברירת Google Application וקורא אפשרויות מן FIREBASE_CONFIG משתנה הסביבה. אם התוכן של FIREBASE_CONFIG משתנית מתחיל עם { זה ינותח כאובייקט JSON. אחרת SDK מניח שהמחרוזת היא שם של קובץ JSON המכיל את האפשרויות.

לדוגמה:

Node.js

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

ג'אווה

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

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

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

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

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

ג'אווה

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

שנה פרמטרים של Config Remote

באפשרותך לשנות ולהוסיף פרמטרים וקבוצות פרמטרים של Config Remote. לדוגמה, לקבוצת פרמטרים קיימת בשם "new_menu" תוכל להוסיף פרמטר לשליטה על הצגת המידע העונתי:

Node.js

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

ג'אווה

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

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

שנה את תנאי התצורה מרחוק

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

Node.js

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

ג'אווה

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

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

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

אמת את תבנית התצורה מרחוק

לחלופין, תוכל לאמת את העדכונים שלך לפני פרסום אותם, כפי שמוצג:

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

ג'אווה

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

תהליך אימות זה בודק שגיאות כגון מפתחות כפולים של פרמטרים ותנאים, שמות תנאים לא חוקיים או תנאים לא קיימים, או תגים לא מעוצבים. לדוגמה, בקשה המכילה יותר מהמותר מפתחות-2000-תחזיר את הודעת השגיאה, Param count too large .

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

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

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

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

ג'אווה

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 API

סעיף זה מתאר את היכולות העיקריות של API REST Config מרחוק על https://firebaseremoteconfig.googleapis.com . לפרטים מלאים, לראות את התייחסות API .

קבל אסימון גישה לאימות ובקשות של בקשות API

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

כדי לאמת חשבון שירות ולאשר לו גישה לשירותי Firebase, עליך ליצור קובץ מפתח פרטי בפורמט JSON.

ליצירת קובץ מפתח פרטי עבור חשבון השירות שלך:

  1. במסוף Firebase, פתח את הגדרות> חשבונות שירות .

  2. לחץ צור חדש פרטי מפתח, ולאחר מכן לאשר ידי לחיצה על צור מפתח.

  3. אחסן בבטחה את קובץ ה- JSON המכיל את המפתח.

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

כדי להגדיר את משתנה הסביבה:

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

לינוקס או macOS

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

חלונות

עם PowerShell:

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

לאחר השלמת השלבים שלעיל, אישורי ברירת המחדל של היישום (ADC) מסוגלים לקבוע במשתמע את האישורים שלך, ומאפשרים לך להשתמש באישורי חשבון שירות בעת בדיקה או הפעלה בסביבות שאינן של Google.

שימוש באישורי Firebase שלך יחד עם ספריית מחבר גוגל עבור השפה המועדפת עליך לאחזר גישת OAuth 2.0 קצרת מועד אסימון:

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

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

פִּיתוֹן

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

ג'אווה

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

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

כדי לאשר גישה מרחוק Config, לבקש את היקף https://www.googleapis.com/auth/firebase.remoteconfig .

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

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

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

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

סִלְסוּל

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

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

בקשת HTTP גולמית

Host: firebaseremoteconfig.googleapis.com

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

שיחת API זו מחזירה את JSON הבא, יחד עם כותרת נפרדת כולל ETag כי אתה משתמש עבור הבקשה עקב.

אמת את תבנית התצורה מרחוק

לחלופין, תוכל לאמת את העדכונים שלך לפני פרסום אותם. עדכוני תבנית אמת ידי צירוף לבקשה לפרסם את פרמטר URL ?validate_only=true . בתשובה, קוד מצב 200 ו ETag מעודכן עם הסיומת -0 אמצעים שהעדכון שלך אומת בהצלחה. כל תגובה שאינה 200 מצביעה על כך שנתוני JSON מכילים שגיאות שעליך לתקן לפני הפרסום.

עדכן את תבנית התצורה מרחוק

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

במידת הצורך, אתה יכול להשתמש ב- API 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 הפקודה, ניתן לציין את התוכן בעזרת התו "@", ואחריו את שם הקובץ.

בקשת HTTP גולמית

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

בגלל זה היא בקשה כתיבה, ETag ישונה על ידי הפקודה הזאת מעודכנת ETag מסופק כותרות התגובה של הבא PUT הפקודה.

שנה את תנאי התצורה מרחוק

באפשרותך לשנות באופן תוכניתי את התנאים והערכים המותנים של Config Remote. עם ה- REST API, עליך לערוך את התבנית ישירות כדי לשנות את התנאים לפני פרסום התבנית.

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

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

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

קודי שגיאה HTTP

קוד סטטוס מַשְׁמָעוּת
200 עודכן בהצלחה
400 אירעה שגיאת אימות. לדוגמה, בקשה המכילה יותר מהמותר מפתחות-2000-תחזיר 400 (בקשה לא טובה) עם הודעת השגיאה, Param count too large . כמו כן, קוד מצב HTTPS זה יכול להתרחש בשני מצבים אלה:
  • אירעה שגיאת אי התאמה לגרסה מכיוון שמערך הערכים והתנאים עודכנו מאז אחזרת ערך ETag בפעם האחרונה. כדי לפתור זאת, אתה צריך להשתמש GET פקוד כדי לקבל תבנית טריה וערך ETag, לעדכן את התבנית, ולאחר מכן להגיש באמצעות תבנית וערך ETag הטרי.
  • PUT פקוד (בקשת תבנית Config מרחוק עדכון) נעשה ללא מטרה שהיא If-Match כותרת.
401 אירעה שגיאת הרשאה (לא סופק אסימון גישה או ש- Firebase Remote Config REST API לא נוסף לפרויקט שלך במסוף המפתחים בענן)
403 אירעה שגיאת אימות (סופק אסימון הגישה הלא נכון)
500 אירעה שגיאה פנימית. אם שגיאה זו מתרחשת, לשלוח כרטיס תמיכה Firebase

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

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

שימוש ב- ETag ועדכונים מאולצים

ה- Remote Config REST API משתמש בתג ישות (ETag) כדי למנוע תנאי מרוץ ועדכונים חופפים במשאבים. כדי ללמוד עוד על ETags, לראות ETag - HTTP .

עבור ה- API REST, גוגל ממליצה למטמון ETag שמספקת האחרונה GET הפקודה, והשימוש כי ערך ETag של If-Match בכותרת הבקשה כאשר הנפקת PUT פקודות. אם שלך PUT תוצאות הפקודה תחת סטאטוס HTTPS קוד 409, אתה צריך להוציא טריים GET הפקודה לרכוש ETag ואת תבנית חדשה לשימוש עם הבא שלך PUT הפקודה.

אתה יכול לעקוף את ETag, ואת ההגנה מפני שהיא מספקת, על ידי לאלץ את התבנית Config מרחוק כדי להתעדכן כדלקמן: If-Match: * עם זאת, גישה זו אינה מומלצת משום שהיא מסתכנת גרימת אובדן עדכונים Config מרחוק שלך תבנית אם מספר לקוחות מעדכנים את תבנית התצורה מרחוק. התנגשות מסוג זה יכולה להתרחש עם מספר לקוחות המשתמשים בממשק ה- API, או עם עדכונים סותרים של לקוחות API ומשתמשי מסוף Firebase.

לקבלת הדרכה על ניהול גרסאות תבנית Config מרחוק, לראות תבניות Config מרחוק גרסאות .