שירות נכסים

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

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

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

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

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);
}

שינוי נתונים

ה-methods‏ 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:

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

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

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

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

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