שירות נכסים

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

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

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

האובייקט הגלובלי 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);
}

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

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

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

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

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

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

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

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