Ricevi notifiche webhook per i tuoi elenchi dei segmenti di pubblico

Questa guida spiega come utilizzare gli webhook per ricevere notifiche asincrone sullo stato delle richieste di esportazione dei segmenti di pubblico. Questa funzionalità è disponibile solo nella versione v1alpha dell'API Data.

Le notifiche webhook sono una funzionalità avanzata dell'API Data di Google Analytics. Per un'introduzione alla funzione di esportazione dei segmenti di pubblico, vedi Creare un'esportazione dei segmenti di pubblico.

Senza webhook, dovrai eseguire periodicamente il polling dell'API per determinare quando una richiesta è completata.

Creare un'applicazione webhook di esempio utilizzando Cloud Run

Puoi creare un'applicazione webhook di esempio utilizzando Google Cloud seguendo il tutorial Guida rapida: esegui il deployment di un servizio di esempio in Cloud Run.

Affinché il servizio di esempio ascolti le richieste di notifica webhook POST, sostituire il file index.js del tutorial di avvio rapido con il seguente 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 stampa il corpo JSON della notifica webhook e un valore del token del canale e restituisce il codice HTTP 200 per indicare il buon esito dell'operazione.

Una volta raggiunto il termine del tutorial di introduzione a Cloud Run e aver eseguito il deployment dell'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

Si tratta dell'URI di notifica del server dove la tua applicazione ascolta le notifiche webhook di Google Analytics.

Creare un elenco del segmento di pubblico e attivare le notifiche webhook

Per richiedere notifiche webhook, specifica i seguenti valori nell'oggetto webhookNotification:

  • L'URI di notifica del server contenente l'indirizzo web che riceverà le notifiche webhook.

  • (Facoltativo) Una stringa arbitraria channelToken per proteggerti dal furto d'identità del messaggio. Specifica channelToken nell'intestazione HTTP X-Goog-Channel-Token della richiesta POST webhook.

Ecco una richiesta di esempio che utilizza gli 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 valore webhookNotification, che conferma che l'webhook specificato ha risposto correttamente in meno di 5 secondi.

Ecco una risposta di esempio:

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 fornisci 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 della risorsa di operazioni a lungo termine nel corpo sia un campo sentTimestamp. Il timestamp inviato specifica l'ora Unix epoch in microsecondi in cui è stata inviata la richiesta. Puoi utilizzare questo timestamp per identificare le notifiche riprodotte.

Durante la creazione di un elenco del segmento di pubblico, all'webhook vengono inviate una o due richieste POST:

  1. La prima richiesta POST viene inviata immediatamente e mostra l'elenco dei segmenti di pubblico appena creato nel suo stato CREATING. Se la prima richiesta al webhook non va a buon fine, l'operazione audienceLists.create restituisce un errore e i dettagli dell'errore del webhook.
  2. La seconda richiesta POST viene inviata al termine della creazione dell'elenco del segmento di pubblico. La creazione è completata quando l'elenco dei segmenti di pubblico raggiunge lo stato ACTIVE o FAILED.

Ecco un esempio della prima notifica per un elenco del segmento di pubblico nello 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 nello 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 ed è pronto per essere sottoposto a query utilizzando il metodo audienceLists.query.

Per testare gli webhook dopo aver chiamato il metodo audienceLists.create, puoi controllare i log della tua applicazione webhook Cloud Run di esempio e visualizzare il corpo JSON di ogni notifica inviata da Google Analytics.