Steeds opnieuw een API bevragen of er iets veranderd is, is verspilling. Beter laat je Workspace je een seintje geven zodra er iets gebeurt. Google Cloud Pub/Sub is de berichtenbus die dat mogelijk maakt: een schaalbare wachtrij waar Workspace-events op publiceren en jouw systeem ze van afhaalt. Dit is de basis voor elke realtime integratie.
In dit artikel zet je stap voor stap een event-pijplijn op en zorg je dat die betrouwbaar blijft draaien.
Hoe Pub/Sub past in Workspace
Pub/Sub is een Google Cloud-dienst, geen onderdeel van Workspace zelf, maar de twee werken naadloos samen. Drie begrippen vormen de kern:
- Een topic is het kanaal waar berichten op gepubliceerd worden.
- Een subscription is hoe jouw verwerker die berichten ontvangt.
- Verschillende Workspace-API's kunnen naar een topic publiceren als je ze de juiste rechten geeft.
Vergeet de publiceerrechten niet
Het cruciale detail is dat je een speciaal Google-serviceaccount publiceerrechten moet geven op je topic. Elke Workspace-bron heeft een eigen service-identiteit die naar je topic mag schrijven. Vergeet je dit, dan komen er simpelweg geen berichten binnen. Dit is verreweg de meest voorkomende oorzaak van een stille pijplijn.
Een topic opzetten
De basis is in een paar stappen geregeld.
Een event-pijplijn opzetten
- Maak een topic aan in je Google Cloud-project.
- Geef het juiste Google-serviceaccount de rol Pub/Sub Publisher op dat topic.
- Maak een subscription aan: push naar een endpoint of pull vanuit je verwerker.
- Koppel de Workspace-bron, bijvoorbeeld een Gmail-watch of een Workspace Events-abonnement, aan het topic.
- Test door een gebeurtenis te triggeren en controleer of de melding binnenkomt.
Push versus pull
Je kunt op twee manieren berichten ontvangen. De keuze hangt af van hoe je verwerker draait.
| Aanpak | Wanneer kiezen | Hoe het werkt |
|---|---|---|
| Push-subscription | Je hebt een altijd-beschikbaar HTTPS-endpoint | Pub/Sub stuurt elk bericht actief naar je URL |
| Pull-subscription | Je draait een worker die zelf bepaalt wanneer hij werk ophaalt | Je verwerker haalt berichten in batches op en bevestigt ze |
Push is handig voor serverless functies die op een binnenkomende request reageren. Pull geeft je meer controle over het tempo en is prettig bij zware verwerking of beperkte capaciteit.
Betrouwbaar verwerken
Pub/Sub garandeert minstens-eenmaal-bezorging. Dat betekent dat een bericht in sommige gevallen meer dan eens kan binnenkomen, bijvoorbeeld na een netwerkonderbreking of een nack.
Maak je verwerking idempotent
Gebruik de message-ID of een eigen sleutel uit de payload om te detecteren of je een gebeurtenis al verwerkt hebt. Zonder deze bescherming krijg je dubbele acties, zoals twee identieke e-mails of twee records, bij elke herbezorging.
Bevestig pas na succes
Bevestig een bericht (ack) pas nadat je het succesvol verwerkt hebt. Faalt de verwerking, ack dan niet, dan levert Pub/Sub het bericht later opnieuw aan. Stel daarnaast een dead-letter-topic in voor berichten die herhaaldelijk falen, zodat ze je pijplijn niet blokkeren.
Onbevestigde berichten bewaart Pub/Sub standaard zeven dagen. Binnen die periode blijft de dienst herbezorgen totdat je ack't of de bewaartermijn verstrijkt. Je kunt deze termijn per subscription instellen, van tien minuten tot eenendertig dagen.
Een concrete koppeling met Gmail
Een veelgebruikt voorbeeld is Gmail. Met de users.watch-aanroep vertel je Gmail naar welk topic het mailbox-wijzigingen moet publiceren. Bij elke wijziging krijg je een melding met een historyId, waarmee je via history.list precies de gewijzigde berichten ophaalt.
Vernieuw je Gmail-watch op tijd
Een Gmail-watch verloopt na maximaal zeven dagen. Roep users.watch periodiek opnieuw aan, bijvoorbeeld dagelijks via een cron-taak, anders stopt de stroom meldingen ongemerkt.
Verder dan Gmail: de Workspace Events API
Naast Gmail biedt de Workspace Events API een bredere ingang. Daarmee abonneer je je op wijzigingen in resources van Google Chat en Google Meet, met meldingen die eveneens via Pub/Sub binnenkomen. Voor Google Drive is een vergelijkbare events-integratie beschikbaar; controleer de actuele status in de Google-documentatie, omdat dit deel via het Developer Preview-programma kan lopen.
Het patroon is steeds hetzelfde: maak een abonnement aan dat naar je topic publiceert, geef de service-identiteit publiceerrechten, en verwerk de berichten idempotent.
Veelgestelde vragen
Kost Pub/Sub geld?
Er is een ruim gratis quotum per maand. Daarboven betaal je per hoeveelheid verwerkte data. Voor de meeste Workspace-integraties blijf je binnen of net boven het gratis niveau. Raadpleeg de actuele prijspagina van Google Cloud voor exacte tarieven.
Waarom ontvang ik geen berichten?
Bijna altijd ontbreken de publiceerrechten voor het juiste Google-serviceaccount op je topic, of de watch is verlopen. Controleer beide en kijk in Cloud Logging of er publicatiefouten zijn.
Hoe lang bewaart Pub/Sub onbevestigde berichten?
Standaard zeven dagen. Binnen die periode probeert Pub/Sub te herbezorgen totdat je ack't of de bewaartermijn verstrijkt. Je kunt de termijn per subscription instellen tussen tien minuten en eenendertig dagen.
Welke Workspace-API's ondersteunen Pub/Sub?
Onder andere Gmail via users.watch, en de bredere Workspace Events API voor diensten zoals Chat en Meet. Voor Drive is een events-integratie beschikbaar waarvan je de beschikbaarheid het beste in de documentatie verifieert.
Moet ik een push- of pull-subscription kiezen?
Kies push als je een altijd-bereikbaar HTTPS-endpoint hebt en snel wilt reageren. Kies pull als je verwerker zelf het tempo wil bepalen of berichten in batches wil verwerken.
Wat is een dead-letter-topic?
Een apart topic waar Pub/Sub berichten naartoe verplaatst die na een ingesteld aantal pogingen niet verwerkt konden worden. Zo blokkeren probleemberichten je hoofdpijplijn niet en kun je ze later apart onderzoeken.
Met Pub/Sub als ruggengraat bouw je reactieve, schaalbare integraties die binnen seconden op Workspace-gebeurtenissen reageren.