تغییر دادن «پیکربندی از راه دور» به‌صورت برنامه‌نویسی‌شده

Config templates using the Admin SDK, REST API, and Firebase CLI. page_type: guide

این سند نحوه خواندن و اصلاح برنامه‌نویسی‌شده مجموعه پارامترها و شرایط با قالب JSON را که به‌عنوان الگوی Remote Config شناخته می‌شود شرح می‌دهد. این به شما امکان می‌دهد تغییرات الگو را در باطن انجام دهید که برنامه کارخواه می‌تواند بااستفاده از کتابخانه کارخواه واکشی کند.

بااستفاده از Remote Config REST API، Admin SDKs، یا Firebase CLI شرح‌داده‌شده در این راهنما، می‌توانید مدیریت الگو در کنسول Firebase را دور بزنید تا مستقیماً تغییرات Remote Config را در فرایندهای خودتان ادغام کنید. برای مثال، با Remote Config میاناهای برنامه‌سازی کاربردی پس‌زمینه، می‌توانید:

  • زمان‌بندی Remote Config به‌روزرسانی. بااستفاده از فراخوانی‌های میانای برنامه‌سازی کاربردی در ارتباط با cron job، می‌توانید مقادیر Remote Config را در زمان‌بندی منظمی تغییر دهید.
  • مقادیر پیکربندی را به‌صورت دسته‌ای وارد کنید تا به‌طور کارآمد از سیستم اختصاصی خودتان به Firebase Remote Config منتقل شوید.
  • از Remote Config با Cloud Functions for Firebase استفاده کنید، مقادیر را در برنامه‌تان براساس رویدادهایی که در سمت سرور اتفاق می‌افتد تغییر دهید. برای مثال، می‌توانید از Remote Config برای تبلیغ ویژگی جدیدی در برنامه‌تان استفاده کنید، و سپس وقتی تشخیص دادید افراد کافی با ویژگی جدید تعامل داشته‌اند، آن تبلیغ را به‌طور خودکار خاموش کنید.

نموداری که تعامل پسای «پیکربندی از راه دور» را با ابزارها و سرورهای سفارشی نشان می‌دهد

بخش‌های زیر در این راهنما عملیاتی را که می‌توانید بااستفاده از میاناهای برنامه‌سازی کاربردی پس‌بخش Remote Config انجام دهید شرح می‌دهد.

تغییر دادن Remote Config بااستفاده از Firebase Admin SDK

‫Admin SDK مجموعه‌ای از کتابخانه‌های سرور است که به شما امکان می‌دهد از محیط‌های ممتاز با Firebase تعامل داشته باشید. Admin SDK علاوه‌بر انجام به‌روزرسانی‌ها در Remote Config، امکان تولید و درستی‌سنجی کدهای احراز هویت Firebase و خواندن و نوشتن از Realtime Database را فراهم می‌کند. برای کسب اطلاعات بیشتر درباره پیش‌نیازها و راه‌اندازی Admin SDK، به افزودن Firebase Admin SDK به سرور مراجعه کنید.

برای مرور کد نمونه‌ای که این کارها را بااستفاده از Admin SDK انجام می‌دهد، یکی از برنامه‌های شروع سریع زیر را ببینید:

در جریان معمول Remote Config، ممکن است الگوی فعلی را دریافت کنید، برخی‌از پارامترها یا گروه‌های پارامتر و شرایط را اصلاح کنید، الگو را اعتبارسنجی کنید، و سپس آن را منتشر کنید. قبل‌از برقراری آن تماس‌های میانای برنامه‌سازی کاربردی، باید درخواست‌های کیت توسعه نرم‌افزار را مجاز کنید.

مقداردهی اولیه کیت توسعه نرم‌افزار و صدور مجوز برای درخواست‌های API

وقتی Admin SDK را بدون پارامتر مقداردهی اولیه می‌کنید، کیت توسعه نرم‌افزار از اعتبارنامه پیش‌فرض برنامه Google استفاده می‌کند و گزینه‌ها را از متغیر محیطی FIREBASE_CONFIG می‌خواند. اگر محتوای متغیر FIREBASE_CONFIG با { شروع شود، به‌عنوان شیء JSON تجزیه خواهد شد. درغیراین‌صورت، کیت توسعه نرم‌افزار فرض می‌کند که رشته نام فایل 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);

دریافت الگوی Remote Config فعلی

هنگام کار با الگوهای Remote Config، به‌خاطر داشته باشید که آن‌ها نسخه‌بندی شده‌اند و هر نسخه از زمان ایجاد تا زمانی که آن را با به‌روزرسانی جایگزین کنید، طول عمر محدودی دارد: ۹۰ روز، با محدودیت کلی ۳۰۰ نسخه ذخیره‌شده. برای اطلاعات بیشتر، به الگوها و نسخه‌بندی مراجعه کنید.

می‌توانید از میاناهای برنامه‌سازی کاربردی پس‌بخش برای دریافت نسخه فعال فعلی الگوی Remote Config در قالب JSON استفاده کنید.

پارامترها و مقادیر پارامترهایی که به‌طور خاص به‌عنوان متغیر در آزمایش A/B Testing ایجاد شده‌اند در الگوهای صادرشده گنجانده نمی‌شوند.

برای دریافت الگو:

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

تغییر دادن Remote Config پارامتر

می‌توانید به‌صورت برنامه‌نویسی‌شده پارامترها و گروه‌های پارامتر Remote 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 می‌توانید پارامترها و گروه‌های پارامتر جدید ایجاد کنید یا مقادیر پیش‌فرض، مقادیر شرطی، و توضیحات را اصلاح کنید. در همه موارد، باید پس‌از اعمال تغییرات، الگو را به‌طور صریح منتشر کنید.

اصلاح Remote Config شرط

می‌توانید به‌صورت برنامه‌نویسی‌شده شرایط Remote Config و مقادیر شرطی را اصلاح و اضافه کنید. برای مثال، برای افزودن شرط جدید:

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

در همه موارد، باید پس‌از اعمال تغییرات، الگو را به‌طور صریح منتشر کنید.

میاناهای برنامه‌سازی کاربردی پسین Remote Config چندین شرط و عملگر مقایسه ارائه می‌دهند که می‌توانید از آن‌ها برای تغییر رفتار و ظاهر برنامه‌تان استفاده کنید. برای کسب اطلاعات بیشتر درباره شرط‌ها و عملگرهای پشتیبانی‌شده برای این شرط‌ها، به مرجع عبارت شرطی مراجعه کنید.

اعتبارسنجی الگوی 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());
  }
}

این فرایند اعتبارسنجی خطاهایی مانند کلیدهای تکراری برای پارامترها و شرایط، نام‌های شرط نامعتبر یا شرایط غیرموجود، یا etagهای با قالب‌بندی نادرست را بررسی می‌کند. برای مثال، درخواستی که حاوی بیش‌از تعداد مجاز کلیدها (۲۰۰۰) باشد، پیام خطای Param count too large را برمی‌گرداند.

انتشار الگوی Remote Config

پس‌از بازیابی الگو و بازبینی آن با به‌روزرسانی‌هایتان، می‌توانید آن را منتشر کنید. انتشار الگو طبق آنچه در این بخش شرح داده شده است، کل الگوی پیکربندی موجود را با فایل به‌روزشده جایگزین می‌کند و به الگوی فعال جدید شماره نسخه‌ای اختصاص داده می‌شود که یک شماره بزرگ‌تر از الگویی است که جایگزین آن شده است.

درصورت لزوم، می‌توانید از REST API برای عقب‌گرد به نسخه قبلی استفاده کنید. برای کاهش خطر خطا در به‌روزرسانی، می‌توانید قبل‌از انتشار اعتبار سنجی کنید.

Remote Config شخصی‌سازی و شرط در الگوهای بارگیری‌شده گنجانده شده است، بنابراین هنگام تلاش برای انتشار در پروژه‌ای دیگر، مهم است که از محدودیت‌های زیر آگاه باشید:

  • شخصی‌سازی‌ها را نمی‌توان از پروژه‌ای به پروژه دیگر وارد کرد.

    برای مثال، اگر شخصی‌سازی‌ها را در پروژه‌تان فعال کرده باشید و الگویی را بارگیری و ویرایش کنید، می‌توانید آن را در همان پروژه منتشر کنید، اما نمی‌توانید آن را در پروژه دیگری منتشر کنید مگراینکه شخصی‌سازی‌ها را از الگو حذف کنید.

  • شرایط را می‌توان از پروژه‌ای به پروژه دیگر وارد کرد، اما توجه داشته باشید که هرگونه مقدار شرطی خاص (مانند شناسه‌های برنامه یا مخاطبان) باید قبل‌از انتشار در پروژه هدف وجود داشته باشد.

    برای مثال، اگر پارامتر Remote Config دارید که از شرطی استفاده می‌کند که مقدار پلاتفرم iOS را مشخص می‌کند، الگو می‌تواند در پروژه دیگری منتشر شود، زیرا مقادیر پلاتفرم برای هر پروژه‌ای یکسان است. اما اگر حاوی شرطی باشد که به شناسه برنامه یا مخاطب کاربر خاصی متکی باشد که در پروژه هدف وجود ندارد، اعتبارسنجی ناموفق خواهد بود.

  • اگر الگویی که قصد انتشار آن را دارید حاوی شرایطی است که به Google Analytics متکی است، Analytics باید در پروژه هدف فعال باشد.

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

اصلاح Remote Config بااستفاده از REST API

این بخش قابلیت‌های اصلی Remote Config REST API را در https://firebaseremoteconfig.googleapis.com شرح می‌دهد. برای جزئیات کامل، مرجع میانای برنامه‌سازی کاربردی را ببینید.

دریافت کد دسترسی برای اصالت‌سنجی و صدور مجوز درخواست‌های میانای برنامه‌سازی کاربردی

پروژه‌های Firebase از حساب‌های سرویس Google پشتیبانی می‌کنند که می‌توانید از آن‌ها برای فراخوانی میاناهای برنامه‌سازی کاربردی سرور Firebase از سرور برنامه یا محیط مورداعتماد استفاده کنید. اگر کد را به‌صورت محلی توسعه می‌دهید یا برنامه‌تان را در محل مستقر می‌کنید، می‌توانید از اعتبارنامه‌های به‌دست‌آمده بااستفاده از این حساب سرویس برای مجاز کردن درخواست‌های سرور استفاده کنید.

می‌توانید همه حساب‌های سرویس پروژه Firebase خود را در برگه تنظیمات > حساب‌های سرویس مشاهده کنید.

برای اصالت‌سنجی حساب خدمات و صدور مجوز برای آن جهت دسترسی به سرویس‌های Firebase، باید فایل کلید خصوصی را در قالب JSON تولید کنید.

برای ایجاد فایل کلید خصوصی برای حساب سرویس خود:

  1. در کنسول Firebase، به تنظیمات > برگه حساب‌های سرویس بروید.

  2. روی تولید کلید خصوصی جدید کلیک کنید، سپس با کلیک کردن روی تولید کلید تأیید کنید.

  3. فایل JSON حاوی کلید را به‌طور ایمن ذخیره کنید.

هنگام صدور مجوز ازطریق حساب سرویس، دو گزینه برای ارائه اعتبارنامه به برنامه‌تان دارید. می‌توانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید یا می‌توانید مسیر کلید حساب سرویس را به‌طور صریح در کد ارسال کنید. گزینه اول ایمن‌تر است و به‌شدت توصیه می‌شود.

برای تنظیم متغیر محیطی:

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل JSON که حاوی کلید حساب سرویس شما است تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می‌شود، بنابراین اگر جلسه جدیدی باز کردید، متغیر را دوباره تنظیم کنید.

Linux یا macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"

پنجره

با PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"

پس‌از تکمیل مراحل بالا، «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) می‌تواند به‌طور ضمنی اعتبارنامه‌های شما را تعیین کند و به شما اجازه دهد هنگام آزمایش یا اجرا در محیط‌های غیرGoogle از اعتبارنامه‌های حساب سرویس استفاده کنید.

از اعتبارنامه Firebase خود به‌همراه کتابخانه Google Auth برای زبان موردنظرتان استفاده کنید تا کد دسترسی 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

جاوا

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

پس‌از منقضی شدن کد دسترسی، روش بازآوری کد به‌طور خودکار فراخوانی می‌شود تا کد دسترسی به‌روزشده بازیابی شود.

برای مجاز کردن دسترسی به Remote Config، دامنه https://www.googleapis.com/auth/firebase.remoteconfig را درخواست کنید.

تغییر دادن الگوی Remote Config

هنگام کار با الگوهای Remote Config، به‌خاطر داشته باشید که آن‌ها نسخه‌بندی شده‌اند و هر نسخه از زمان ایجاد تا زمانی که آن را با به‌روزرسانی جایگزین کنید، طول عمر محدودی دارد: ۹۰ روز، با محدودیت کلی ۳۰۰ نسخه ذخیره‌شده. برای اطلاعات بیشتر، الگوها و نسخه‌بندی را ببینید.

دریافت الگوی Remote Config فعلی

می‌توانید از میاناهای برنامه‌سازی کاربردی پس‌بخش برای دریافت نسخه فعال فعلی الگوی Remote Config در قالب JSON استفاده کنید.

پارامترها و مقادیر پارامترهایی که به‌طور خاص به‌عنوان متغیر در آزمایش A/B Testing ایجاد شده‌اند در الگوهای صادرشده گنجانده نمی‌شوند.

از فرمان‌های زیر استفاده کنید:

cURL

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

این فرمان پایه‌بار JSON را در یک فایل و سرصفحه‌ها (ازجمله Etag) را در فایلی جداگانه برونداد می‌کند.

درخواست اچ‌تی‌تی‌پی خام

Host: firebaseremoteconfig.googleapis.com

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

این فراخوانی میانای برنامه‌سازی کاربردی JSON زیر را به‌همراه سرصفحه جداگانه‌ای که حاوی ETag است و از آن برای درخواست بعدی استفاده می‌کنید برمی‌گرداند.

اعتبارسنجی الگوی Remote Config

درصورت تمایل، می‌توانید به‌روزرسانی‌هایتان را قبل‌از انتشار اعتبار سنجی کنید. به‌روزرسانی‌های الگو را با افزودن پارامتر نشانی وب ?validate_only=true به درخواست انتشار خود اعتبارسنجی کنید. در پاسخ، کد وضعیت ۲۰۰ و etag به‌روزشده با پسوند -0 به این معنی است که به‌روزرسانی شما باموفقیت اعتبارسنجی شده است. هر پاسخ غیر ۲۰۰ نشان می‌دهد که داده‌های JSON حاوی خطاهایی است که باید قبل‌از انتشار اصلاح کنید.

به‌روزرسانی الگوی Remote Config

پس‌از بازیابی الگو و بازبینی محتوای JSON با به‌روزرسانی‌هایتان، می‌توانید آن را منتشر کنید. انتشار الگو طبق آنچه در این بخش شرح داده شده است، کل الگوی پیکربندی موجود را با فایل به‌روزشده جایگزین می‌کند و به الگوی فعال جدید شماره نسخه‌ای اختصاص داده می‌شود که یک شماره بزرگ‌تر از الگویی است که جایگزین آن شده است.

درصورت لزوم، می‌توانید از REST API برای عقب‌گرد به نسخه قبلی استفاده کنید. برای کاهش خطر خطا در به‌روزرسانی، می‌توانید قبل‌از انتشار اعتبار سنجی کنید.

Remote Config شخصی‌سازی و شرط در الگوهای بارگیری‌شده گنجانده شده است، بنابراین هنگام تلاش برای انتشار در پروژه‌ای دیگر، مهم است که از محدودیت‌های زیر آگاه باشید:

  • شخصی‌سازی‌ها را نمی‌توان از پروژه‌ای به پروژه دیگر وارد کرد.

    برای مثال، اگر شخصی‌سازی‌ها را در پروژه‌تان فعال کرده باشید و الگویی را بارگیری و ویرایش کنید، می‌توانید آن را در همان پروژه منتشر کنید، اما نمی‌توانید آن را در پروژه دیگری منتشر کنید مگراینکه شخصی‌سازی‌ها را از الگو حذف کنید.

  • شرایط را می‌توان از پروژه‌ای به پروژه دیگر وارد کرد، اما توجه داشته باشید که هرگونه مقدار شرطی خاص (مانند شناسه‌های برنامه یا مخاطبان) باید قبل‌از انتشار در پروژه هدف وجود داشته باشد.

    برای مثال، اگر پارامتر Remote Config دارید که از شرطی استفاده می‌کند که مقدار پلاتفرم iOS را مشخص می‌کند، الگو می‌تواند در پروژه دیگری منتشر شود، زیرا مقادیر پلاتفرم برای هر پروژه‌ای یکسان است. اما اگر حاوی شرطی باشد که به شناسه برنامه یا مخاطب کاربر خاصی متکی باشد که در پروژه هدف وجود ندارد، اعتبارسنجی ناموفق خواهد بود.

  • اگر الگویی که قصد انتشار آن را دارید حاوی شرایطی است که به Google Analytics متکی است، Analytics باید در پروژه هدف فعال باشد.

cURL

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، می‌توانید محتوا را بااستفاده از نویسه «@» و سپس نام فایل مشخص کنید.

درخواست اچ‌تی‌تی‌پی خام

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 بعدی ارائه می‌شود.

اصلاح Remote Config شرط

می‌توانید شرایط و مقادیر شرطی Remote Config را به‌صورت برنامه‌نویسی‌شده اصلاح کنید. با 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 نیز برای اهداف کنترل نسخه ارائه می‌شود.

میاناهای برنامه‌سازی کاربردی پسین Remote Config چندین شرط و عملگر مقایسه ارائه می‌دهند که می‌توانید از آن‌ها برای تغییر رفتار و ظاهر برنامه‌تان استفاده کنید. برای کسب اطلاعات بیشتر درباره شرط‌ها و عملگرهای پشتیبانی‌شده برای این شرط‌ها، به مرجع عبارت شرطی مراجعه کنید.

کدهای خطای HTTP

کد وضعیت معنی
۲۰۰ باموفقیت به‌روز شد
400 خطای اعتبارسنجی روی داد. برای مثال، درخواستی که حاوی بیش‌از تعداد مجاز کلیدها (۲۰۰۰) باشد، خطای ۴۰۰ (درخواست بد) را با پیام خطای Param count too large برمی‌گرداند. همچنین، این «کد وضعیت HTTPS» می‌تواند در این دو موقعیت رخ دهد:
  • خطای عدم تطابق نسخه رخ داد زیرا مجموعه مقادیر و شرایط از آخرین باری که مقدار ETag را بازیابی کردید به‌روز شده است. برای حل این مشکل، باید از فرمان GET برای دریافت الگو و مقدار ETag جدید استفاده کنید، الگو را به‌روز کنید، و سپس بااستفاده از آن الگو و مقدار ETag جدید ارسال کنید.
  • فرمان PUT (درخواست الگوی به‌روزرسانی Remote Config) بدون مشخص کردن سرایند If-Match انجام شد.
401 خطای مجوز رخ داد (هیچ کد دسترسی ارائه نشده است یا Firebase Remote Config REST API به پروژه شما در Cloud Developer Console اضافه نشده است)
403 خطای اصالت‌سنجی رخ داد (کد دسترسی اشتباه ارائه شد)
500 یک خطای داخلی رخ داد. اگر این خطا رخ داد، بلیت پشتیبانی Firebase ارسال کنید

کد وضعیت ۲۰۰ یعنی الگوی Remote Config (پارامترها، مقادیر، و شرایط پروژه) به‌روز شده است و اکنون برای برنامه‌هایی که از این پروژه استفاده می‌کنند دردسترس است. کدهای وضعیت دیگر نشان می‌دهند که الگوی Remote Config که قبلاً وجود داشته است هنوز معتبر است.

پس‌از ارسال به‌روزرسانی‌ها برای الگوی خود، به کنسول Firebase بروید تا تأیید کنید تغییراتتان طبق انتظار نشان داده می‌شود. این موضوع بسیار مهم است زیرا ترتیب شرایط بر نحوه ارزیابی آن‌ها تأثیر می‌گذارد (اولین شرطی که true ارزیابی شود اعمال می‌شود).

استفاده از ETag و به‌روزرسانی‌های اجباری

Remote Config REST API از برچسب موجودیت (ETag) برای جلوگیری از شرایط رقابت و به‌روزرسانی‌های هم‌پوشان در منابع استفاده می‌کند. برای کسب اطلاعات بیشتر درباره ETag، ETag - HTTP را ببینید.

برای REST API،‏ Google توصیه می‌کند که ETag ارائه‌شده توسط جدیدترین فرمان GET را ذخیره کنید و از آن مقدار ETag در سرایند درخواست If-Match هنگام صدور فرمان‌های PUT استفاده کنید. اگر فرمان PUT شما منجر به HTTPS Status Code 409 شد، باید فرمان GET جدیدی صادر کنید تا ETag و الگوی جدیدی برای استفاده با فرمان PUT بعدی‌تان دریافت کنید.

می‌توانید با اجبار به‌روزرسانی الگوی Remote Config به‌صورت زیر، ETag و محافظتی را که ارائه می‌دهد دور بزنید: If-Match: *. اما این رویکرد توصیه نمی‌شود زیرا اگر چند مشتری درحال به‌روزرسانی الگوی Remote Config باشند، خطر ازدست رفتن به‌روزرسانی‌های الگوی Remote Config وجود دارد. این نوع تداخل ممکن است با چندین کارخواه که از میانای برنامه‌سازی کاربردی استفاده می‌کنند یا با به‌روزرسانی‌های متداخل از کارخواه‌های میانای برنامه‌سازی کاربردی و کاربران کنسول Firebase رخ دهد.

برای راهنمایی درباره مدیریت نسخه‌های الگوی Remote Config، به الگوها و نسخه‌بندی Remote Config مراجعه کنید.

تغییر دادن Remote Config بااستفاده از Firebase CLI

Firebase CLI به شما امکان می‌دهد الگوهای Remote Config را بررسی، مدیریت، و واگرد کنید، و همچنین آزمایش‌ها و عرضه کردن‌های Remote Config را مستقیماً از خط فرمان فهرست، بررسی، و حذف کنید.

پیش‌نیازها و راه‌اندازی

  1. Firebase CLI را نصب کنید یا به جدیدترین نسخه آن به‌روزرسانی کنید.

  2. ورود به سیستم Firebase:

    firebase login
  3. پروژه فعال خود را تنظیم کنید یا --project PROJECT_ID را با هر فرمان مشخص کنید:

    firebase use PROJECT_ID

مطمئن شوید که حساب یا حساب سرویس شما اجازه‌های IAM لازم را دارد:

خلاصه فرمان CLI

فرمان شرح
firebase remoteconfig:versions:list Remote Config نسخه اخیر الگو را فهرست می‌کند.
firebase remoteconfig:get الگوی Remote Config را دریافت می‌کند (به‌صورت اختیاری در فایل می‌نویسد).
firebase remoteconfig:rollback الگوی Remote Config را به نسخه قبلی برمی‌گرداند.
firebase remoteconfig:experiments:list همه آزمایش‌های Remote Config را در پروژه فهرست می‌کند.
firebase remoteconfig:experiments:get جزئیات آزمایش Remote Config خاصی را دریافت می‌کند.
firebase remoteconfig:experiments:delete آزمایش Remote Config خاصی را حذف می‌کند.
firebase remoteconfig:rollouts:list همه عرضه Remote Config در پروژه را فهرست می‌کند.
firebase remoteconfig:rollouts:get جزئیات عرضه Remote Config خاصی را دریافت می‌کند.
firebase remoteconfig:rollouts:delete عرضه Remote Config خاصی را حذف می‌کند.

اصلاح کردن الگوها و نسخه‌های Remote Config

از فرمان‌های زیر برای بازرسی، بارگیری، و بازگرداندن الگوهای Remote Config و سابقه نسخه آن‌ها استفاده کنید:

فهرست کردن نسخه‌های الگو

به‌طور پیش‌فرض، ۱۰ نسخه اخیر الگوی Remote Config را فهرست می‌کند، ازجمله شماره نسخه، زمان به‌روزرسانی، منبع به‌روزرسانی، نوع به‌روزرسانی، و updateUser.

firebase remoteconfig:versions:list [--limit NUMBER_OF_VERSIONS]
  • ‫--limit NUMBER_OF_VERSIONS: حداکثر تعداد نسخه‌هایی که باید برگردانده شود. 0 را برای برگرداندن همه نسخه‌های موجود (تا حد ۳۰۰ نسخه ذخیره‌شده) مشخص کنید.

مثال‌ها:

  • فهرست کردن ۱۰ نسخه اخیر:

    firebase remoteconfig:versions:list
  • فهرست کردن همه نسخه‌های دردسترس:

    firebase remoteconfig:versions:list --limit 0
  • ۵ نسخه اخیر را فهرست کنید:

    firebase remoteconfig:versions:list --limit 5

دریافت الگو

الگوی Remote Config را دریافت می‌کند و گروه‌های پارامتر، پارامترها، نام‌های شرط، و نسخه را برونداد می‌کند. به‌طور پیش‌فرض، آخرین نسخه فعال را بازیابی می‌کند و خلاصه‌ای قالب‌بندی‌شده را در پایانه چاپ می‌کند.

firebase remoteconfig:get [-v, --version_number VERSION_NUMBER] [-o, --output FILENAME]
  • -v, --version_number VERSION_NUMBER: شماره نسخه الگو برای بازیابی. اگر حذف شود، به‌طور پیش‌فرض به جدیدترین نسخه می‌رود.
  • -o, --output FILENAME: محموله JSON الگو را به‌جای چاپ در خروجی استاندارد، مستقیماً در مسیر مشخص‌شده می‌نویسد.

مثال‌ها:

  • نمایش الگوی فعال کنونی در پایانه:

    firebase remoteconfig:get
  • الگوی فعال کنونی را در فایل JSON بارگیری کنید:

    firebase remoteconfig:get -o remote_config_template.json
  • بارگیری نسخه تاریخی خاص (برای مثال، نسخه ۱۲) در یک فایل:

    firebase remoteconfig:get -v 12 -o remote_config_v12.json

بازگرداندن الگو

الگوی فعال Remote Config را به نسخه قبلی برمی‌گرداند. این کار نسخه فعال جدیدی ایجاد می‌کند که محتوای آن با نسخه هدف یکسان است.

firebase remoteconfig:rollback [-v, --version_number VERSION_NUMBER] [--force]
  • ‫-v, --version_number VERSION_NUMBER: شماره نسخه هدف برای بازگردانی. اگر حذف شود، به‌طور پیش‌فرض به نسخه بلافاصله قبلی (نسخه فعلی منهای ۱) برمی‌گردد.
  • --force: بازگرداندن را فوراً و بدون درخواست تأیید تعاملی (بله/نه) انجام می‌دهد. برای خط لوله‌های CI/CD و دستورگان‌های خودکارسازی‌شده مفید است.

مثال‌ها:

  • برگشتن به نسخه قبلی با تأیید تعاملی:

    firebase remoteconfig:rollback
  • برگشتن به نسخه ۸ بدون درخواست:

    firebase remoteconfig:rollback -v 8 --force

تغییر دادن A/B Testing آزمایش

از فرمان‌های زیر برای فهرست کردن، بازرسی، و حذف کردن Remote Config آزمایش‌های A/B Testing مستقیماً با میانای خط فرمان استفاده کنید:

فهرست کردن آزمایش‌ها

همه آزمایش‌های Remote Config را برای پروژه فهرست می‌کند، با فیلتر کردن و صفحه‌بندی اختیاری.

firebase remoteconfig:experiments:list [--filter EXPRESSION] [--pageSize NUMBER] [--pageToken TOKEN]
  • --filter EXPRESSION: عبارت فیلتر برای اعمال به فهرست آزمایش.
  • --pageSize NUMBER: تعداد آزمایش‌هایی که باید در هر صفحه برگردانده شود (پیش‌فرض ۱۰ است).
  • --pageToken TOKEN: کد برای جابه‌جایی صفحه هنگام بازیابی نتایج صفحه‌بندی‌شده.

مثال:

firebase remoteconfig:experiments:list

دریافت جزئیات آزمایش

جزئیات کامل آزمایش Remote Config مشخص‌شده را دریافت می‌کند.

firebase remoteconfig:experiments:get EXPERIMENT_ID

مثال:

firebase remoteconfig:experiments:get exp_promo_discount_2026

حذف کردن آزمایش

آزمایش Remote Config مشخص‌شده را حذف می‌کند.

firebase remoteconfig:experiments:delete EXPERIMENT_ID

مثال:

firebase remoteconfig:experiments:delete exp_promo_discount_2026

اصلاح کردن Remote Config عرضه

از فرمان‌های زیر برای فهرست کردن، بازرسی، و حذف مستقیم Remote Config عرضه با CLI استفاده کنید:

فهرست کردن عرضه‌ها

همه عرضه Remote Config را برای پروژه با فیلتر کردن اختیاری و صفحه‌بندی فهرست می‌کند.

firebase remoteconfig:rollouts:list [--filter EXPRESSION] [--pageSize NUMBER] [--pageToken TOKEN]
  • --filter EXPRESSION: عبارت فیلتر برای اعمال به فهرست عرضه.
  • --pageSize NUMBER: تعداد عرضه‌هایی که در هر صفحه برگردانده می‌شود (پیش‌فرض ۱۰ است).
  • --pageToken TOKEN: کد برای جابه‌جایی صفحه هنگام بازیابی نتایج صفحه‌بندی‌شده.

مثال:

firebase remoteconfig:rollouts:list

دریافت جزئیات عرضه

جزئیات کامل را برای عرضه Remote Config مشخص‌شده دریافت می‌کند.

firebase remoteconfig:rollouts:get ROLLOUT_ID

مثال:

firebase remoteconfig:rollouts:get rollout_new_checkout_flow

حذف عرضه

عرضه Remote Config مشخص‌شده را حذف می‌کند.

firebase remoteconfig:rollouts:delete ROLLOUT_ID

مثال:

firebase remoteconfig:rollouts:delete rollout_new_checkout_flow

برای اطلاعات کلی بیشتر درباره فرمان‌های Firebase CLI، به مرجع Firebase CLI مراجعه کنید.