Z tego przewodnika dowiesz się, jak używać webhooków do otrzymywania asynchronicznych powiadomień o stanie żądań eksportu list odbiorców. Ta funkcja jest dostępna tylko w wersji alfa 1 interfejsu Data API.
Powiadomienia webhook to zaawansowana funkcja interfejsu Data API Google Analytics. Wprowadzenie do funkcji eksportowania list odbiorców znajdziesz w artykule Tworzenie eksportu listy odbiorców.
Bez webhooków musisz okresowo wysyłać zapytania do interfejsu API, aby sprawdzić, kiedy żądanie zostanie zrealizowane.
Tworzenie przykładowej aplikacji webhook za pomocą Cloud Run
Przykładową aplikację webhook możesz utworzyć za pomocą Google Cloud, postępując zgodnie z samouczkiem Szybki start: wdrażanie przykładowej usługi w Cloud Run.
Aby przykładowa usługa nasłuchiwała żądań powiadomień webhooka POST, zastąp plik index.js z samouczka szybkiego startu tym kodem:
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}`);
});
W przypadku każdego przychodzącego powiadomienia webhooka wysłanego jako żądanie POST ten kod wyświetla treść JSON powiadomienia webhooka i wartość tokena kanału oraz zwraca kod HTTP 200, aby wskazać, że operacja została wykonana prawidłowo.
Po ukończeniu samouczka Szybki start Cloud Run i wdrożeniu aplikacji webhooka za pomocą polecenia gcloud run deploy zapisz adres URL, pod którym jest wdrożona usługa.
Adres URL usługi jest wyświetlany w konsoli, np.:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Jest to identyfikator URI powiadomienia serwera, w którym aplikacja nasłuchuje powiadomień webhook z Google Analytics.
Tworzenie listy odbiorców i włączanie powiadomień webhook
Aby poprosić o powiadomienia webhooka, w obiekcie webhookNotification podaj te wartości:
Identyfikator URI powiadomienia serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhook.
(Opcjonalnie) Dowolny ciąg znaków
channelTokenchroniący przed podszywaniem się pod nadawcę wiadomości. OkreślchannelTokenw nagłówku HTTP żądania POST webhooka.X-Goog-Channel-Token
Oto przykładowe żądanie z użyciem webhooków:
Żądanie HTTP
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"
}
]
}
Odpowiedź z metody audienceLists.create zawiera pole webhookNotification, które potwierdza, że określony webhook odpowiedział w ciągu 5 sekund.
Przykładowa odpowiedź:
Odpowiedź HTTP
{
"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"
}
}
}
Jeśli webhook nie odpowie lub podasz nieprawidłowy adres URL usługi, zamiast tego zostanie zwrócony komunikat o błędzie.
Oto przykładowy komunikat o błędzie, który możesz otrzymać:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Przetwarzanie powiadomień webhooka
Żądanie POST wysyłane do usługi webhook zawiera w treści zarówno wersję JSON zasobu operacji długotrwałej, jak i pole sentTimestamp. Sygnatura czasowa wysłania określa czas epoki uniksowej w mikrosekundach, w którym wysłano żądanie. Ten sygnatura czasowa może służyć do identyfikowania powtórzonych powiadomień.
Podczas tworzenia listy odbiorców do webhooka wysyłane są 1 lub 2 żądania POST:
- Pierwsza prośba POST jest wysyłana natychmiast, a na liście odbiorców w stanie
CREATINGwidać nowo utworzoną listę. Jeśli pierwsze żądanie wysłane do webhooka nie powiedzie się, operacjaaudienceLists.createzwróci błąd i szczegóły niepowodzenia webhooka. - Drugie żądanie POST jest wysyłane po zakończeniu tworzenia listy odbiorców. Tworzenie zostanie zakończone, gdy lista odbiorców osiągnie stan
ACTIVElubFAILED.
Oto przykład pierwszego powiadomienia dotyczącego listy odbiorców w stanie 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"
}
}
Oto przykład drugiego powiadomienia dotyczącego listy odbiorców w stanie 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"
}
}
Drugie powiadomienie potwierdza, że lista odbiorców została utworzona i jest gotowa do wysyłania zapytań za pomocą metody audienceLists.query.
Aby przetestować webhooki po wywołaniu metody audienceLists.create, możesz sprawdzić logi przykładowej aplikacji webhooka Cloud Run i zobaczyć treść JSON każdego powiadomienia wysłanego przez Google Analytics.