Serviço de propriedades

O serviço de propriedades armazena dados em pares de chave-valor no escopo de um script, um usuário de um script ou um documento em que um complemento é usado. Normalmente, ele é usado para armazenar configurações do desenvolvedor ou preferências do usuário. As propriedades nunca são compartilhadas entre scripts.

Para conferir as cotas diárias e os limites de armazenamento do serviço de propriedades, consulte Cotas para serviços do Google.

Comparação de lojas de propriedades

O objeto global PropertiesService oferece três métodos, cada um retornando um objeto Properties semelhante, mas com direitos de acesso diferentes, conforme mostrado na tabela a seguir:

Formato de dados

O serviço de propriedades armazena todos os dados como strings em pares de chave-valor. Os tipos de dados que ainda não são strings são convertidos automaticamente para strings, incluindo métodos contidos em objetos salvos.

Salvar dados

Para salvar um único valor, chame o método Properties.setProperty(key, value) do repositório adequado, conforme mostrado no exemplo a seguir:

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

Para salvar dados em massa, transmita um mapa de pares de chave-valor para Properties.setProperties(properties). Cada par de chave-valor do objeto no parâmetro é armazenado como uma propriedade separada:

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

Ler dados

Para recuperar um único valor salvo anteriormente, chame 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);
}

Para recuperar todos os valores no repositório de propriedades atual, chame 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);
}

Modificar dados

Os métodos getProperty e getProperties retornam uma cópia dos dados armazenados, não uma visualização dinâmica. Portanto, mudar o objeto retornado não atualiza o valor no armazenamento de propriedades. Para atualizar os dados no repositório, salve-os novamente:

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

Excluir dados

Para excluir um único valor, chame 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);
}

Para excluir todas as propriedades na loja atual, chame 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);
}

Gerenciar propriedades do script manualmente

Adicione manualmente até 50 propriedades personalizadas como strings em pares de chave-valor na página de configurações do projeto. Para adicionar mais de 50 propriedades, faça isso de forma programática usando os métodos descritos na seção anterior em Salvar dados. Ao definir propriedades de script na página de configurações do projeto, não faça referência a variáveis de script.

Adicionar propriedades do script

1. Abra seu projeto do Google Apps Script.
2. À esquerda, clique em Configurações do projeto .
3. Para adicionar a primeira propriedade, em Propriedades do script, clique em Adicionar propriedade do script.
4. Para adicionar a segunda propriedade e as seguintes, em Propriedades do script, clique em Editar propriedades do script > Adicionar propriedade do script.
5. Em Propriedade, insira o nome da chave.
6. Em Valor, insira o valor da chave.
7. (Opcional) Para adicionar mais propriedades, clique em Adicionar propriedade de script.
8. Clique em Salvar propriedades do script.

Editar propriedades do script

1. Abra seu projeto do Apps Script.
2. À esquerda, clique em Configurações do projeto .
3. Em Propriedades do script, clique em Editar propriedades do script.
4. Faça mudanças no nome e no valor da chave de cada propriedade que você quer alterar.
5. Clique em Salvar propriedades do script.

Excluir propriedades do script

1. Abra seu projeto do Apps Script.
2. À esquerda, clique em Configurações do projeto .
3. Em Propriedades do script, clique em Editar propriedades do script.
4. Ao lado da propriedade que você quer excluir, clique em Remover close.
5. Clique em Salvar propriedades do script.