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

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

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

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

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

    תרשים המציג את ה-Remote Config באינטראקציה עם כלים ושרתים מותאמים אישית

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

שנה את התצורה המרוחקת באמצעות Firebase Admin SDK

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

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

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

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

לדוגמה:

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

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

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

אתה יכול להשתמש בממשקי ה-API האחוריים כדי לקבל את הגרסה הפעילה הנוכחית של תבנית התצורה המרוחקת בפורמט 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);
      });
}

Java

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

שנה פרמטרים של תצורה מרחוק

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

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

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

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

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

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

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

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

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

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

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

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

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

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

במידת הצורך, אתה יכול להשתמש ב- 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);
      });
}

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

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

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

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

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

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

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

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

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

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

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

קודי שגיאה של HTTP

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

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

לאחר שליחת עדכונים לתבנית, עבור אל מסוף 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 מרחוק גרסאות .