Cette page a été traduite par l'API Cloud Translation.

Service des propriétés

Le service des propriétés vous permet de stocker des données simples dans des 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 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 des propriétés, consultez la section Quotas pour les services Google.

Comparaison de magasins de biens immobiliers

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

	Propriétés du script	Propriétés utilisateur	Propriétés du document
Méthode d'accès	`getScriptProperties()`	`getUserProperties()`	`getDocumentProperties()`
Données partagées entre	Tous les utilisateurs d'un script, d'un module complémentaire ou d'une application Web	Utilisateur actuel d'un script, d'un module complémentaire ou d'une application Web	Tous les utilisateurs d'un module complémentaire dans le document ouvert
Généralement utilisé pour	Données de configuration à l'échelle de l'application, telles que le nom d'utilisateur et le mot de passe de la base de données externe du développeur	Paramètres spécifiques à l'utilisateur, comme les unités de mesure ou impériales	Données spécifiques aux documents, comme l'URL source d'un graphique intégré

Format des données

Le service des propriétés 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.

Enregistrement des données...

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

service/propertyService.gs

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

Pour enregistrer des données de manière groupée, transmettez un mappage 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:

service/propertyService.gs

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

Lire des données

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

service/propertyService.gs

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

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

service/propertyService.gs

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

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 modifier les données du magasin, il vous suffit de les réenregistrer:

service/propertyService.gs

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

Supprimer des données

Pour supprimer une seule valeur, appelez Properties.deleteProperty(key):

service/propertyService.gs

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

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

service/propertyService.gs

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

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

Vous pouvez ajouter manuellement jusqu'à cinquante propriétés personnalisées, en tant que chaînes dans des paires clé/valeur, à partir de la page des paramètres du projet. Pour en ajouter plus de cinquante, vous devez les ajouter de manière programmatique à l'aide des méthodes décrites ci-dessus dans la section Enregistrer des données. Lorsque vous définissez les propriétés de script à partir de la page "Paramètres du projet", vous ne pouvez pas référencer de variables de script.

Ajouter des propriétés de script

Ouvrez votre projet Apps Script.
À gauche, cliquez sur Project Settings (Paramètres du projet).
Pour ajouter la première propriété du script, sous Propriétés du script, cliquez sur Ajouter une propriété de script.
Pour ajouter une deuxième propriété et les suivantes, sous Propriétés du script, cliquez sur Modifier les propriétés du script > Ajouter une propriété de script.
Pour Propriété, saisissez le nom de la clé.
Pour Valeur, saisissez la valeur de la clé.
(Facultatif) Pour ajouter d'autres propriétés, cliquez sur Ajouter une propriété de script.
Cliquez sur Enregistrer les propriétés de script.

Modifier les propriétés du script

Ouvrez votre projet Apps Script.
À gauche, cliquez sur Project Settings (Paramètres du projet).
Sous Propriétés du script, cliquez sur Modifier les propriétés du script.
Modifiez le nom et la valeur de clé de chaque propriété que vous souhaitez modifier.
Cliquez sur Enregistrer les propriétés de script.

Supprimer les propriétés de script

Ouvrez votre projet Apps Script.
À gauche, cliquez sur Project Settings (Paramètres du projet).
Sous Propriétés du script, cliquez sur Modifier les propriétés du script.
À côté de la propriété que vous souhaitez supprimer, cliquez sur Supprimer .
Cliquez sur Enregistrer les propriétés de script.