خدمة المواقع

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

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

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

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

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

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

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

حفظ البيانات

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

service/propertyService.gs

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

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. انقر على حفظ مواقع النص البرمجي.