# Reports API gebruiken voor Workspace-statistieken

[[TOC]]

Wil je weten wie er vanuit het buitenland inlogde, hoeveel opslag elke gebruiker verbruikt, of welke bestanden extern gedeeld zijn? De Reports API geeft je toegang tot de audit-logs en gebruiksstatistieken van je hele organisatie. Dit is onmisbaar voor security-monitoring, compliance en capaciteitsplanning.

In dit artikel haal je beide soorten rapporten op en leg je een basis voor monitoring.

## Twee soorten rapporten

De Reports API kent twee hoofdcategorieen die je los gebruikt.

- **Activity reports**: gedetailleerde gebeurtenissen per applicatie. Denk aan logins, admin-acties, Drive-deelacties en Gmail-instellingen. Elke regel is een gebeurtenis met actor, tijd en details.
- **Usage reports**: geaggregeerde cijfers per gebruiker, per klant of per entiteit. Denk aan opslaggebruik, aantal verstuurde mails of actieve apps.

:::info title="Audit-data loopt iets achter"
De meeste log-events (login, drive, admin, gmail) verschijnen binnen enkele minuten. Sommige bronnen lopen langer achter: token-events en OAuth tot enkele uren, en geaggregeerde rapporten doorgaans een tot drie dagen. Houd hier rekening mee bij monitoring; voor echte realtime-signalen gebruik je liever de Alert Center API of Pub/Sub.
:::

## Activity-logs ophalen

Je vraagt activiteiten op per `applicationName`, zoals `login`, `drive`, `admin` of `token`. De aanroep loopt via een service-account dat een beheerder impersoneert, met de scope `admin.reports.audit.readonly`.

```python
response = service.activities().list(
    userKey='all',
    applicationName='login',
    startTime='2026-05-01T00:00:00Z'
).execute()
for activiteit in response.get('items', []):
    print(activiteit['actor']['email'], activiteit['events'])
```

:::tip title="Filter op eventName scheelt enorm in volume"
Gebruik de parameter `eventName` om alleen relevante gebeurtenissen op te halen, bijvoorbeeld `login_failure`. Dat verkleint de respons fors en maakt je monitoring veel scherper dan alle events doorploegen. Combineer het met `startTime` en `endTime` om het tijdvak strak te houden.
:::

## Een veelgebruikt scenario: verdachte logins

Een klassieke toepassing is het detecteren van mislukte of verdachte inlogpogingen.

:::howto title="Verdachte logins opsporen"
1. Vraag `activities().list` op met `applicationName='login'` en `eventName='login_failure'`.
2. Groepeer de resultaten per actor en per IP-adres.
3. Markeer accounts met veel mislukte pogingen of logins vanaf onbekende locaties.
4. Stuur een melding naar je security-team of trigger een automatische actie, bijvoorbeeld het tijdelijk uitschakelen van een account.
5. Draai dit periodiek via een geplande taak en bewaar het laatste tijdstip zodat je alleen nieuwe events ophaalt.
:::

## Usage-rapporten ophalen

Voor kwantitatieve cijfers gebruik je `userUsageReport` of `customerUsageReport`. Hiervoor heb je de scope `admin.reports.usage.readonly` nodig.

```python
response = service.userUsageReport().get(
    userKey='all',
    date='2026-05-28'
).execute()
```

Elke gebruiker krijgt een set parameters terug, zoals `accounts:used_quota_in_mb` voor opslagverbruik.

:::warn title="Vraag altijd een datum in het verleden op"
Usage-rapporten gaan over een specifieke afgesloten dag, niet over vandaag. Vraag een datum van enkele dagen geleden op om zeker te zijn dat de data compleet is, anders krijg je lege of onvolledige resultaten.
:::

## Naar een monitoring-pipeline

Voor serieuze monitoring exporteer je de data, omdat de console maar een beperkt venster toont. De standaard bewaartermijn voor de meeste audit-logs is zes maanden, met uitzonderingen zoals Vault (onbeperkt) en Chrome-rapporten (twaalf maanden). Via de API opgehaalde gebruiksdata per klant of gebruiker bewaart Google vijftien maanden.

Veel organisaties sturen audit-logs daarom door naar BigQuery. Daar bewaar je ze langer dan de standaardtermijn, combineer je events met andere bronnen en bouw je dashboards in Looker Studio voor je security- en compliance-team. Een veelgebruikt patroon is een geplande Cloud Function die dagelijks de nieuwe activiteiten ophaalt en wegschrijft naar een BigQuery-tabel.

:::tip title="Begin klein, schaal daarna op"
Start met een enkel rapport, bijvoorbeeld login-events naar een tabel. Zodra dat stabiel draait voeg je drive- en admin-events toe. Zo houd je de pipeline overzichtelijk en debug je makkelijker.
:::

## Veelgestelde vragen

:::faq
### Welke scope heb ik nodig?
Voor alleen-lezen audit-data gebruik je `admin.reports.audit.readonly`. Voor usage-rapporten gebruik je `admin.reports.usage.readonly`. Beide zijn beperkt tot een beheerder die je via domain-wide delegation impersoneert.

### Hoe ver terug gaan de logs?
De meeste audit-logs bewaart Google zes maanden. Vault-events blijven onbeperkt bewaard en Chrome-rapporten twaalf maanden. Via de API opgehaalde gebruiksdata per klant of gebruiker gaat tot vijftien maanden terug. Wil je langer bewaren, exporteer dan naar BigQuery of Cloud Logging.

### Kan ik realtime alerts krijgen?
De Reports API is pull-gebaseerd en kent enige vertraging. De meeste log-events verschijnen binnen minuten, maar voor echte realtime-signalen gebruik je de Alert Center API of stuur je events via Pub/Sub.

### Welke applicaties kan ik opvragen?
Onder andere `login`, `admin`, `drive`, `token`, `calendar`, `groups`, `gmail`, `chat` en `mobile`. Elke applicatie heeft eigen event-types die je met `eventName` verder filtert.

### Waarom krijg ik een 403-fout?
Meestal ontbreekt de juiste scope of impersoneert je service-account geen beheerder met leesrechten op rapporten. Controleer de domain-wide delegation in de Admin console en of de geimpersoneerde gebruiker de rol Reports of een hogere admin-rol heeft.
:::

Met de Reports API krijg je diepgaand inzicht in wat er in je organisatie gebeurt, de basis voor proactieve security en compliance.