שירות נכסים

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

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

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

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

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

פורמט נתונים

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

שמירת נתונים

כדי לשמור ערך יחיד, צריך להפעיל את השיטה 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 מאפיינים מותאמים אישית באופן ידני, כמחרוזות בזוגות של מפתח/ערך, מדף ההגדרות של הפרויקט. כדי להוסיף יותר מחמישים נכסים, צריך להוסיף אותם באופן פרוגרמטי באמצעות השיטות שמתוארות למעלה בקטע שמירת נתונים. כשמגדירים מאפייני סקריפט מדף ההגדרות של הפרויקט, אי אפשר להפנות למשתני סקריפט.

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

1. פותחים את הפרויקט ב-Apps Script.
2. בצד ימין, לוחצים על הגדרות הפרויקט .
3. כדי להוסיף את הנכס הראשון, בקטע מאפייני סקריפט לוחצים על הוספת מאפיין סקריפט.
4. כדי להוסיף את המאפיין השני והמאפיינים הבאים, בקטע מאפייני סקריפט לוחצים על עריכת מאפייני הסקריפט > הוספת מאפיין סקריפט.
5. בשדה Property, מזינים את שם המפתח.
6. בשדה ערך, מזינים את הערך של המפתח.
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.