In dieser Anleitung wird beschrieben, 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 eine erweiterte Funktion der Google Analytics Data API. Eine Einführung in das Feature „Zielgruppenexport“ finden Sie unter Zielgruppenexport erstellen.
Ohne Webhooks müssen Sie die API regelmäßig abfragen, um festzustellen, wann eine Anfrage abgeschlossen ist.
Webhook-Beispielanwendung mit Cloud Run erstellen
Sie können eine Beispiel-Webhook-Anwendung mit Google Cloud erstellen, indem Sie der Anleitung Schnellstart: Beispiel-Dienst in Cloud Run bereitstellen folgen.
Damit der Beispieldienst auf POST-Webhook-Benachrichtigungsanfragen reagiert, ersetzen Sie die Datei index.js aus dem Schnellstart-Tutorial 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 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 Console angezeigt, z. B.:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Dies ist der URI für Serverbenachrichtigungen, ü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 die folgenden Werte im webhookNotification-Objekt an:
Der Serverbenachrichtigungs-URI mit der Webadresse, an die Webhook-Benachrichtigungen gesendet werden.
(Optional) Eine beliebige Zeichenfolge
channelToken, um die Nachricht vor Spoofing zu schützen. Geben Sie diechannelTokenimX-Goog-Channel-Token-HTTP-Header der 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 webhookNotification. Das 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 reagiert 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 Vorgänge mit langer Ausführungszeit 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 wiedergegebene Benachrichtigungen erkennen.
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 die neu erstellte Zielgruppenliste wird im Status
CREATINGangezeigt. Wenn die erste Anfrage an den Webhook fehlschlägt, gibt der VorgangaudienceLists.createeinen 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 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"
}
}
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 Methode audienceLists.create testen möchten, können Sie die Logs Ihrer Cloud Run-Webhook-Beispielanwendung ansehen und den JSON-Text jeder von Google Analytics gesendeten Benachrichtigung prüfen.