# Batch-API-calls uitvoeren voor Workspace

[[TOC]]

Als je honderd gebruikers wilt aanmaken, is het verleidelijk om honderd losse API-calls te doen. Maar elke call kost een complete netwerkrondreis. Met batch-requests bundel je veel verzoeken in een enkele HTTP-call, wat de overhead enorm verlaagt en je integratie sneller maakt. In dit artikel leer je batches correct inzetten met de Google API Python-client.

## Wat een batch oplevert

Een batch verpakt meerdere onafhankelijke verzoeken in een enkele HTTP-request. Het voordeel zit vooral in de overhead.

- Een netwerkrondreis in plaats van vele.
- Minder TLS-handshakes en connectie-opbouw.
- Hogere doorvoer bij veel kleine operaties.
- Overzichtelijker code met een enkel verzendpunt.

:::info title="Een batch is geen transactie"
De subverzoeken worden onafhankelijk verwerkt en kunnen elk apart slagen of falen. Een fout in het ene subverzoek raakt de andere niet. Behandel elk resultaat dus individueel in de callback.
:::

## Een batch opbouwen in Python

De service-client biedt `new_batch_http_request`. Je voegt verzoeken toe met `add()` en koppelt een callback die per resultaat wordt aangeroepen.

```python
resultaten = {}

def callback(request_id, response, exception):
    if exception is not None:
        resultaten[request_id] = f'fout: {exception}'
    else:
        resultaten[request_id] = response

batch = service.new_batch_http_request(callback=callback)
for index, gebruiker in enumerate(nieuwe_gebruikers):
    batch.add(service.users().insert(body=gebruiker), request_id=str(index))
batch.execute()
```

:::tip title="Geef elk subverzoek een herkenbare ID"
Gebruik per subverzoek een duidelijke `request_id` zodat je in de callback precies weet welk verzoek bij welk resultaat hoort. Geef die mee als argument aan `add()`. Zonder duidelijke ID's is foutafhandeling bij grote batches een raadspel.
:::

## Grootte beperken

De Python-client staat technisch tot 1000 subverzoeken per batch toe (`MAX_BATCH_LIMIT`), maar Google raadt aan om bij maximaal honderd te blijven. Sommige API's hanteren honderd zelfs als harde grens, zoals de Gmail-API. Houd daarom honderd aan als veilige bovengrens en splits grotere hoeveelheden op.

:::howto title="Zo splits je een grote reeks in batches"
1. Verzamel alle gewenste operaties in een lijst.
2. Splits de lijst in stukken van maximaal honderd verzoeken.
3. Bouw per stuk een batch met `new_batch_http_request` en voer hem uit met `execute()`.
4. Verwerk de callbacks en verzamel de fouten per `request_id`.
5. Pas backoff toe tussen batches als je tegen quota of rate limits aanloopt.
:::

:::warn title="Batchen omzeilt je quota niet"
Elk subverzoek telt afzonderlijk mee voor je rate limits. Een batch van honderd inserts verbruikt evenveel quota als honderd losse calls. Combineer batching dus met exponential backoff, anders krijg je rate-limit-fouten (HTTP 429 of 403) binnen je batch.
:::

## Wanneer je batches gebruikt

Batchen is geen wondermiddel. Het loont vooral bij veel kleine, onafhankelijke verzoeken. In de praktijk:

| Situatie | Aanpak |
| --- | --- |
| Veel kleine, onafhankelijke operaties | Batchen levert grote winst op. |
| Een paar grote of onderling afhankelijke calls | Batchen helpt nauwelijks; doe ze los of sequentieel. |
| Continue stroom losse events | Een wachtrij met batching per tijdvenster werkt vaak het beste. |

Let op de afhankelijkheid tussen calls: omdat subverzoeken in willekeurige volgorde verwerkt kunnen worden, kun je geen call laten afhangen van het resultaat van een andere call in dezelfde batch.

## Veelgestelde vragen

:::faq
### Kan ik calls naar verschillende API's in een batch mengen?
Houd batches per API en per versie. Het mengen van verschillende diensten in een batch wordt niet betrouwbaar ondersteund, dus bouw per dienst een eigen batch.

### Wat gebeurt er als een subverzoek faalt?
Alleen dat subverzoek faalt; de rest gaat door. Je callback ontvangt dan de exception, zodat je gericht kunt herstellen of dat ene verzoek opnieuw kunt proberen.

### Hoeveel verzoeken passen er in een batch?
De Python-client staat tot 1000 toe, maar Google raadt maximaal honderd aan en sommige API's begrenzen het daar hard. Houd honderd aan en splits grotere hoeveelheden op.

### Versnelt batching ook lees-operaties?
Ja, het bundelen van veel kleine get-calls vermindert de overhead net zo goed als bij schrijf-operaties.

### Mag een call in de batch afhangen van een andere call?
Nee. Subverzoeken worden onafhankelijk en in willekeurige volgorde verwerkt, dus afhankelijke calls voer je sequentieel uit buiten de batch.
:::

Met batch-requests verwerk je grote hoeveelheden operaties efficient, met minder netwerk-overhead en strakke foutafhandeling per subverzoek.