In dieser Anleitung wird beschrieben, wie Sie mithilfe von Webhooks asynchrone Benachrichtigungen zum Status Ihrer Zielgruppenexportanfragen erhalten. Diese Funktion ist nur in der v1alpha-Version der Data API verfügbar.
Webhook-Benachrichtigungen sind eine erweiterte Funktion der Google Analytics Data API. Eine Einführung in die Funktion „Zielgruppenexport“ finden Sie unter Zielgruppenexport erstellen.
Ohne Webhooks müssen Sie die API regelmäßig abfragen, um festzustellen, wann eine Anfrage abgeschlossen ist.
Beispiel-Webhook-Anwendung mit Cloud Run erstellen
Eine Beispiel-Webhook-Anwendung mit Google Cloud erstellen
Damit der Beispieldienst POST-Webhook-Benachrichtigungsanfragen verarbeiten 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 Kanaltokenwert aus und gibt den HTTP-Code 200 zurück, um einen erfolgreichen Vorgang anzugeben.
Wenn Sie die Cloud Run-Kurzanleitung bis zum Ende durchgearbeitet 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 der URI der Serverbenachrichtigung, unter dem Ihre Anwendung Webhook-Benachrichtigungen von Google Analytics empfängt.
Zielgruppenliste erstellen und Webhook-Benachrichtigungen aktivieren
Wenn du Webhook-Benachrichtigungen anfordern möchtest, gib die folgenden Werte im webhookNotification-Objekt an:
Der Serverbenachrichtigungs-URI mit der Webadresse, an die Webhook-Benachrichtigungen gesendet werden.
Optional: Ein beliebiger String
channelToken, um zu verhindern, dass die Nachricht gefälscht wird. Geben Sie denchannelTokenimX-Goog-Channel-Token-HTTP-Header der Webhook-POST-Anfrage an.
Hier ein Beispiel für eine Anfrage 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, was bestätigt, 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 ein Beispiel für einen möglichen Fehler:
{
"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 den lang laufenden Vorgang im Text als auch ein sentTimestamp-Feld. Der gesendete Zeitstempel gibt die Unix-Epochenzeit in Mikrosekunden an, zu der die Anfrage gesendet wurde. Anhand dieses Zeitstempels können Sie wiederholte Benachrichtigungen erkennen.
Beim Erstellen einer Zielgruppenliste werden entweder eine oder zwei POST-Anfragen an den Webhook gesendet:
- Die erste POST-Anfrage wird sofort gesendet und zeigt den Status
CREATINGder neu erstellten Zielgruppenliste an. Wenn die erste Anfrage an den Webhook fehlschlägt, gibt deraudienceLists.create-Vorgang einen Fehler und die Details zum Webhook-Fehler zurück. - Die zweite POST-Anfrage wird gesendet, nachdem die Zielgruppenliste erstellt wurde. Die Erstellung ist abgeschlossen, wenn die Zielgruppenliste den Status
ACTIVEoderFAILEDerreicht.
Hier 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 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"
}
}
In der zweiten Benachrichtigung wird bestätigt, dass die Zielgruppenliste erstellt wurde und mit der Methode audienceLists.query abgefragt werden kann.
Wenn Sie Webhooks nach dem Aufrufen der audienceLists.create-Methode testen möchten, können Sie die Protokolle Ihrer Beispiel-Cloud Run-Webhook-Anwendung prüfen und den JSON-Text jeder von Google Analytics gesendeten Benachrichtigung aufrufen.