Webhook-Benachrichtigungen für Zielgruppenlisten erhalten

In dieser Anleitung wird erläutert, wie Sie Webhooks verwenden, um asynchrone Benachrichtigungen zum Status Ihrer Zielgruppenexportanfragen zu erhalten. Dieses Feature ist nur in der v1alpha-Version der Data API verfügbar.

Webhook-Benachrichtigungen sind ein erweitertes Feature der Google Analytics Data API. Eine Einführung in das Feature zum Exportieren von Zielgruppen finden Sie unter Zielgruppenexport erstellen.

Ohne Webhooks müssen Sie die API regelmäßig abfragen, um zu ermitteln, wann eine Anfrage abgeschlossen ist.

Beispiel-Webhook-Anwendung mit Cloud Run erstellen

Sie können eine Beispiel-Webhook-Anwendung mit Google Cloud erstellen. Folgen Sie dazu der Anleitung Schnellstart: Beispiel-Dienst in Cloud Run bereitstellen.

Damit der Beispieldienst auf POST-Webhook-Benachrichtigungsanfragen reagieren kann, ersetzen Sie die Datei index.js aus der Schnellstartanleitung durch den folgenden Code:

  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}`);
  });

Für jede eingehende Webhook-Benachrichtigung, die als POST-Anfrage gesendet wird, gibt dieser Code den JSON-Text der Webhook-Benachrichtigung und einen Channel-Token-Wert aus und gibt den HTTP-Code 200 zurück, um einen erfolgreichen Vorgang anzugeben.

Wenn Sie das Ende der Schnellstartanleitung für Cloud Run erreicht und die Webhook-Anwendung mit dem Befehl gcloud run deploy bereitgestellt haben, speichern Sie die URL, unter der Ihr Dienst bereitgestellt wird.

Die Dienst-URL wird in der Console angezeigt, z. B.:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

Dies ist die Serverbenachrichtigungs-URI unter der Ihre Anwendung auf Webhook-Benachrichtigungen von Google Analytics wartet.

Zielgruppenliste erstellen und Webhook-Benachrichtigungen aktivieren

Wenn Sie Webhook-Benachrichtigungen anfordern möchten, geben Sie die folgenden Werte im webhookNotification Objekt an:

  • Die Serverbenachrichtigungs-URI mit der Webadresse, die Webhook-Benachrichtigungen empfängt.

  • Optional: Eine beliebige String-Variable channelToken um zu verhindern, dass die Nachricht gefälscht wird. Geben Sie channelToken im HTTP-Header X-Goog-Channel-Token der Webhook-POST-Anfrage an.

Hier ist eine Beispielanfrage mit Webhooks:

HTTP-Anfrage

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"
    }
  ]
}

Die Antwort der Methode audienceLists.create enthält webhookNotification, wodurch bestätigt wird, dass der angegebene Webhook innerhalb von 5 Sekunden geantwortet hat.

Sie sehen hier ein Beispiel:

HTTP-Antwort

{
  "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"
    }
  }
}

Wenn ein Webhook nicht antwortet oder Sie eine falsche Dienst-URL angeben, wird stattdessen eine Fehlermeldung zurückgegeben.

Hier ist ein Beispiel für einen Fehler, den Sie möglicherweise erhalten:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Webhook-Benachrichtigungen verarbeiten

Die POST-Anfrage an einen Webhook-Dienst enthält sowohl eine JSON-Version der Ressource für Vorgänge mit langer Ausführungszeit im Text als auch ein Feld sentTimestamp. Der gesendete Zeitstempel gibt die Unix-Epochenzeit in Mikrosekunden an, zu der die Anfrage gesendet wurde. Mit diesem Zeitstempel können Sie wiederholte Benachrichtigungen identifizieren.

Beim Erstellen einer Zielgruppenliste werden entweder eine oder zwei POST-Anfragen an den Webhook gesendet:

  1. Die erste POST-Anfrage wird sofort gesendet und zeigt die neu erstellte Zielgruppenliste im Status CREATING an. Wenn die erste Anfrage an den Webhook fehlschlägt, gibt der Vorgang audienceLists.create einen Fehler und die Details zum Webhook-Fehler zurück.
  2. Die zweite POST-Anfrage wird gesendet, nachdem die Zielgruppenliste erstellt wurde. Die Erstellung ist abgeschlossen, wenn die Zielgruppenliste den Status ACTIVE oder FAILED erreicht.

Hier ist ein Beispiel für die erste Benachrichtigung für eine Zielgruppenliste im Status 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"
      }
  }

Hier ist ein Beispiel für die zweite Benachrichtigung für eine Zielgruppenliste im Status 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"
      }
  }

Die zweite Benachrichtigung bestätigt, dass die Zielgruppenliste erstellt wurde und mit der audienceLists.query Methode abgefragt werden kann.

Wenn Sie Webhooks nach dem Aufrufen der Methode audienceLists.create testen möchten, können Sie die Logs Ihrer Beispiel-Webhook-Anwendung in Cloud Run prüfen und den JSON-Text jeder von Google Analytics gesendeten Benachrichtigung ansehen.