Propriétés du script Apps Script : stocker une clé API hors du code avec PropertiesService

Pourquoi sortir les secrets du code

Le réflexe le plus courant, quand on branche un script sur un service externe, c’est d’écrire const API_KEY = 'sk-…'; en haut du fichier. Ça marche, jusqu’au jour où :

• vous partagez le Google Sheets avec un collègue en modification : il voit aussi le code, donc la clé ;
• vous faites une copie du fichier pour un autre client : la clé part avec ;
• vous collez le code sur un forum ou dans un outil d’IA pour demander de l’aide ;
• la clé change : il faut retrouver tous les scripts où elle est écrite.

Les propriétés séparent la configuration (clés, jetons, identifiants de dossier, adresse e-mail du destinataire d’un rapport…) du code. Le code reste identique d’un fichier à l’autre, seules les valeurs changent.

Ajouter une propriété depuis l’éditeur, sans coder

C’est la méthode la plus simple pour une clé API, puisqu’elle ne laisse aucune trace dans le code :

1. Dans le Google Sheets, ouvrez Extensions → Apps Script.
2. Dans la barre de gauche de l’éditeur, cliquez sur l’icône engrenage Paramètres du projet.
3. Descendez jusqu’à la section Propriétés du script.
4. Cliquez sur Ajouter une propriété de script (ou Modifier les propriétés du script s’il en existe déjà).
5. Saisissez une propriété (le nom, par exemple API_KEY) et sa valeur, puis cliquez sur Enregistrer les propriétés du script.

Cet écran ne gère que les propriétés du script. Les propriétés utilisateur et document ne se manipulent que par le code.

Lire la propriété dans le code

function appelerService() {
  const apiKey = PropertiesService.getScriptProperties().getProperty('API_KEY');
  if (!apiKey) {
    throw new Error('Propriété API_KEY absente : ajoutez-la dans Paramètres du projet.');
  }
  // … utiliser apiKey, par exemple dans un en-tête Authorization
}

getProperty renvoie null si la clé n’existe pas : testez toujours ce cas, l’erreur sera beaucoup plus claire qu’un « 401 Unauthorized » renvoyé par l’API trois lignes plus loin.

Les trois magasins de propriétés

Magasin	Méthode	Qui voit la valeur	Usage typique
Script	getScriptProperties()	Toutes les personnes qui exécutent le script	Clé API de l’entreprise, URL d’un webhook, ID d’un dossier Drive
Utilisateur	getUserProperties()	Uniquement l’utilisateur courant, pour ce script	Jeton personnel, préférence d’affichage, signature e-mail
Document	getDocumentProperties()	Tous les utilisateurs, mais propre au fichier ouvert	Réglages d’un module complémentaire installé sur plusieurs fichiers

getDocumentProperties() n’a de sens que pour un script lié à un fichier (créé depuis Extensions → Apps Script) ou un module complémentaire. Dans un script autonome, la méthode renvoie null.

Écrire, lire et supprimer par le code

function demoProprietes() {
  const props = PropertiesService.getScriptProperties();
  // Écrire une valeur (toujours une chaîne de caractères)
  props.setProperty('DOSSIER_EXPORT_ID', '1AbCdEf…');
  // Écrire plusieurs valeurs d’un coup
  props.setProperties({
    RAPPORT_DESTINATAIRE: 'direction@exemple.fr',
    RAPPORT_ACTIF: 'true',
  });
  // Lire une valeur, ou toutes
  const actif = props.getProperty('RAPPORT_ACTIF') === 'true';
  const toutes = props.getProperties(); // objet { clé: valeur }
  Logger.log(Object.keys(toutes));      // n’affichez jamais les valeurs secrètes
  // Supprimer
  props.deleteProperty('DOSSIER_EXPORT_ID');
}

Les valeurs sont toujours stockées en texte. Un booléen devient 'true', un nombre devient '42' : convertissez-les à la lecture (Number(...), comparaison à 'true'). Pour un objet, passez par JSON :

const props = PropertiesService.getUserProperties();
props.setProperty('PREFS', JSON.stringify({ langue: 'fr', relance: 7 }));
const prefs = JSON.parse(props.getProperty('PREFS') || '{}');

Attention à setProperties(objet, true) : le second argument à true supprime toutes les autres propriétés du magasin. Et deleteAllProperties() vide tout, sans corbeille.

Exemple complet : un jeton personnel demandé une seule fois

Quand chaque utilisateur doit utiliser son propre jeton (par exemple pour un outil de facturation où chacun a son compte), on le stocke dans les propriétés utilisateur. Ses collègues ne le verront jamais, même en utilisant le même script.

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('Connexion')
    .addItem('Enregistrer mon jeton', 'enregistrerJeton')
    .addToUi();
}
function enregistrerJeton() {
  const ui = SpreadsheetApp.getUi();
  const rep = ui.prompt('Jeton API', 'Collez votre jeton personnel :', ui.ButtonSet.OK_CANCEL);
  if (rep.getSelectedButton() !== ui.Button.OK) return;
  const jeton = rep.getResponseText().trim();
  if (!jeton) return;
  PropertiesService.getUserProperties().setProperty('JETON_API', jeton);
  ui.alert('Jeton enregistré pour votre compte uniquement.');
}
function getJeton() {
  const jeton = PropertiesService.getUserProperties().getProperty('JETON_API');
  if (!jeton) throw new Error('Aucun jeton : menu Connexion → Enregistrer mon jeton.');
  return jeton;
}

Limites et quotas

Google publie ces limites dans la page des quotas Apps Script (elles peuvent évoluer) :

Limite	Valeur
Taille d’une valeur	9 Ko
Stockage total par magasin	500 Ko
Lectures/écritures par jour (compte gmail.com)	50 000
Lectures/écritures par jour (compte Google Workspace)	500 000

Concrètement : les propriétés sont faites pour de la configuration, pas pour stocker des données. Pour un historique ou une liste de milliers de lignes, utilisez un onglet du classeur. Et si une boucle lit la même propriété des centaines de fois, lisez-la une fois avant la boucle : getProperties() renvoie tout le magasin en un seul appel.

Ce que les propriétés ne protègent pas

• Les éditeurs du projet voient les propriétés du script dans les paramètres du projet. Elles protègent la clé des copies et du code partagé, pas des personnes qui ont accès en modification au projet.
• Le journal d’exécution : un Logger.log(apiKey) oublié affiche la clé à quiconque consulte les exécutions. Ne journalisez que les noms des clés.
• Les copies de fichier : quand on fait une copie d’un Google Sheets, son script lié est copié aussi. Vérifiez ce que la copie contient avant de la transmettre.

Questions fréquentes

Je ne trouve pas « Propriétés du script » dans l’éditeur

La section est dans Paramètres du projet (icône engrenage à gauche), en bas de la page, sous les identifiants et les options de l’éditeur. Il faut être éditeur du projet pour la modifier.

PropertiesService ou CacheService ?

Les propriétés sont permanentes jusqu’à leur suppression. CacheService garde une valeur quelques heures au maximum : il sert à éviter de rappeler une API à chaque exécution, pas à stocker une configuration.

Les propriétés sont-elles chiffrées ?

Elles sont stockées par Google avec le projet, mais lisibles par les éditeurs du projet et par le code. Pour un secret très sensible, limitez le nombre d’éditeurs et utilisez des clés à droits restreints côté service.

Ranger proprement clés et réglages fait partie des bonnes pratiques vues dans la formation Google Apps Script. Pour un outil déjà en place qui mélange code et secrets, voir aussi l’automatisation Google Sheets sur mesure. Suite logique : appeler une API avec UrlFetchApp en utilisant la clé stockée ici.