خدمة المواقع

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

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

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

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

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

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

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

حفظ البيانات

لحفظ قيمة واحدة، استخدِم الطريقة 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. افتح مشروعك في Apps Script.
  2. على يمين الصفحة، انقر على إعدادات المشروع رمز إعدادات المشروع.
  3. لإضافة الموقع الأوّل، انقر على إضافة خاصية نص برمجي ضمن خصائص النصوص البرمجية.
  4. لإضافة السمة الثانية والتالية، انقر على تعديل سمات النصوص البرمجية > إضافة سمة نص برمجي ضمن سمات النصوص البرمجية.
  5. بالنسبة إلى السمة، أدخِل اسم المفتاح.
  6. بالنسبة إلى القيمة، أدخِل قيمة المفتاح.
  7. (اختياري) لإضافة المزيد من المواقع، انقر على إضافة خاصية نص برمجي.
  8. انقر على حفظ مواقع النصوص البرمجية.

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

  1. افتح مشروعك في Apps Script.
  2. على يمين الصفحة، انقر على إعدادات المشروع رمز إعدادات المشروع.
  3. ضمن مواقع النصوص البرمجية، انقر على تعديل مواقع النصوص البرمجية.
  4. أجرِ تغييرات على اسم المفتاح وقيمته لكلّ موقع تريد تغييره.
  5. انقر على حفظ مواقع النصوص البرمجية.

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

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