Z tego przewodnika dowiesz się, jak używać webhooków do otrzymywania asynchronicznych powiadomień o stanie żądań eksportowania list odbiorców. Ta funkcja jest dostępna tylko w wersji v1alpha 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ć do interfejsu API zapytania, aby sprawdzić, czy żądanie zostało zrealizowane.
Tworzenie przykładowej aplikacji webhooka za pomocą Cloud Run
Przykładową aplikację webhooka 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 mogła nasłuchiwać żą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 drukuje 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 webhook przy użyciu polecenia gcloud run deploy zapisz adres URL, pod którym jest wdrożona usługa.
URL usługi jest wyświetlany w konsoli, na przykład:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Jest to identyfikator URI powiadomienia serwera, pod 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:
Adres 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ślchannelTokenwX-Goog-Channel-Tokennagłówku HTTP żądania POST webhooka.
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 webhookNotification, co 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:
- Pierwsze żądanie POST jest wysyłane natychmiast, a na liście odbiorców w stanie
CREATINGwidać nowo utworzoną listę. Jeśli pierwsze żądanie wysłane do webhooka zakończy się niepowodzeniem, 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.