Questa guida spiega come utilizzare i webhook per ricevere notifiche asincrone. per lo stato delle tue richieste di esportazione dei segmenti di pubblico. Questa funzionalità è disponibile solo nella versione v1alpha dell'API di dati.
Notifiche webhook sono una funzione avanzata dei dati di Google Analytics l'API. Per un'introduzione funzionalità di esportazione dei segmenti di pubblico. Consulta l'articolo Creare un'esportazione dei segmenti di pubblico.
Senza webhook, dovrai eseguire periodicamente il polling dell'API per determinare quando una richiesta è stata completata.
Crea un'applicazione webhook di esempio utilizzando Cloud Run
Puoi creare un'applicazione webhook di esempio utilizzando Google Cloud seguendo questo il tutorial Guida rapida: Esegui il deployment di un servizio di esempio in Cloud Run.
Affinché il servizio di esempio possa ascoltare le richieste di notifica dei webhook POST,
sostituisci il file index.js del tutorial di avvio rapido con quanto segue
codice:
import express from 'express';
const app = express();
app.use(express.json());
app.post('/', (req, res) => {
const channelToken = req.get('X-Goog-Channel-Token');
const bodyJson = JSON.stringify(req.body);
console.log(`channel token: ${channelToken}`);
console.log(`notification body: ${bodyJson}`);
res.sendStatus(200);
});
const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
console.log(`helloworld: listening on port ${port}`);
});
Per ogni notifica webhook in arrivo inviata come richiesta POST, questo codice viene stampato
il corpo JSON della notifica webhook e un valore del token del canale, e
restituisce il codice HTTP 200 per indicare che l'operazione è riuscita.
Dopo aver raggiunto la fine del tutorial della guida rapida di Cloud Run ed eseguito il deployment
l'applicazione webhook utilizzando il comando gcloud run deploy, salva
l'URL in cui è stato eseguito il deployment del servizio.
L'URL del servizio viene visualizzato nella console, ad esempio:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Questo è l'URI della notifica del server in cui la tua applicazione rimane in ascolto delle notifiche webhook Google Analytics.
Crea un elenco del segmento di pubblico e attiva le notifiche webhook
Per richiedere notifiche webhook, specifica i seguenti valori nel campo webhookNotification
:
L'URI della notifica del server contenente l'indirizzo web che riceverà le notifiche webhook.
(Facoltativo) Una stringa arbitraria
channelTokenper evitare che il messaggio venga falsificato. Specifica il valorechannelTokennell'intestazione HTTPX-Goog-Channel-Tokendel richiesta POST webhook.
Di seguito è riportata una richiesta di esempio che utilizza i webhook:
Richiesta HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
},
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
La risposta del metodo audienceLists.create contiene il parametro
webhookNotification, che conferma che il webhook specificato è stato eseguito correttamente
ha risposto in meno di 5 secondi.
Ecco un esempio di risposta:
Risposta HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged": 51,
"rowCount": 13956,
"percentageCompleted": 100,
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
}
}
}
Se un webhook non risponde o se hai fornito un URL del servizio errato, viene restituito un messaggio di errore.
Ecco un esempio di errore che potresti ricevere:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Elabora le notifiche webhook
La richiesta POST a un servizio webhook contiene sia una versione JSON del file
risorsa per operazioni a lunga esecuzione
nel corpo e un campo sentTimestamp. Il timestamp inviato specifica
il tempo di epoca Unix in microsecondi in cui è stata inviata la richiesta. Puoi utilizzare questo
per identificare le notifiche riprodotte.
Una o due richieste POST vengono inviate al webhook durante una creazione dell'elenco del segmento di pubblico:
- La prima richiesta POST viene inviata immediatamente e mostra la richiesta
elenco del segmento di pubblico nello stato
CREATING. Se la prima richiesta inviata webhook non riesce, l'operazioneaudienceLists.createrestituisce un errore e i dettagli dell'errore del webhook. - La seconda richiesta POST viene inviata dopo il completamento dell'elenco del segmento di pubblico
per la creazione di contenuti. La creazione è completa quando l'elenco del segmento di pubblico raggiunge una
lo stato
ACTIVEoFAILED.
Ecco un esempio della prima notifica per un elenco del segmento di pubblico, nella
Stato CREATING:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"CREATING",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":0,
"rowCount":0,
"percentageCompleted":0,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
Ecco un esempio della seconda notifica per un elenco del segmento di pubblico, nella
Stato ACTIVE:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":68,
"rowCount":13956,
"percentageCompleted":100,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
La seconda notifica conferma che l'elenco del segmento di pubblico è stato creato e
pronto per l'esecuzione di query utilizzando audienceLists.query
.
Per testare i webhook dopo aver chiamato il metodo audienceLists.create, puoi:
ispezione dei log
dell'applicazione webhook Cloud Run di esempio e osserva il corpo JSON di ogni
notifica inviata da Google Analytics.