خدمة المواقع

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

لعرض الحصص اليومية وحدود مساحة التخزين لخدمة "المواقع"، يُرجى الاطّلاع على حصص خدمات Google.

مقارنة بين المتاجر العقارية

يوفّر الكائن العام PropertiesService ثلاث طرق تعرض كل منها كائن Properties مشابهًا ولكن مع حقوق وصول مختلفة، كما هو موضّح في الجدول التالي:

خصائص النص البرمجي خصائص المستخدِمين خصائص المستند
طريقة الوصول getScriptProperties() getUserProperties() getDocumentProperties()
البيانات التي تتم مشاركتها بين جميع مستخدمي نص برمجي أو إضافة أو تطبيق ويب المستخدم الحالي لنص برمجي أو إضافة أو تطبيق ويب جميع مستخدمي إضافة في المستند المفتوح
يُستخدم عادةً مع بيانات الإعدادات على مستوى التطبيق، مثل اسم المستخدم وكلمة المرور لقاعدة البيانات الخارجية للمطوّر الإعدادات الخاصة بالمستخدم، مثل الوحدات المترية أو الإمبراطورية البيانات الخاصة بالمستند، مثل عنوان URL المصدر لرسم بياني مضمّن

تنسيق البيانات

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

جارٍ حفظ البيانات

لحفظ قيمة واحدة، يمكنك استدعاء طريقة Properties.setProperty(key, value) للمتجر المناسب، كما هو موضح في المثال التالي:

service/propertyService.gs
try {
  // Set a property in each of the three property stores.
  const scriptProperties = PropertiesService.getScriptProperties();
  const userProperties = PropertiesService.getUserProperties();
  const documentProperties = PropertiesService.getDocumentProperties();

  scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
  userProperties.setProperty('DISPLAY_UNITS', 'metric');
  documentProperties.setProperty('SOURCE_DATA_ID',
      '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

لحفظ البيانات بشكلٍ مجمّع، انتقِل إلى Properties.setProperties(properties) في خريطة تتضمّن أزواج المفتاح/القيمة. يتم تخزين كل زوج المفتاح/القيمة للكائن في المعلمة كخاصية منفصلة:

service/propertyService.gs
try {
  // Set multiple script properties in one call.
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'cow': 'moo',
    'sheep': 'baa',
    'chicken': 'cluck'
  });
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

قراءة البيانات

لاسترداد قيمة واحدة حفظتها مسبقًا، يمكنك طلب الرقم Properties.getProperty(key):

service/propertyService.gs
try {
  // Get the value for the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  const units = userProperties.getProperty('DISPLAY_UNITS');
  console.log('values of units %s', units);
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

لاسترداد جميع القيم في مخزن المواقع الحالي، يمكنك طلب الرمز Properties.getProperties():

service/propertyService.gs
try {
  // Get multiple script properties in one call, then log them all.
  const scriptProperties = PropertiesService.getScriptProperties();
  const data = scriptProperties.getProperties();
  for (const key in data) {
    console.log('Key: %s, Value: %s', key, data[key]);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

تعديل البيانات

تعرض الطريقتان getProperty() وgetProperties() نسخة من البيانات المخزَّنة، وليس عرضًا مباشرًا، لذا لن يؤدي تغيير العنصر المعروض إلى تعديل القيمة في مخزن الخصائص. لتحديث البيانات في المتجر، ما عليك سوى حفظها مرة أخرى كما يلي:

service/propertyService.gs
try {
  // Change the unit type in the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  let units = userProperties.getProperty('DISPLAY_UNITS');
  units = 'imperial'; // Only changes local value, not stored value.
  userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

حذف البيانات

لحذف قيمة واحدة، يمكنك طلب إجراء Properties.deleteProperty(key):

service/propertyService.gs
try {
  // Delete the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('DISPLAY_UNITS');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

لحذف كل السمات في المتجر الحالي، يمكنك طلب Properties.deleteAllProperties():

service/propertyService.gs
try {
  // Get user properties in the current script.
  const userProperties = PropertiesService.getUserProperties();
  // Delete all user properties in the current script.
  userProperties.deleteAllProperties();
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

إدارة خصائص النص البرمجي يدويًا

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

إضافة خصائص النص البرمجي

  1. افتح مشروع "برمجة تطبيقات Google".
  2. على يمين الصفحة، انقر على رمز إعدادات المشروع رمز إعدادات المشروع.
  3. لإضافة الموقع الأول، ضمن خصائص النص البرمجي، انقر على إضافة موقع نص برمجي.
  4. لإضافة المواقع الثانية واللاحقة، ضمن خصائص النص البرمجي، انقر على تعديل خصائص النص البرمجي > إضافة موقع نص برمجي.
  5. بالنسبة إلى الموقع، أدخِل اسم المفتاح.
  6. بالنسبة إلى القيمة، أدخِل قيمة المفتاح.
  7. (اختياري) لإضافة المزيد من المواقع، انقر على إضافة موقع نص برمجي.
  8. انقر على حفظ مواقع النص البرمجي.

تعديل خصائص النص البرمجي

  1. افتح مشروع "برمجة تطبيقات Google".
  2. على يمين الصفحة، انقر على رمز إعدادات المشروع رمز إعدادات المشروع.
  3. ضمن خصائص النص البرمجي، انقر على تعديل مواقع النص البرمجي.
  4. يمكنك إجراء تغييرات على اسم المفتاح والقيمة الرئيسية لكل موقع تريد تغييره.
  5. انقر على حفظ مواقع النص البرمجي.

حذف خصائص النص البرمجي

  1. افتح مشروع "برمجة تطبيقات Google".
  2. على يمين الصفحة، انقر على رمز إعدادات المشروع رمز إعدادات المشروع.
  3. ضمن خصائص النص البرمجي، انقر على تعديل مواقع النص البرمجي.
  4. بجانب الموقع الذي تريد حذفه، انقر على "إزالة ".
  5. انقر على حفظ مواقع النص البرمجي.