Service Propriétés

Le service Properties stocke les données sous forme de paires clé/valeur limitées à un script, à un utilisateur d'un script ou à un document dans lequel un module complémentaire est utilisé. Il est généralement utilisé pour stocker la configuration du développeur ou les préférences de l'utilisateur. Les propriétés ne sont jamais partagées entre les scripts.

Pour afficher les quotas quotidiens et les limites de stockage du service Properties, consultez la section Quotas pour les services Google.

Comparaison des magasins de propriétés

L'objet PropertiesService global propose trois méthodes, chacune renvoyant un objet Properties semblable, mais avec des droits d'accès différents, comme indiqué dans le tableau suivant :

Format des données

Le service Properties stocke toutes les données sous forme de chaînes dans des paires clé/valeur. Les types de données qui ne sont pas déjà des chaînes sont automatiquement convertis en chaînes, y compris les méthodes contenues dans les objets enregistrés.

Enregistrer les données

Pour enregistrer une seule valeur, appelez la méthode Properties.setProperty(key, value) du magasin approprié, comme illustré dans l'exemple suivant :

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

Pour enregistrer des données en bloc, transmettez une carte de paires clé/valeur à Properties.setProperties(properties). Chaque paire clé/valeur de l'objet dans le paramètre est stockée en tant que propriété distincte :

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

Lire des données

Pour récupérer une seule valeur que vous avez enregistrée précédemment, appelez Properties.getProperty :

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

Pour récupérer toutes les valeurs du magasin de propriétés actuel, appelez Properties.getProperties :

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

Modifier les données

Les méthodes getProperty et getProperties renvoient une copie des données stockées, et non une vue en direct. Par conséquent, la modification de l'objet renvoyé ne met pas à jour la valeur dans le magasin de propriétés. Pour mettre à jour les données dans le magasin, enregistrez-les à nouveau :

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

Supprimer des données

Pour supprimer une seule valeur, appelez Properties.deleteProperty :

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

Pour supprimer toutes les propriétés du magasin actuel, appelez Properties.deleteAllProperties :

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

Gérer manuellement les propriétés de script

Ajoutez manuellement jusqu'à 50 propriétés personnalisées, sous forme de chaînes dans des paires clé/valeur, à partir de la page des paramètres du projet. Pour ajouter plus de 50 propriétés, ajoutez-les par programmation à l'aide des méthodes décrites dans la section précédente en enregistrant les données. Lorsque vous définissez des propriétés de script à partir de la page des paramètres du projet, ne faites pas référence aux variables de script.

Ajouter des propriétés de script

1. Ouvrez votre projet Google Apps Script.
2. À gauche, cliquez sur Paramètres du projet .
3. Pour ajouter la première propriété, sous Propriétés du script , cliquez sur Ajouter une propriété de script.
4. Pour ajouter la deuxième propriété et les suivantes, sous Propriétés du script , cliquez sur Modifier les propriétés de script > Ajouter une propriété de script.
5. Dans le champ Propriété, saisissez le nom de la clé.
6. Dans le champ Valeur, saisissez la valeur de la clé.
7. (Facultatif) Pour ajouter d'autres propriétés, cliquez sur Ajouter une propriété de script.
8. Cliquez sur Enregistrer les propriétés de script.

Modifier les propriétés de script

1. Ouvrez votre projet Apps Script.
2. À gauche, cliquez sur Paramètres du projet .
3. Sous Propriétés du script, cliquez sur Modifier les propriétés de script.
4. Modifiez le nom et la valeur de la clé pour chaque propriété que vous souhaitez modifier.
5. Cliquez sur Enregistrer les propriétés de script.

Supprimer des propriétés de script

1. Ouvrez votre projet Apps Script.
2. À gauche, cliquez sur Paramètres du projet .
3. Sous Propriétés du script, cliquez sur Modifier les propriétés de script.
4. À côté de la propriété que vous souhaitez supprimer, cliquez sur Supprimer close.
5. Cliquez sur Enregistrer les propriétés de script.