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

تنظیم پیکربندی از راه دور به صورت برنامه ای

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

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

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

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

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

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

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

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

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

هنگامی که شما مقداردهی اولیه SDK محیط مدیریت بدون پارامتر، از SDK با استفاده از گوگل نرم افزار پیش فرض مدارک و بار خوانده شده گزینه از 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 را منتشر کنید

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

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

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

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

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

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

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

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

  1. در فایربیس کنسول، تنظیمات> حساب خدمات .

  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"

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

استفاده از اعتبار فایربیس خود را همراه با کتابخانه تایید گوگل برای زبان مورد نظر خود را برای بازیابی یک 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();
}

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

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

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

پس از بازیابی یک الگو و اصلاح محتوای 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 فرمان.

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

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

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

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

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

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

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

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

برای راهنمایی در مدیریت از راه دور نسخه های قالب پیکربندی، و قالب پیکربندی از راه دور و نسخه .