שירות נכסים

שירות המאפיינים מאפשר לאחסן נתונים פשוטים בצמדי מפתח/ערך עם סקריפט אחד, משתמש אחד בסקריפט או מסמך אחד שבו נעשה שימוש בתוסף. בדרך כלל משתמשים בו כדי לאחסן את הגדרות המפתח או את העדפות המשתמש. המאפיינים אף פעם לא משותפים בין סקריפטים.

במאמר מכסות לשירותי Google תוכלו לראות את המכסות היומיות ומגבלות האחסון של השירות Properties.

השוואה בין חנויות נכסים

האובייקט הגלובלי PropertiesService מציע שלוש שיטות, שכל אחת מהן מחזירה אובייקט Properties דומה אבל עם הרשאות גישה שונות, כפי שמוצג בטבלה הבאה:

	מאפייני הסקריפט	מאפייני משתמש	מאפייני המסמך
שיטת גישה	getScriptProperties()	getUserProperties()	getDocumentProperties()
נתונים שמשותפים בין	כל המשתמשים בסקריפט, בתוסף או באפליקציית אינטרנט	המשתמש הנוכחי בסקריפט, בתוסף או באפליקציית אינטרנט	כל המשתמשים בתוסף במסמך הפתוח
בדרך כלל משמש עבור	נתוני תצורה ברמת האפליקציה, כמו שם המשתמש והסיסמה למסד הנתונים החיצוני של המפתח	הגדרות ספציפיות למשתמש, כמו יחידות מטריות או יחידות אימפריאליות	נתונים ספציפיים למסמך, כמו כתובת ה-URL של המקור של תרשים מוטמע

פורמט נתונים

שירות המאפיינים מאחסן את כל הנתונים כמחרוזות בצמדי מפתח/ערך. סוגי נתונים שהם לא מחרוזות כבר מומרים באופן אוטומטי למחרוזות, כולל methods שכלולות באובייקטים שנשמרו.

מתבצעת שמירה של הנתונים

כדי לשמור ערך בודד, קוראים לשיטה 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);
}

ניהול מאפייני סקריפט באופן ידני

בדף הגדרות הפרויקט אפשר להוסיף באופן ידני עד 50 מאפיינים מותאמים אישית, כמחרוזות בצמדי מפתח/ערך. כדי להוסיף יותר מחמישים מאפיינים, צריך להוסיף אותם באופן פרוגרמטי באמצעות ה-methods שמתוארות למעלה בקטע שמירת נתונים. כשמגדירים מאפייני סקריפטים מדף הגדרות הפרויקט, אי אפשר להפנות למשתני סקריפטים.

הוספת מאפייני סקריפט

1. פותחים את פרויקט Apps Script.
2. בצד ימין, לוחצים על הגדרות הפרויקט .
3. כדי להוסיף את המאפיין הראשון, בקטע Script Properties לוחצים על Add script property (הוספת מאפיין סקריפט).
4. כדי להוסיף את המאפיין השני ואת המאפיין הבא, בקטע מאפייני סקריפט לוחצים על עריכת מאפייני הסקריפט > הוספת מאפיין סקריפט.
5. בשדה נכס, מזינים את שם המפתח.
6. בשדה Value, מזינים את ערך המפתח.
7. (אופציונלי) כדי להוסיף עוד מאפיינים, לוחצים על הוספת מאפיין סקריפט.
8. לוחצים על Save script properties (שמירת מאפייני הסקריפט).

עריכת מאפייני הסקריפט

1. פותחים את פרויקט Apps Script.
2. בצד ימין, לוחצים על הגדרות הפרויקט .
3. בקטע מאפייני סקריפט, לוחצים על עריכת מאפייני סקריפט.
4. עורכים שינויים בשם המפתח ובערך המפתח בכל נכס שרוצים לשנות.
5. לוחצים על Save script properties (שמירת מאפייני הסקריפט).

מחיקת מאפייני סקריפט

1. פותחים את פרויקט Apps Script.
2. בצד ימין, לוחצים על הגדרות הפרויקט .
3. בקטע מאפייני סקריפט, לוחצים על עריכת מאפייני סקריפט.
4. לצד הנכס שרוצים למחוק, לוחצים על סמל ההסרה .
5. לוחצים על Save script properties (שמירת מאפייני הסקריפט).