خدمات املاک

سرویس Properties به شما امکان می‌دهد داده‌های ساده را در جفت‌های کلید-مقدار ذخیره کنید که به یک اسکریپت، یک کاربر از یک اسکریپت یا یک سند که در آن یک افزونه استفاده می‌شود، محدود می‌شوند. این سرویس معمولاً برای ذخیره پیکربندی توسعه‌دهنده یا تنظیمات کاربر استفاده می‌شود. Properties هرگز بین اسکریپت‌ها به اشتراک گذاشته نمی‌شود.

برای مشاهده سهمیه‌های روزانه و محدودیت‌های ذخیره‌سازی برای سرویس Properties، به سهمیه‌های سرویس‌های Google مراجعه کنید.

مقایسه فروشگاه‌های املاک

شیء سراسری PropertiesService سه متد ارائه می‌دهد که هر کدام یک شیء Properties مشابه اما با حقوق دسترسی متفاوت را برمی‌گردانند، همانطور که در جدول زیر نشان داده شده است:

	ویژگی‌های اسکریپت	ویژگی‌های کاربر	ویژگی‌های سند
روش دسترسی	getScriptProperties()	getUserProperties()	getDocumentProperties()
داده‌های به اشتراک گذاشته شده بین	همه کاربران یک اسکریپت، افزونه یا برنامه وب	کاربر فعلی یک اسکریپت، افزونه یا برنامه وب	همه کاربران یک افزونه در سند باز
معمولاً برای	داده‌های پیکربندی در سطح برنامه، مانند نام کاربری و رمز عبور برای پایگاه داده خارجی توسعه‌دهنده	تنظیمات خاص کاربر، مانند واحدهای متریک یا امپریال	داده‌های مختص سند، مانند URL منبع برای نمودار جاسازی‌شده

قالب داده

سرویس Properties تمام داده‌ها را به صورت رشته‌هایی در جفت‌های کلید-مقدار ذخیره می‌کند. انواع داده‌هایی که از قبل رشته نیستند، از جمله متدهای موجود در اشیاء ذخیره شده، به طور خودکار به رشته تبدیل می‌شوند.

ذخیره داده‌ها

برای ذخیره یک مقدار واحد، متد Properties.setProperty(key, value) را از حافظه‌ی مربوطه فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:

سرویس/ویژگیService.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.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.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.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.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.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.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. برای افزودن اولین ویژگی، در قسمت Script Properties روی Add script property کلیک کنید.
4. برای افزودن ویژگی‌های دوم و بعدی، در بخش «ویژگی‌های اسکریپت» روی «ویرایش ویژگی‌های اسکریپت» > «افزودن ویژگی اسکریپت» کلیک کنید.
5. برای Property ، نام کلید را وارد کنید.
6. برای Value ، مقدار مربوط به کلید را وارد کنید.
7. (اختیاری) برای افزودن ویژگی‌های بیشتر، روی افزودن ویژگی اسکریپت کلیک کنید.
8. روی ذخیره ویژگی‌های اسکریپت کلیک کنید.

ویرایش ویژگی‌های اسکریپت

1. پروژه Apps Script خود را باز کنید.
2. در سمت چپ، روی تنظیمات پروژه کلیک کنید .
3. در قسمت «ویژگی‌های اسکریپت» ، روی «ویرایش ویژگی‌های اسکریپت» کلیک کنید.
4. برای هر ویژگی که می‌خواهید تغییر دهید، نام کلید و مقدار کلید را تغییر دهید.
5. روی ذخیره ویژگی‌های اسکریپت کلیک کنید.

حذف ویژگی‌های اسکریپت

1. پروژه Apps Script خود را باز کنید.
2. در سمت چپ، روی تنظیمات پروژه کلیک کنید .
3. در قسمت «ویژگی‌های اسکریپت» ، روی «ویرایش ویژگی‌های اسکریپت» کلیک کنید.
4. در کنار ملکی که می‌خواهید حذف کنید، روی «حذف کلیک کنید.
5. روی ذخیره ویژگی‌های اسکریپت کلیک کنید.