Servizio proprietà

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

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

Confronto tra gli archivi 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 tabella seguente:

Proprietà script Proprietà utente Proprietà documento
Metodo di accesso getScriptProperties() getUserProperties() getDocumentProperties()
Dati condivisi tra Tutti gli utenti di uno script, un componente aggiuntivo o un'app web L'utente corrente di uno script, un componente aggiuntivo o un'app web Tutti gli utenti di un componente aggiuntivo nel documento aperto
In genere utilizzato per Dati di configurazione a livello di app, come il nome utente e la password per il database esterno dello sviluppatore Impostazioni specifiche dell'utente, come unità di misura metriche o imperiali Dati specifici del documento, come l'URL di origine di un grafico incorporato

Formato dei dati

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

Risparmia dati

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

service/propertyService.gs
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 i dati in blocco, passa una mappa di coppie chiave-valore a Properties.setProperties(properties). Ogni coppia chiave-valore dell'oggetto nel parametro viene archiviata come proprietà separata:

service/propertyService.gs
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 di dati

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

service/propertyService.gs
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 nel datastore delle proprietà corrente, chiama Properties.getProperties:

service/propertyService.gs
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 live, quindi la modifica dell'oggetto restituito non aggiorna il valore nell'archivio delle proprietà. Per aggiornare i dati nel datastore, salvali di nuovo:

service/propertyService.gs
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);
}

Elimina i dati

Per eliminare un singolo valore, chiama Properties.deleteProperty:

service/propertyService.gs
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à nell'archivio corrente, chiama Properties.deleteAllProperties:

service/propertyService.gs
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à dello script

Aggiungi manualmente fino a 50 proprietà personalizzate, come stringhe in coppie chiave-valore, dalla pagina delle impostazioni progetto. Per aggiungere più di 50 proprietà, aggiungile a livello di programmazione utilizzando i metodi descritti nella sezione precedente in Salvare i dati. Quando imposti le proprietà dello script dalla pagina delle impostazioni del progetto, non fare riferimento alle variabili dello script.

Aggiungere proprietà dello script

  1. Apri il progetto Google Apps Script.
  2. A sinistra, fai clic su Impostazioni progetto L'icona delle 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à, in Proprietà script fai clic su Modifica proprietà script > Aggiungi 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à script.
  8. Fai clic su Salva proprietà script.

Modificare le proprietà dello script

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

Eliminare le proprietà dello script

  1. Apri il progetto Apps Script.
  2. A sinistra, fai clic su Impostazioni progetto L'icona delle impostazioni progetto.
  3. In Proprietà script, fai clic su Modifica proprietà script.
  4. Accanto alla proprietà che vuoi eliminare, fai clic su Rimuovi .
  5. Fai clic su Salva proprietà script.