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 interfejsie Data API w wersji v1alpha.
Powiadomienia webhook to zaawansowana funkcja interfejsu Data API Google Analytics. Wprowadzenie do funkcji eksportowania list odbiorców znajdziesz w artykule Tworzenie eksportu list odbiorców.
Bez webhooków musisz okresowo odpytywać interfejs API, aby określić, kiedy żądanie zostało zrealizowane.
Tworzenie przykładowej aplikacji webhooka za pomocą Cloud Run
Możesz utworzyć przykładową aplikację webhooka 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 Szybki start 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 wysył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 się powiodła.
Po ukończeniu samouczka szybkiego startu Cloud Run i wdrożeniu aplikacji webhooka za pomocą polecenia gcloud run deploy zapisz adres URL, pod którym wdrożono usługę.
W konsoli wyświetli się URL usługi, na przykład:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Jest to identyfikator URI powiadomień serwera, pod którym Twoja aplikacja nasłuchuje powiadomień webhooka z Google Analytics.
Tworzenie listy odbiorców i włączanie powiadomień webhooka
Aby poprosić o powiadomienia webhooka, podaj te wartości w obiekcie webhookNotification:
Identyfikator URI powiadomienia serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhooka.
(Opcjonalnie) Dowolny ciąg znaków
channelToken, który chroni przed podszywaniem się pod wiadomość. OkreślchannelTokenw nagłówku HTTPX-Goog-Channel-Tokenżą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ź metody audienceLists.create zawiera webhookNotification, co potwierdza, że określony webhook odpowiedział w ciągu 5 sekund.
Oto 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 URL usługi, zostanie zwrócony komunikat o błędzie.
Oto przykładowy błąd, który może się pojawić:
{
"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 webhooka zawiera w treści zarówno wersję JSON zasobu długotrwałej operacji, jak i pole sentTimestamp. Sygnatura czasowa wysłania określa czas epoki uniksowej w mikrosekundach, w którym żądanie zostało wysłane. Możesz użyć tej sygnatury czasowej do identyfikacji 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 i wyświetla nowo utworzoną listę odbiorców w stanie
CREATING. Jeśli pierwsze żądanie do webhooka nie powiedzie się, operacjaaudienceLists.createzwróci błąd i szczegóły niepowodzenia webhooka. - Drugie żądanie POST jest wysyłane po utworzeniu listy odbiorców. Tworzenie listy odbiorców jest zakończone, gdy osiągnie ona 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 wyświetlić treść JSON każdego powiadomienia wysłanego przez Google Analytics.