Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

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

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

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

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

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

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

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

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

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

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

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

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

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 Remote Config בכתובת https://firebaseremoteconfig.googleapis.com . לפרטים מלאים, עיין בהתייחסות ל- API .

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

פרויקטים של Firebase תומכים בחשבונות שירות של Google, שבהם אתה יכול לקרוא ממשקי API של שרת 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 שלך ​​יחד עם ספריית הלקוחות של Google API עבור השפה המועדפת עליך כדי לאחזר אסימון גישה קצר 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 {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

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

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

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

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

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

אתה יכול להשתמש בממשקי ה- API האחוריים כדי לקבל את הגרסה הפעילה הנוכחית של תבנית 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 Validate_only ?validate_only=true . בתגובה, קוד סטטוס 200 ותג מעודכן עם הסיומת -0 פירושם שהעדכון שלך אומת בהצלחה. כל תגובה שאינה של 200 מציינת כי נתוני JSON מכילים שגיאות שעליך לתקן לפני הפרסום.

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

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

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

סִלְסוּל

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 (עדכון בקשת תבנית תצורה מרחוק) נעשתה מבלי לציין כותרת של If-Match .
401 אירעה שגיאת הרשאה (לא סופק אסימון גישה או שממשק ה- API של REST ה- Configure REST מרחוק לא נוסף לפרויקט שלך במסוף המפתחים בענן)
403 אירעה שגיאת אימות (סופק אסימון הגישה השגוי)
500 אירעה שגיאה פנימית. אם שגיאה זו מתרחשת, הגש כרטיס תמיכה של Firebase

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

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

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

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

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

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

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