خدمة المواقع

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

للاطّلاع على الحصص اليومية وحدود مساحة التخزين لخدمة "المواقع"، يُرجى الاطّلاع على حصص خدمات 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:

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:

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