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

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

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

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

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

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

ה- Admin SDK הוא קבוצה של ספריות שרתים המאפשרות לך לקיים אינטראקציה עם Firebase מסביבות מיוחדות. בנוסף לביצוע עדכונים ל- Config מרחוק, ה- 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();

ג'אווה

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

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

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

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

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

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

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

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

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

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

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

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 .

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

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

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

שנה תצורה מרחוק באמצעות ממשק ה- API של REST

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

קודי שגיאה ב- HTTP

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

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

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

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

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

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

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

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