Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

يصف هذا المستند كيف يمكنك قراءة وتعديل مجموعة المعلمات ذات تنسيق 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 ، راجع أحد نماذج التطبيقات التالية:

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

Admin SDK هي مجموعة من مكتبات الخوادم التي تتيح لك التفاعل مع Firebase من البيئات ذات الامتيازات. بالإضافة إلى إجراء تحديثات لـ Remote Config ، فإن Admin SDK يتيح إنشاء رموز مصادقة Firebase والتحقق منها ، والقراءة والكتابة من Realtime Database ، وما إلى ذلك. لمعرفة المزيد حول المتطلبات الأساسية لـ 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();

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

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

يمكنك استخدام واجهات برمجة التطبيقات الخلفية للحصول على الإصدار النشط الحالي من قالب التكوين عن بُعد بتنسيق 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);
      });
}

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

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

cd169 درهم 2 ب

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

تعديل شروط Remote Config

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

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: '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);
      });
}

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

انشر قالب Remote Config

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

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

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

قم بتعديل 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 متغير البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف ملف JSON الذي يحتوي على مفتاح حساب الخدمة الخاص بك. ينطبق هذا المتغير فقط على جلسة shell الحالية ، لذلك إذا فتحت جلسة جديدة ، فقم بتعيين المتغير مرة أخرى.

Linux أو macOS

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 API Client للغتك المفضلة لاسترداد رمز وصول 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 {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

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

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

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

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

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

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

لفة

89 عبيدة 341

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

إذا لزم الأمر ، يمكنك استخدام واجهة برمجة تطبيقات 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 الخام

800066299 ج

نظرًا لأن هذا طلب كتابة ، يتم تعديل ETag بواسطة هذا الأمر ويتم توفير ETag محدث في رؤوس الاستجابة لأمر PUT التالي.

تعديل شروط Remote Config

يمكنك تعديل شروط 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 أيضًا لأغراض التحكم في الإصدار.

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

رموز خطأ HTTP

كود الحالة المعنى
200 تم التحديث بنجاح
400 حدث خطأ في التحقق من الصحة. على سبيل المثال ، الطلب الذي يحتوي على أكثر من العدد المسموح به للمفاتيح — 2000 — سيعيد 400 (طلب غير صالح) مع رسالة الخطأ ، Param count too large . أيضًا ، يمكن أن يحدث رمز حالة HTTPS في هاتين الحالتين:
  • حدث خطأ عدم تطابق في الإصدار نظرًا لأنه تم تحديث مجموعة القيم والشروط منذ آخر مرة استردت فيها قيمة ETag. لحل هذه المشكلة ، يجب عليك استخدام أمر GET للحصول على قالب جديد وقيمة ETag ، وتحديث القالب ، ثم الإرسال باستخدام هذا القالب وقيمة ETag الجديدة.
  • تم إجراء أمر PUT (طلب تحديث قالب التكوين عن بُعد) بدون تحديد عنوان If-Match .
401 حدث خطأ في التفويض (لم يتم توفير رمز وصول أو لم تتم إضافة Firebase Remote Config REST API إلى مشروعك في Cloud Developer Console)
403 حدث خطأ في المصادقة (تم توفير رمز وصول خاطئ)
500 حدث خطأ داخلي. في حالة حدوث هذا الخطأ ، قم بتقديم بطاقة دعم Firebase

يعني رمز الحالة 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 Console.

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