In dieser Anleitung wird erläutert, wie Sie mithilfe von Webhooks asynchrone Benachrichtigungen zum Status von Anfragen für den Zielgruppenexport 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 zum Exportieren von Zielgruppen 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
Sie können eine Beispiel-Webhook-Anwendung mit Google Cloud erstellen. Folgen Sie dazu der Anleitung Kurzanleitung: Beispieldienst in Cloud Run bereitstellen.
Damit der Beispieldienst POST-Webhook-Benachrichtigungsanfragen überwachen kann, ersetzen Sie die Datei index.js aus der Kurzanleitung 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 anzuzeigen.
Wenn Sie das Ende der Cloud Run-Kurzanleitung 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 Konsole angezeigt, z. B.:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Dies ist der Serverbenachrichtigungs-URI, über den Ihre Anwendung Webhook-Benachrichtigungen von Google Analytics empfängt.
Zielgruppenliste erstellen und Webhook-Benachrichtigungen aktivieren
Geben Sie zum Anfordern von Webhook-Benachrichtigungen die folgenden Werte im Objekt webhookNotification an:
Der Serverbenachrichtigungs-URI mit der Webadresse, an die Webhook-Benachrichtigungen gesendet werden sollen.
(Optional) Ein beliebiger String
channelToken, um vor Spoofing der Nachricht zu schützen. Geben Sie daschannelTokenim HTTP-HeaderX-Goog-Channel-Tokender Webhook-POST-Anfrage an.
Hier sehen Sie eine Beispielanfrage mit Webhooks:
HTTP-Request
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 den webhookNotification, mit dem bestätigt wird, dass der angegebene Webhook in weniger als 5 Sekunden erfolgreich 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, der möglicherweise angezeigt wird:
{
"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 mit langer Ausführungszeit im Text als auch ein sentTimestamp-Feld. Der Zeitstempel „Gesendet“ gibt die Unix-Epochenzeit in Mikrosekunden an, in der die Anfrage gesendet wurde. Anhand dieses Zeitstempels können Sie wiederholte Benachrichtigungen identifizieren.
Beim Erstellen einer Zielgruppenliste werden eine oder zwei POST-Anfragen an den Webhook gesendet:
- Die erste POST-Anfrage wird sofort gesendet. Die neu erstellte Zielgruppenliste wird im Status
CREATINGangezeigt. 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 sehen Sie ein Beispiel für die erste Benachrichtigung für eine Zielgruppenliste mit dem 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 mit dem 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 Methode audienceLists.query abgefragt werden kann.
Wenn Sie Webhooks nach dem Aufrufen der Methode audienceLists.create testen möchten, können Sie die Logs der Cloud Run-Webhook-Beispielanwendung prüfen und sich den JSON-Text aller von Google Analytics gesendeten Benachrichtigungen ansehen.