Servizio proprietà

Il servizio Proprietà consente di archiviare dati semplici in coppie chiave-valore con ambito a un solo script, a un utente di uno script o a un documento in cui viene utilizzato un componente aggiuntivo. In genere viene utilizzato per archiviare la configurazione sviluppatore o le preferenze utente. Le proprietà non vengono mai condivise tra script.

Per visualizzare le quote giornaliere e i limiti di archiviazione per il servizio Proprietà, consulta Quote per i servizi Google.

Confronto tra i negozi di proprietà

L'oggetto globale PropertiesService offre tre metodi, ognuno dei quali restituisce un oggetto Properties simile, ma con diritti di accesso diversi, come mostrato nella seguente tabella:

	Proprietà script	Proprietà utente	Proprietà documento
Metodo di accesso	getScriptProperties()	getUserProperties()	getDocumentProperties()
Dati condivisi tra	Tutti gli utenti di uno script, di un componente aggiuntivo o di un'app web	L'utente corrente di uno script, di un componente aggiuntivo o di un'app web	Tutti gli utenti di un componente aggiuntivo nel documento aperto
Utilizzato di solito per	Dati di configurazione a livello di app, come nome utente e password del database esterno dello sviluppatore	Impostazioni specifiche dell'utente, ad esempio unità metriche o imperiali	Dati specifici dei documenti, ad esempio l'URL della fonte di un grafico incorporato

Formato dei dati

Il servizio Proprietà archivia tutti i dati come stringhe nelle coppie chiave-valore. I tipi di dati che non sono già stringhe vengono convertiti automaticamente in stringhe, inclusi i metodi contenuti negli oggetti salvati.

Salvataggio dei dati in corso...

Per salvare un singolo valore, chiama il metodo Properties.setProperty(key, value) del negozio appropriato, come mostrato nell'esempio seguente:

service/propertyService.gs

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

Per salvare collettivamente i dati, passa una mappa delle coppie chiave-valore a Properties.setProperties(properties). Ogni coppia chiave-valore dell'oggetto nel parametro viene memorizzata come una proprietà separata:

service/propertyService.gs

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

Lettura dei dati

Per recuperare un singolo valore che hai salvato in precedenza, chiama Properties.getProperty(key):

service/propertyService.gs

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

Per recuperare tutti i valori nell'attuale archivio della proprietà, chiama Properties.getProperties():

service/propertyService.gs

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

Modifica dei dati

I metodi getProperty() e getProperties() restituiscono una copia dei dati archiviati, non una visualizzazione in tempo reale, quindi la modifica dell'oggetto restituito non aggiorna il valore nell'archivio proprietà. Per aggiornare i dati nello store, è sufficiente salvarli di nuovo:

service/propertyService.gs

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

Eliminazione di dati

Per eliminare un singolo valore, chiama Properties.deleteProperty(key):

service/propertyService.gs

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

Per eliminare tutte le proprietà nello store corrente, chiama Properties.deleteAllProperties():

service/propertyService.gs

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

Gestire manualmente le proprietà degli script

Puoi aggiungere manualmente fino a cinquanta proprietà personalizzate, come stringhe nelle coppie chiave-valore, dalla pagina delle impostazioni del progetto. Per aggiungere più di 50 proprietà, devi aggiungerle in modo programmatico utilizzando i metodi descritti sopra nella sezione Salvataggio dei dati. Quando imposti le proprietà dello script dalla pagina delle impostazioni del progetto, non puoi fare riferimento alle variabili dello script.

Aggiungi proprietà script

1. Apri il progetto Apps Script.
2. A sinistra, fai clic su Impostazioni progetto .
3. Per aggiungere la prima proprietà, in Proprietà script fai clic su Aggiungi proprietà script.
4. Per aggiungere la seconda e le successive proprietà, fai clic su Modifica proprietà script > Aggiungi proprietà script in Proprietà script.
5. In Proprietà, inserisci il nome della chiave.
6. In Valore, inserisci il valore della chiave.
7. (Facoltativo) Per aggiungere altre proprietà, fai clic su Aggiungi proprietà dello script.
8. Fai clic su Salva proprietà script.

Modifica proprietà script

1. Apri il progetto Apps Script.
2. A sinistra, fai clic su Impostazioni progetto .
3. In Proprietà script, fai clic su Modifica proprietà script.
4. Modifica il nome e il valore della chiave per ogni proprietà che vuoi modificare.
5. Fai clic su Salva proprietà script.

Elimina proprietà script

1. Apri il progetto Apps Script.
2. A sinistra, fai clic su Impostazioni progetto .
3. In Proprietà script, fai clic su Modifica proprietà script.
4. Fai clic su Rimuovi in corrispondenza della proprietà che vuoi eliminare.
5. Fai clic su Salva proprietà script.