نماذج "الإعداد عن بُعد" وتحديد الإصدارات

نماذج "الإعداد عن بُعد" هي مجموعات من المَعلمات والشروط بتنسيق JSON التي أنشأتها لمشروعك على Firebase. يمكنك إنشاء نماذج العميل، التي يجلب تطبيقك القيم منها، ونماذج الخادم التي يمكن لعملاء الخادم جلب القيم منها.

يمكنك تعديل النموذج وإدارته باستخدام وحدة تحكم Firebase التي تعرض محتوى النموذج بتنسيق رسومي في علامتَي التبويب المعلَمات والشروط. يمكنك أيضًا استخدام REST API وحزمة تطوير البرامج (SDK) للمشرف أو واجهة سطر الأوامر في Firebase لتعديل نموذج العميل وإدارته.

إليك مثال على ملف نموذج العميل:

      {
        "conditions": [
          {
            "name": "ios",
            "expression": "device.os == 'ios'"
          }
        ],
        "parameters": {
          "welcome_message": {
            "defaultValue": {
              "value": "Welcome to this sample app"
            },
            "conditionalValues": {
              "ios": {
                "value": "Welcome to this sample iOS app"
              }
            }
          },
          "welcome_message_caps": {
            "defaultValue": {
              "value": "false"
            }
          },
          "header_text": {
            "defaultValue": {
              "useInAppDefault": true
            }
          }
        },
        "version": {
          "versionNumber": "28",
          "updateTime": "2020-05-14T18:39:38.994Z",
          "updateUser": {
            "email": "user@google.com"
          },
          "updateOrigin": "CONSOLE",
          "updateType": "INCREMENTAL_UPDATE"
        }
      }

وفي ما يلي مثال على ملف نموذج الخادم:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

يمكنك تنفيذ مهام إدارة الإصدارات التالية باستخدام "وحدة تحكُّم Firebase":

• سرد جميع إصدارات النماذج المخزنة
• استرداد نسخة معينة
• العودة إلى إصدار عميل محدّد
• يمكنك حذف نماذج "الإعداد عن بُعد" من صفحة سجلّ التغييرات.

إذا كنت تدير نماذج العملاء، يمكنك أيضًا إدراج النماذج واسترداد النماذج والرجوع إلى الإصدار السابق من النماذج باستخدام واجهة سطر الأوامر في Firebase وواجهات برمجة تطبيقات الواجهة الخلفية لميزة "الإعداد عن بُعد".

هناك حد إجمالي يبلغ 300 نسخة مخزّنة منذ الإنشاء لكل نوع نموذج (300 نموذج عميل و300 نموذج خادم)، ويشمل ذلك أرقام الإصدارات المخزَّنة للنماذج المحذوفة. وإذا نشرت أكثر من 300 إصدار نموذج لكل نوع نموذج خلال فترة إنشاء المشروع، سيتم حذف أقدم النُسخ، مع الحفاظ على 300 إصدار من هذا النوع كحد أقصى.

وفي كل مرة تعدِّل فيها المَعلمات، تنشئ ميزة "الإعداد عن بُعد" نموذجًا جديدًا لميزة "الإعداد عن بُعد" بإصدارات جديدة وتخزِّن النموذج السابق كإصدار يمكنك استرداده أو الرجوع إليه حسب الحاجة. تتم زيادة أرقام الإصدارات بالتسلسل من القيمة الأولية التي تم تخزينها بواسطة ميزة "الإعداد عن بُعد". تشتمل جميع النماذج على حقل version على النحو المعروض، ويحتوي على بيانات وصفية حول الإصدار المحدّد.

باستخدام "وحدة تحكُّم Firebase" أو واجهة سطر الأوامر في Firebase أو واجهات برمجة التطبيقات للخلفية في ميزة "الإعداد عن بُعد"، يمكنك تنفيذ مهام إدارة الإصدارات التالية:

• سرد جميع إصدارات النماذج المخزنة
• استرداد نسخة معينة
• العودة إلى إصدار محدَّد

ويمكنك حذف نماذج "الإعداد عن بُعد" حسب الحاجة من صفحة سجلّ التغييرات في وحدة تحكُّم "الإعداد عن بُعد". هناك حد إجمالي يبلغ 300 نسخة مخزّنة منذ الإنشاء، بما في ذلك أرقام الإصدارات المخزنة للنماذج المحذوفة. إذا نشرت أكثر من 300 إصدار نموذج خلال فترة إنشاء المشروع، سيتم حذف أقدم الإصدارات، مع الحفاظ على 300 إصدار كحد أقصى.

إدارة إصدارات نماذج "الإعداد عن بُعد"

يوضّح هذا القسم كيفية إدارة إصدارات نموذج "الإعداد عن بُعد". لمزيد من التفاصيل حول كيفية إنشاء النماذج وتعديلها وحفظها آليًا، يُرجى الاطّلاع على تعديل ميزة "الإعداد عن بُعد" آليًا.

إدراج جميع الإصدارات المخزَّنة من نموذج "الإعداد عن بُعد"

يمكنك استرداد قائمة بجميع الإصدارات المخزنة من نموذج "الإعداد عن بُعد". على سبيل المثال:

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

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

firebase remoteconfig:versions:list

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

{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]

استرداد نسخة معيّنة من نموذج "الإعداد عن بُعد"

يمكنك استرداد أي إصدار محدد مخزّن من نموذج "الإعداد عن بُعد". على سبيل المثال:

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

firebase remoteconfig:get -v VERSION_NUMBER

العودة إلى إصدار محدَّد مخزّن من نموذج "الإعداد عن بُعد"

يمكنك العودة إلى أي إصدار مخزن من القالب. على سبيل المثال:

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

firebase remoteconfig:rollback -v VERSION_NUMBER

تجدر الإشارة إلى أنّ عملية العودة إلى الإصدارات السابقة هذه تنشئ إصدارًا جديدًا مرقّمًا بشكل فعّال. على سبيل المثال، يؤدي الرجوع من الإصدار 10 إلى الإصدار 6 إلى إنشاء نسخة جديدة من الإصدار 6 بشكل فعال تختلف عن الإصدار الأصلي فقط في أن رقم الإصدار هو 11. ولا يزال الإصدار 6 الأصلي مخزّنًا، بافتراض أنه لم يبلغ انتهاء صلاحيته، بينما سيصبح الإصدار 11 النموذج النشط.

حذف نموذج لميزة "الإعداد عن بُعد"

يمكنك حذف نماذج "الإعداد عن بُعد" من "وحدة تحكُّم Firebase". لحذف نموذج "الإعداد عن بُعد":

1. من صفحة المَعلمات في ميزة "الإعداد عن بُعد"، انقر على history سجلّ التغييرات.

2. انتقِل إلى النموذج الذي تريد حذفه، وانقر على more_vertالمزيد، ثم على حذف.

3. عندما يُطلب منك تأكيد الحذف، انقر على حذف.

تنزيل نماذج "الإعداد عن بُعد" ونشرها

يمكنك تنزيل نماذج "الإعداد عن بُعد" ونشرها لدمجها في أنظمة التحكّم في المصدر وإنشاء أنظمة التشغيل وتعديلات الإعدادات تلقائيًا ومزامنة المعلمات والقيم على مستوى مشاريع متعددة.

يمكنك تنزيل نموذج "الإعداد عن بُعد" النشِط حاليًا بشكل آلي أو من "وحدة تحكُّم Firebase". يمكنك بعد ذلك تحديث ملف JSON الذي تم تصديره ونشره في المشروع نفسه أو نشره في مشروع جديد أو حالي.

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

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

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

لتصدير نماذج "الإعداد عن بُعد" واستيرادها:

1. نزِّل النموذج الحالي لميزة "الإعداد عن بُعد".
2. التحقّق من صحة نموذج "الإعداد عن بُعد"
3. نشر نموذج "الإعداد عن بُعد".

تنزيل النموذج الحالي لميزة "الإعداد عن بُعد"

يمكنك تنزيل نموذج "الإعداد عن بُعد" الحالي والنشط تلقائيًا أو باستخدام "وحدة تحكّم Firebase".

استخدِم الأوامر التالية لتنزيل نموذج "الإعداد عن بُعد" النشط بتنسيق JSON:

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

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

firebase remoteconfig:get -o filename

التحقّق من صحة نموذج "الإعداد عن بُعد"

يمكنك التحقّق من صحة تعديلات النماذج قبل نشرها باستخدام حزمة تطوير البرامج (SDK) لمشرف Firebase أو REST API. يتم أيضًا التحقّق من صحة النماذج عند محاولة النشر من خلال واجهة سطر الأوامر في Firebase أو وحدة تحكُّم Firebase.

تتحقّق عملية التحقّق من صحة النموذج من عدم وجود أخطاء، مثل المفاتيح المكرّرة للمَعلمات والشروط أو أسماء الشروط غير الصالحة أو الشروط غير المتوفّرة أو العلامات ETag غير الصحيحة. على سبيل المثال، سيعرض الطلب الذي يحتوي على أكثر من عدد المفاتيح المسموح به 2000 رسالة الخطأ Param count too large.

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

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?validate_only=true -d @filename

نشر نموذج "الإعداد عن بُعد"

بعد تنزيل نموذج وإجراء أي تغييرات مطلوبة على محتوى JSON والتحقّق من صحته، يمكنك نشره على مشروع.

يؤدي نشر نموذج إلى استبدال نموذج الضبط الحالي بالكامل بالملف المعدّل وزيادة نسخة النموذج بمقدار واحد. بسبب استبدال الإعدادات بالكامل، إذا حذفت معلَمة من ملف JSON ونشرتها، يتم حذف المَعلمة من الخادم ولن تعود متاحة للعملاء.

بعد النشر، تصبح التغييرات في المَعلمات والقيم متاحة فورًا لتطبيقاتك ومستخدميك. وإذا لزم الأمر، يمكنك العودة إلى إصدار سابق.

استخدِم الأوامر التالية لنشر النموذج:

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

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

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

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

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

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

  على سبيل المثال، إذا كانت لديك مَعلمة "الإعداد عن بُعد" تستخدِم شرطًا يحدِّد قيمة النظام الأساسي iOS، يمكن نشر النموذج في مشروع آخر، لأنّ قيم الأنظمة الأساسية هي نفسها لأي مشروع. ومع ذلك، إذا كان يتضمّن شرطًا يعتمد على رقم تعريف تطبيق أو جمهور مستخدمين محدّدَين غير موجود في المشروع المستهدَف، لن تنجح عملية التحقّق.

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

تنزيل الإعدادات التلقائية لنماذج "الإعداد عن بُعد"

نظرًا لأن تطبيقك قد لا يكون متصلاً بالإنترنت دائمًا، يجب عليك ضبط القيم التلقائية للتطبيق من جهة العميل لجميع معلَمات الإعداد عن بُعد. يجب أيضًا مزامنة القيم التلقائية لبرنامج تطبيقك بشكل دوري وقيم المعلمات التلقائية للخلفية في ميزة "الإعداد عن بُعد"، لأنّها قد تتغيّر بمرور الوقت.

وكما هو موضّح في الروابط الخاصة بالنظام الأساسي في نهاية هذا القسم، يمكنك ضبط هذه الإعدادات التلقائية يدويًا في تطبيقك أو يمكنك تبسيط هذه العملية من خلال تنزيل الملفات التي تحتوي فقط على أزواج المفتاح/القيمة لجميع المعلمات وقيمها التلقائية في نموذج "الإعداد عن بُعد" النشط. يمكنك بعد ذلك تضمين هذا الملف في مشروعك وتهيئة تطبيقك لاستيراد هذه القيم

يمكنك تنزيل هذه الملفات بتنسيق XML لتطبيقات Android، وتنسيق قائمة الخصائص (plist) لتطبيقات iOS، وملفات JSON لتطبيقات الويب.

ننصح بتنزيل الإعدادات التلقائية لميزة "الإعداد عن بُعد" بشكل دوري قبل طرح أي إصدار جديد للتطبيق لضمان المزامنة بين التطبيق والخلفية الخلفية لميزة "الإعداد عن بُعد".

لتنزيل ملف يحتوي على الإعدادات التلقائية للنموذج:

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

لمزيد من المعلومات حول استيراد القيم التلقائية لميزة "الإعداد عن بُعد" إلى تطبيقك، يُرجى الاطّلاع على:

• ضبط قيم المَعلمات التلقائية داخل التطبيق لنظام التشغيل Android

• ضبط قيم المَعلمات التلقائية داخل التطبيق لنظام التشغيل iOS

• ضبط قيم المَعلمات التلقائية داخل التطبيق للويب

• ضبط قيم المَعلمات التلقائية داخل التطبيق لنظام Unity

• ضبط قيم المَعلمات التلقائية داخل التطبيق للغة C++