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

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

يمكنك تعديل النموذج وإدارته باستخدام "وحدة تحكُّم Firebase" التي تعرض محتوى النموذج بتنسيق رسومي في علامتَي التبويب المَعلمات والشروط. يمكنك أيضًا استخدام Remote Config 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++