In diesem Leitfaden wird erläutert, wie Sie Webhooks verwenden, um asynchrone Benachrichtigungen zum Status Ihrer Anfragen für den Zielgruppenexport zu 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 die Cloud Run-Kurzanleitung abgeschlossen und die Webhook-Anwendung mit dem Befehl gcloud run deploy bereitgestellt haben, speichern Sie die URL, unter der Ihr Dienst bereitgestellt ist.
Die Dienst-URL wird in der Console 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
Wenn Sie Webhook-Benachrichtigungen anfordern möchten, geben Sie im Objekt webhookNotification die folgenden Werte an:
Der Serverbenachrichtigungs-URI mit der Webadresse, die Webhook-Benachrichtigungen empfängt.
(Optional) Ein beliebiger String
channelToken, um die Nachricht vor Spoofing zu schützen. Geben Sie diechannelTokenim HTTP-HeaderX-Goog-Channel-Tokender Webhook-POST-Anfrage an.
Hier ist 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 den webhookNotification, der bestätigt, dass der angegebene Webhook innerhalb von 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 ein Beispiel für einen Fehler, der auftreten kann:
{
"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 sentTimestamp-Feld. Der Zeitstempel für das Senden gibt die Unix-Epoche in Mikrosekunden an, zu der die Anfrage gesendet wurde. Anhand dieses Zeitstempels können Sie wiederholte Benachrichtigungen identifizieren.
Während der Erstellung einer Zielgruppenliste werden entweder eine oder zwei POST-Anfragen an den Webhook gesendet:
- Die erste POST-Anfrage wird sofort gesendet und zeigt die neu erstellte Zielgruppenliste im Status
CREATINGan. 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 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 Methode audienceLists.query abgefragt werden kann.
Wenn Sie Webhooks nach dem Aufruf der Methode audienceLists.create testen möchten, können Sie die Logs Ihrer Cloud Run-Beispiel-Webhook-Anwendung prüfen und sich den JSON-Text jeder von Google Analytics gesendeten Benachrichtigung ansehen.