# Properties Service voor configuratie

[[TOC]]

## Properties Service typen

De Properties Service bewaart configuratiedata persistent tussen script-uitvoeringen. In tegenstelling tot de Cache Service gaan Properties nooit verloren, tenzij je ze expliciet verwijdert.

Drie typen:
- **Script Properties**: gedeeld door alle gebruikers, persisteert zolang het script bestaat.
- **Document Properties**: gedeeld door alle gebruikers in het huidige document.
- **User Properties**: privé per gebruiker, persisteert over sessies.

```javascript
const scriptProps = PropertiesService.getScriptProperties();
const docProps = PropertiesService.getDocumentProperties();
const userProps = PropertiesService.getUserProperties();
```

## Eigenschappen lezen en schrijven

```javascript
function beheerProperties() {
  const props = PropertiesService.getScriptProperties();

  props.setProperty('VERSIE', '1.2.0');
  props.setProperty('ADMIN_EMAIL', 'admin@bedrijf.nl');

  props.setProperties({
    DB_HOST: 'db.bedrijf.nl',
    DB_PORT: '3306',
    MAX_RIJEN: '500',
    DEBUG_MODE: 'false',
  });

  const versie = props.getProperty('VERSIE');
  Logger.log(`Versie: ${versie}`);

  const alleProps = props.getProperties();
  Logger.log(JSON.stringify(alleProps));
}
```

:::tip title="Schrijf gebundeld weg met setProperties"
Elke `setProperty()` is een aparte schrijfactie die telt voor je dagquotum. Gebruik `setProperties()` met een object om meerdere waarden in één keer weg te schrijven. Dat is sneller en zuiniger met je quotum.
:::

## Configuratiepatroon

Een veelgebruikt patroon is één toegangsfunctie met standaardwaarden als fallback. Zo werkt je script ook als een property nog niet is gezet.

```javascript
const CONFIG_DEFAULTS = {
  MAX_RIJEN: '500',
  TIMEOUT_SEC: '30',
  NOTIFICATIE_EMAIL: 'beheer@bedrijf.nl',
  DEBUG: 'false',
};

function getConfig(sleutel) {
  const props = PropertiesService.getScriptProperties();
  const waarde = props.getProperty(sleutel);
  return waarde !== null ? waarde : (CONFIG_DEFAULTS[sleutel] || null);
}

function isDebug() {
  return getConfig('DEBUG') === 'true';
}

function setConfig(sleutel, waarde) {
  PropertiesService.getScriptProperties().setProperty(sleutel, String(waarde));
}
```

:::info title="Properties zijn altijd strings"
Elke waarde wordt als string opgeslagen, ook getallen en booleans. Converteer bij het ophalen met `parseInt()`, `parseFloat()`, `=== 'true'` of `JSON.parse()`.
:::

## Gebruikersvoorkeursinstellingen

Voor instellingen die per gebruiker verschillen gebruik je User Properties. Met `JSON.stringify()` en `JSON.parse()` bewaar je ook objecten en getallen in het juiste type.

```javascript
function slaVoorkeurOp(instelling, waarde) {
  PropertiesService.getUserProperties().setProperty(instelling, JSON.stringify(waarde));
}

function getVoorkeur(instelling, standaard = null) {
  const opgeslagen = PropertiesService.getUserProperties().getProperty(instelling);
  return opgeslagen !== null ? JSON.parse(opgeslagen) : standaard;
}

function laadGebruikersInstellingen() {
  const taal = getVoorkeur('taal', 'nl');
  const itemsPerPagina = getVoorkeur('items_per_pagina', 25);
  const donkerModus = getVoorkeur('donker_modus', false);

  Logger.log(`Taal: ${taal}, Items: ${itemsPerPagina}, Donker: ${donkerModus}`);
}
```

## API-sleutels en credentials

Script Properties zijn de standaardplek om API-sleutels buiten je broncode te houden. Zo staan er geen geheimen in je code wanneer je het script deelt of in versiebeheer zet.

```javascript
function slaApiSleutelsOp() {
  const props = PropertiesService.getScriptProperties();
  props.setProperties({
    OPENAI_API_KEY: 'sk-...',
    SLACK_WEBHOOK_URL: 'https://hooks.slack.com/...',
    SENDGRID_API_KEY: 'SG...',
  });
  Logger.log('API-sleutels opgeslagen');
}

function getApiSleutel(service) {
  const sleutel = PropertiesService.getScriptProperties().getProperty(`${service}_API_KEY`);
  if (!sleutel) {
    throw new Error(`API-sleutel voor ${service} niet gevonden. Roep slaApiSleutelsOp() aan.`);
  }
  return sleutel;
}
```

:::warn title="Script Properties zijn niet versleuteld"
Iedereen met bewerkrechten op het script kan Script Properties uitlezen, en ze zijn niet versleuteld in rust. Deel een script met API-sleutels dus nooit met mensen die je het geheim niet toevertrouwt. Roep `slaApiSleutelsOp()` met de echte sleutels eenmalig zelf aan en bewaar de waarden niet in je broncode. Voor strengere eisen gebruik je een Google Cloud-project met Secret Manager.
:::

## Voortgang bijhouden over triggerlopen

Apps Script kapt lange uitvoeringen af (ongeveer 6 minuten voor consumentenaccounts, 30 minuten voor Workspace). Door je voortgang in een property te bewaren kun je in batches verder werken bij de volgende triggerloop.

```javascript
function hervattabareVerwerking() {
  const props = PropertiesService.getScriptProperties();
  const startRij = parseInt(props.getProperty('LAATSTE_VERWERKTE_RIJ') || '1');

  const blad = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const data = blad.getDataRange().getValues();
  const batchGrootte = 50;

  const eindRij = Math.min(startRij + batchGrootte, data.length);

  for (let i = startRij; i < eindRij; i++) {
    verwerkRij(data[i]);
  }

  if (eindRij < data.length) {
    props.setProperty('LAATSTE_VERWERKTE_RIJ', String(eindRij));
    Logger.log(`Voortgang opgeslagen: rij ${eindRij}`);
  } else {
    props.deleteProperty('LAATSTE_VERWERKTE_RIJ');
    Logger.log('Alle rijen verwerkt');
  }
}

function verwerkRij(rij) {
  Logger.log(rij[0]);
}
```

## Properties verwijderen

```javascript
function verwijderProperties() {
  const props = PropertiesService.getScriptProperties();

  props.deleteProperty('TIJDELIJKE_WAARDE');

  props.deleteAllProperties();
  Logger.log('Alle script-properties verwijderd');
}
```

## Limieten in één oogopslag

| Limiet | Waarde |
| --- | --- |
| Maximale grootte per waarde | 9 KB |
| Maximale totale opslag per store | 500 KB |
| Lees- of schrijfacties per dag (consument) | 50.000 |
| Lees- of schrijfacties per dag (Workspace) | 500.000 |

Deze limieten gelden voor juni 2026. Controleer bij twijfel de actuele quota-pagina van Apps Script.

:::faq
### Hoe groot mogen Properties zijn?
Maximaal 9 KB per waarde en maximaal 500 KB totaal per Properties-store. Voor grotere data gebruik je de Cache Service of een bestand in Drive.

### Zijn Script Properties zichtbaar voor andere gebruikers van het script?
Ja, Script Properties worden gedeeld en zijn leesbaar voor iedereen met bewerkrechten op het project. Gebruik User Properties voor privédata per gebruiker.

### Kan ik Properties bekijken zonder code te schrijven?
Ja. Open in de Apps Script-editor het tandwiel Projectinstellingen en scroll naar Scripteigenschappen. Daar zie je alle script-eigenschappen en kun je ze handmatig toevoegen of bewerken.

### Wat gebeurt er met Properties als ik het script verwijder?
Properties worden samen met het project verwijderd. Maak een exportfunctie die Properties naar een sheet schrijft als je een back-up wilt.

### Wat is het verschil met de Cache Service?
De Cache Service is bedoeld voor tijdelijke data die na maximaal zes uur verloopt, terwijl Properties persistent blijven tot je ze verwijdert. Gebruik Cache voor snelheidswinst en Properties voor configuratie die moet blijven bestaan.

### Tellen lees- en schrijfacties tegen een quotum?
Ja. Er geldt een dagquotum van 50.000 acties voor consumentenaccounts en 500.000 voor Workspace-accounts. Bundel daarom waar mogelijk met `getProperties()` en `setProperties()` in plaats van losse aanroepen.
:::

:::howto title="Script configureren zonder code te wijzigen"
1. Maak een setup-functie die standaardwaarden met `setProperties()` in Script Properties zet.
2. Voer de setup-functie eenmalig uit via de editor.
3. Gebruik `getConfig(sleutel)` als enige toegangspunt tot configuratie in je script.
4. Pas waarden later aan via het tandwiel **Projectinstellingen** en **Scripteigenschappen**.
5. Gebruik User Properties voor configuratie die per gebruiker verschilt, zoals een taalvoorkeur.
:::

Properties Service maakt scripts configureerbaar zonder codeveranderingen. Sla API-sleutels, drempelwaarden en gebruikersvoorkeuren op als properties en maak je scripts flexibel inzetbaar in verschillende omgevingen.