Remote Config را با برنامه تغییر دهید

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

با استفاده از Remote Config REST API یا Admin SDK های توضیح داده شده در این راهنما، می توانید مدیریت الگو را در کنسول Firebase دور بزنید تا مستقیماً تغییرات Remote Config را در فرآیندهای خود ادغام کنید. به عنوان مثال، با Remote Config Backend API، می توانید:

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

    نموداری که باطن Remote Config را در تعامل با ابزارها و سرورهای سفارشی نشان می دهد

بخش‌های زیر از این راهنما، عملیات‌هایی را که می‌توانید با Remote Config Backend API انجام دهید، شرح می‌دهد. برای بررسی کدهایی که این وظایف را از طریق REST API انجام می‌دهند، یکی از این برنامه‌های نمونه را ببینید:

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

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

در یک جریان پیکربندی از راه دور معمولی، می‌توانید الگوی فعلی را دریافت کنید، برخی از پارامترها یا گروه‌ها و شرایط پارامترها را تغییر دهید، الگو را اعتبارسنجی کنید و سپس آن را منتشر کنید. قبل از برقراری آن تماس‌های API، باید درخواست‌ها را از SDK تأیید کنید.

SDK را راه اندازی کنید و درخواست های API را مجاز کنید

زمانی که Admin SDK را بدون هیچ پارامتری مقداردهی اولیه می‌کنید، 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);

الگوی پیکربندی از راه دور فعلی را دریافت کنید

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

برای دریافت نسخه فعال فعلی قالب Remote Config در قالب JSON، می‌توانید از APIهای Backend استفاده کنید. برای دریافت قالب:

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

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 Backend API شرایط و عملگرهای مقایسه ای را ارائه می دهد که می توانید از آنها برای تغییر رفتار و ظاهر برنامه خود استفاده کنید. برای کسب اطلاعات بیشتر در مورد شرایط و عملگرهای پشتیبانی شده برای این شرایط، به مرجع عبارت شرطی مراجعه کنید.

الگوی 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 است.

قالب Remote Config را منتشر کنید

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

در صورت لزوم، می‌توانید از 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());
  }
}

تنظیمات Remote را با استفاده از REST API تغییر دهید

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

برای احراز هویت و تأیید درخواست‌های API یک نشانه دسترسی دریافت کنید

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

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

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

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

  2. روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.

  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"

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

برای بازیابی رمز دسترسی کوتاه مدت OAuth 2.0، از اعتبارنامه Firebase خود به همراه کتابخانه Google Auth برای زبان دلخواه خود استفاده کنید:

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

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

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

قالب Remote Config را تغییر دهید

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

الگوی پیکربندی از راه دور فعلی را دریافت کنید

برای دریافت نسخه فعال فعلی قالب Remote Config در قالب JSON، می‌توانید از APIهای Backend استفاده کنید. از دستورات زیر استفاده کنید:

حلقه

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

این دستور payload 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 است که برای درخواست بعدی استفاده می‌کنید، برمی‌گرداند.

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

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

قالب Remote Config را به روز کنید

پس از بازیابی یک الگو و اصلاح محتوای 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 بعدی ارائه می شود.

شرایط پیکربندی از راه دور را تغییر دهید

شما می توانید شرایط 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 Backend API شرایط و عملگرهای مقایسه ای را ارائه می دهد که می توانید از آنها برای تغییر رفتار و ظاهر برنامه خود استفاده کنید. برای کسب اطلاعات بیشتر در مورد شرایط و عملگرهای پشتیبانی شده برای این شرایط، به مرجع عبارت شرطی مراجعه کنید.

کدهای خطای HTTP

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

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

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

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

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

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

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

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