تعديل "التكوين البعيد" برمجياً

يصف هذا المستند كيف يمكنك قراءة وتعديل مجموعة المعلمات ذات تنسيق JSON والظروف المعروفة باسم قالب التكوين البعيد . يتيح لك ذلك إجراء تغييرات على القالب على الواجهة الخلفية التي يمكن لتطبيق العميل جلبها باستخدام مكتبة العميل.

باستخدام Remote Config REST API أو Admin SDKs الموضحة في هذا الدليل ، يمكنك تجاوز إدارة القالب في وحدة تحكم Firebase لدمج تغييرات التكوين عن بُعد مباشرةً في عملياتك الخاصة. على سبيل المثال ، باستخدام واجهات برمجة التطبيقات الخلفية للتكوين البعيد ، يمكنك:

• جدولة تحديثات Remote Config . باستخدام استدعاءات API جنبًا إلى جنب مع وظيفة cron ، يمكنك تغيير قيم Remote Config وفقًا لجدول منتظم.
• قيم تكوين استيراد الدُفعات من أجل الانتقال بكفاءة من نظامك الخاص إلى Firebase Remote Config.

• استخدم Remote Config with Cloud Functions لـ Firebase ، وتغيير القيم في تطبيقك بناءً على الأحداث التي تحدث من جانب الخادم. على سبيل المثال ، يمكنك استخدام Remote Config للترويج لميزة جديدة في تطبيقك ، ثم إيقاف تشغيل هذا الترويج تلقائيًا بمجرد اكتشاف عدد كافٍ من الأشخاص الذين تفاعلوا مع الميزة الجديدة.

  

تصف الأقسام التالية من هذا الدليل العمليات التي يمكنك القيام بها باستخدام واجهات برمجة التطبيقات الخلفية للتكوين البعيد. لمراجعة بعض التعليمات البرمجية التي تؤدي هذه المهام عبر واجهة برمجة تطبيقات REST ، راجع أحد نماذج التطبيقات التالية:

• Firebase Remote Config REST API Java Quickstart
• Firebase Remote Config REST API Node.js Quickstart
• Firebase Remote Config REST API Python Quickstart

قم بتعديل Remote Config باستخدام Firebase Admin SDK

Admin SDK هي مجموعة من مكتبات الخوادم التي تتيح لك التفاعل مع Firebase من البيئات ذات الامتيازات. بالإضافة إلى إجراء تحديثات لـ Remote Config ، فإن Admin SDK يتيح إنشاء رموز مصادقة Firebase والتحقق منها ، والقراءة والكتابة من قاعدة بيانات Realtime ، وما إلى ذلك. لمعرفة المزيد حول المتطلبات الأساسية لـ Admin SDK والإعداد ، راجع إضافة Firebase Admin SDK إلى الخادم الخاص بك .

في تدفق "التكوين البعيد" النموذجي ، قد تحصل على القالب الحالي ، وتعديل بعض المعلمات أو مجموعات وشروط المعلمات ، والتحقق من صحة القالب ، ثم نشره. قبل إجراء استدعاءات واجهة برمجة التطبيقات هذه ، يجب عليك تفويض الطلبات من SDK.

تهيئة SDK وتفويض طلبات واجهة برمجة التطبيقات

عند تهيئة Admin SDK بدون معلمات ، تستخدم SDK بيانات الاعتماد الافتراضية لتطبيق Google وتقرأ الخيارات من متغير البيئة FIREBASE_CONFIG . إذا بدأ محتوى المتغير FIREBASE_CONFIG بـ { فسيتم تحليله ككائن JSON. بخلاف ذلك ، تفترض SDK أن السلسلة هي اسم ملف JSON الذي يحتوي على الخيارات.

على سبيل المثال:

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 إصدار مخزن. راجع القوالب وتعيين الإصدار لمزيد من المعلومات.

يمكنك استخدام واجهات برمجة التطبيقات الخلفية للحصول على الإصدار النشط الحالي من قالب التكوين عن بُعد بتنسيق JSON.

لا يتم تضمين المعلمات وقيم المعلمات التي تم إنشاؤها على وجه التحديد كمتغيرات في تجربة اختبار A / B في القوالب المصدرة.

للحصول على النموذج:

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

تعديل معلمات التكوين البعيد

يمكنك تعديل وإضافة معلمات التكوين البعيد ومجموعات المعلمات برمجيًا. على سبيل المثال ، إلى مجموعة معلمات موجودة تسمى "new_menu" ، يمكنك إضافة معلمة للتحكم في عرض المعلومات الموسمية:

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

تسمح لك واجهة برمجة التطبيقات بإنشاء مجموعات معلمات ومعلمات جديدة ، أو تعديل القيم الافتراضية ، والقيم الشرطية ، والأوصاف. في جميع الحالات ، يجب عليك نشر القالب بشكل صريح بعد إجراء التعديلات.

تعديل شروط Remote Config

يمكنك تعديل وإضافة شروط "التكوين البعيد" والقيم الشرطية برمجيًا. على سبيل المثال ، لإضافة شرط جديد:

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

اختياريًا ، يمكنك التحقق من صحة تحديثاتك قبل نشرها ، كما هو موضح:

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 للعودة إلى الإصدار السابق . لتقليل مخاطر الأخطاء في التحديث ، يمكنك التحقق من الصحة قبل النشر .

تم تضمين تخصيصات وشروط Remote Config في القوالب التي تم تنزيلها ، لذلك من المهم أن تكون على دراية بالقيود التالية عند محاولة النشر إلى مشروع مختلف:

• لا يمكن استيراد التخصيصات من مشروع إلى آخر.

  على سبيل المثال ، إذا قمت بتمكين التخصيصات في مشروعك وقمت بتنزيل قالب وتحريره ، فيمكنك نشره على نفس المشروع ، ولكن لا يمكنك نشره في مشروع آخر ما لم تحذف التخصيصات من القالب.

• يمكن استيراد الشروط من مشروع إلى مشروع ، ولكن لاحظ أن أي قيم شرطية محددة (مثل معرفات التطبيق أو الجماهير) ، يجب أن تكون موجودة في المشروع الهدف قبل النشر.

  على سبيل المثال ، إذا كان لديك معلمة Remote Config تستخدم شرطًا يحدد قيمة النظام الأساسي لنظام iOS ، فيمكن نشر القالب إلى مشروع آخر ، لأن قيم النظام الأساسي هي نفسها لأي مشروع. ومع ذلك ، إذا كان يحتوي على شرط يعتمد على معرف تطبيق معين أو جمهور مستخدم غير موجود في المشروع المستهدف ، فسيفشل التحقق من الصحة.

• إذا كان النموذج الذي تخطط لنشره يحتوي على شروط تعتمد على Google Analytics ، فيجب تمكين Analytics في المشروع المستهدف.

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 على https://firebaseremoteconfig.googleapis.com . للحصول على التفاصيل الكاملة ، راجع مرجع API .

احصل على رمز وصول لمصادقة طلبات واجهة برمجة التطبيقات وتفويضها

تدعم مشاريع Firebase حسابات خدمة Google ، والتي يمكنك استخدامها للاتصال بواجهات برمجة تطبيقات خادم Firebase من خادم التطبيق أو البيئة الموثوقة. إذا كنت تقوم بتطوير التعليمات البرمجية محليًا أو نشر تطبيقك محليًا ، فيمكنك استخدام بيانات الاعتماد التي تم الحصول عليها عبر حساب الخدمة هذا لتفويض طلبات الخادم.

لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase ، يجب عليك إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة الخاص بك:

1. في وحدة تحكم Firebase ، افتح الإعدادات> حسابات الخدمة .

2. انقر فوق إنشاء مفتاح خاص جديد ، ثم قم بالتأكيد بالنقر فوق إنشاء مفتاح .

3. قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

عند التفويض عبر حساب خدمة ، لديك خياران لتقديم بيانات الاعتماد لتطبيقك. يمكنك إما تعيين متغير بيئة GOOGLE_APPLICATION_CREDENTIALS ، أو يمكنك صراحة تمرير المسار إلى مفتاح حساب الخدمة في التعليمات البرمجية. الخيار الأول أكثر أمانًا ويوصى به بشدة.

لتعيين متغير البيئة:

اضبط متغير البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف ملف JSON الذي يحتوي على مفتاح حساب الخدمة. ينطبق هذا المتغير فقط على جلسة shell الحالية ، لذلك إذا فتحت جلسة جديدة ، فقم بتعيين المتغير مرة أخرى.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

بعد الانتهاء من الخطوات المذكورة أعلاه ، يمكن لبيانات اعتماد التطبيق الافتراضية (ADC) تحديد بيانات الاعتماد الخاصة بك بشكل ضمني ، مما يسمح لك باستخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لـ Google.

استخدم بيانات اعتماد Firebase مع مكتبة مصادقة Google للغتك المفضلة لاسترداد رمز وصول OAuth 2.0 قصير العمر:

 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);
      });
}
index.js

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
configure.py

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

بعد انتهاء صلاحية رمز الوصول الخاص بك ، يتم استدعاء طريقة تحديث الرمز المميز تلقائيًا لاسترداد رمز وصول محدث.

لتفويض الوصول إلى Remote Config ، اطلب النطاق https://www.googleapis.com/auth/firebase.remoteconfig .

قم بتعديل قالب Remote Config

عند العمل باستخدام قوالب التكوين عن بُعد ، ضع في اعتبارك أنه تم إصدارها ، وأن كل إصدار له عمر محدود من وقت إنشائه حتى وقت استبداله بالتحديث: 90 يومًا ، بحد إجمالي 300 إصدار مخزن. راجع القوالب وتعيين الإصدار لمزيد من المعلومات.

احصل على قالب التكوين عن بعد الحالي

يمكنك استخدام واجهات برمجة التطبيقات الخلفية للحصول على الإصدار النشط الحالي من قالب التكوين عن بُعد بتنسيق JSON.

لا يتم تضمين المعلمات وقيم المعلمات التي تم إنشاؤها على وجه التحديد كمتغيرات في تجربة اختبار A / B في القوالب المصدرة.

استخدم الأوامر التالية:

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

Host: firebaseremoteconfig.googleapis.com

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

تحقق من صحة قالب Remote Config

اختياريًا ، يمكنك التحقق من صحة التحديثات قبل نشرها. تحقق من صحة تحديثات القالب من خلال إلحاق طلب النشر بمعامل URL ?validate_only=true . في الاستجابة ، يشير رمز الحالة 200 و etag المحدث مع اللاحقة -0 إلى أنه تم التحقق من صحة التحديث بنجاح. تشير أي إجابة بخلاف 200 إلى أن بيانات JSON تحتوي على أخطاء يجب تصحيحها قبل النشر.

قم بتحديث قالب Remote Config

بعد استرداد نموذج ومراجعة محتوى JSON بالتحديثات التي تريدها ، يمكنك بعد ذلك نشره. يؤدي نشر قالب كما هو موضح في هذا القسم إلى استبدال قالب التكوين الحالي بالكامل بالملف المحدث ، ويتم تعيين رقم إصدار أكبر من القالب الذي تم استبداله للقالب النشط الجديد.

إذا لزم الأمر ، يمكنك استخدام واجهة برمجة تطبيقات REST للعودة إلى الإصدار السابق . لتقليل مخاطر الأخطاء في التحديث ، يمكنك التحقق من الصحة قبل النشر .

تم تضمين تخصيصات وشروط Remote Config في القوالب التي تم تنزيلها ، لذلك من المهم أن تكون على دراية بالقيود التالية عند محاولة النشر إلى مشروع مختلف:

• لا يمكن استيراد التخصيصات من مشروع إلى آخر.

  على سبيل المثال ، إذا قمت بتمكين التخصيصات في مشروعك وقمت بتنزيل قالب وتحريره ، فيمكنك نشره على نفس المشروع ، ولكن لا يمكنك نشره في مشروع آخر ما لم تحذف التخصيصات من القالب.

• يمكن استيراد الشروط من مشروع إلى مشروع ، ولكن لاحظ أن أي قيم شرطية محددة (مثل معرفات التطبيق أو الجماهير) ، يجب أن تكون موجودة في المشروع الهدف قبل النشر.

  على سبيل المثال ، إذا كان لديك معلمة Remote Config تستخدم شرطًا يحدد قيمة النظام الأساسي لنظام iOS ، فيمكن نشر القالب إلى مشروع آخر ، لأن قيم النظام الأساسي هي نفسها لأي مشروع. ومع ذلك ، إذا كان يحتوي على شرط يعتمد على معرف تطبيق معين أو جمهور مستخدم غير موجود في المشروع المستهدف ، فسيفشل التحقق من الصحة.

• إذا كان النموذج الذي تخطط لنشره يحتوي على شروط تعتمد على Google Analytics ، فيجب تمكين Analytics في المشروع المستهدف.

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

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

تعديل شروط Remote Config

يمكنك تعديل شروط "التكوين البعيد" والقيم الشرطية برمجيًا. باستخدام واجهة برمجة تطبيقات REST ، يجب عليك تحرير القالب مباشرةً لتعديل الشروط قبل نشر القالب.

{
  "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 أيضًا لأغراض التحكم في الإصدار.

توفر واجهات برمجة التطبيقات الخلفية للتكوين البعيد العديد من الشروط وعوامل المقارنة التي يمكنك استخدامها لتغيير سلوك ومظهر تطبيقك. لمعرفة المزيد حول الشروط والعوامل المدعومة لهذه الشروط ، راجع مرجع التعبير الشرطي .

رموز خطأ HTTP

يعني رمز الحالة 200 أنه تم تحديث نموذج Remote Config (المعلمات والقيم والشروط الخاصة بالمشروع) وهو متاح الآن للتطبيقات التي تستخدم هذا المشروع. تشير رموز الحالة الأخرى إلى أن نموذج Remote Config الموجود مسبقًا لا يزال ساريًا.

بعد إرسال التحديثات إلى القالب الخاص بك ، انتقل إلى وحدة تحكم Firebase للتحقق من ظهور التغييرات على النحو المتوقع. هذا أمر بالغ الأهمية لأن ترتيب الشروط يؤثر على كيفية تقييمها (الشرط الأول الذي يقيم true يسري مفعوله).

استخدام ETag والتحديثات المفروضة

تستخدم Remote Config REST API علامة كيان (ETag) لمنع ظروف السباق وتداخل التحديثات على الموارد. لمعرفة المزيد حول ETag ، راجع ETag - HTTP .

بالنسبة لواجهة برمجة تطبيقات REST ، توصي Google بتخزين ETag الذي تم توفيره بواسطة أحدث أمر GET ، واستخدام قيمة ETag هذه في عنوان طلب If-Match عند إصدار أوامر PUT . إذا نتج عن أمر PUT رمز حالة HTTPS 409 ، فيجب عليك إصدار أمر GET جديد للحصول على ETag ونموذج جديد لاستخدامهما مع أمر PUT التالي.

يمكنك التحايل على ETag ، والحماية التي توفرها ، عن طريق إجبار قالب التكوين عن بُعد على التحديث على النحو التالي: If-Match: * ومع ذلك ، لا يُنصح بهذا الأسلوب لأنه قد يتسبب في فقدان تحديثات لـ Remote Config. إذا كان هناك العديد من العملاء يقومون بتحديث قالب Remote Config. قد يحدث هذا النوع من التعارض مع العديد من العملاء الذين يستخدمون واجهة برمجة التطبيقات ، أو مع التحديثات المتضاربة من عملاء واجهة برمجة التطبيقات ومستخدمي وحدة تحكم Firebase.

للحصول على إرشادات حول إدارة إصدارات قوالب التكوين عن بُعد ، راجع قوالب التكوين عن بُعد وتعيين الإصدار .