Z tego przewodnika dowiesz się, jak używać webhooków do otrzymywania powiadomień asynchronicznych o stanie próśb o eksport list odbiorców. Ta funkcja jest dostępna tylko w wersji 1 alfa interfejsu Data API.
Powiadomienia webhooka to zaawansowana funkcja interfejsu API danych Google Analytics. Więcej informacji o funkcji eksportu list odbiorców znajdziesz w artykule Tworzenie pliku eksportu listy odbiorców.
Bez webhooków musisz okresowo sprawdzać interfejs API, aby określić, kiedy żądanie zostało wykonane.
Tworzenie przykładowej aplikacji webhook za pomocą Cloud Run
Przykładową aplikację webhook możesz utworzyć w Google Cloud, wykonując instrukcje z samouczka Szybki start: wdrażanie przykładowej usługi w Cloud Run.
Aby przykładowa usługa mogła odbierać żądania 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 webhook wysyłanego jako żądanie POST ten kod wypisuje treść JSON powiadomienia webhook i wartość tokenu kanału, a następnie zwraca kod HTTP 200, aby wskazać, że operacja się powiodła.
Po zakończeniu samouczka wdrażania Cloud Run i wdrożeniu aplikacji webhook za pomocą polecenia gcloud run deploy zapisz adres URL, pod którym została wdrożona usługa.
Adres 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, na który aplikacja nasłuchuje powiadomień webhook z Google Analytics.
Utwórz listę odbiorców i włącz powiadomienia webhook
Aby poprosić o powiadomienia webhook, podaj te wartości w obiekcie webhookNotification:
Identyfikator URI powiadomienia serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhook.
(Opcjonalnie) dowolny ciąg znaków
channelToken, który chroni przed podszywanie się pod wiadomość. W nagłówku HTTPX-Goog-Channel-Tokenżądania POST webhooka podaj wartośćchannelToken.
Oto przykładowa prośba korzystająca z wezłów webhook:
Żą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 wartość webhookNotification, która potwierdza, że podany webhook odpowiedział w ciągu mniej niż 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 adres URL usługi, zamiast tego zwrócony zostanie komunikat o błędzie.
Oto przykładowy komunikat o błędzie:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Przetwarzanie powiadomień webhook
Żądanie POST do usługi webhooka zawiera w treści zarówno wersję JSON zasobu operacji długotrwałej, jak i pole sentTimestamp. Wysłana sygnatura czasowa określa czas uniksowej strefy czasowej w mikrosekundach, w której żądanie zostało wysłane. Możesz użyć tego sygnatury czasowej, aby zidentyfikować powiadomienia odtworzone.
Podczas tworzenia listy odbiorców na adres webhook wysyłane jest 1 lub 2 żądania POST:
- Pierwsze żądanie POST jest wysyłane natychmiast i odzwierciedla stan nowo utworzonej listy odbiorców w stanie
CREATING. Jeśli pierwsze żądanie do webhooka się nie powiedzie, operacjaaudienceLists.createzwróci błąd i szczegóły błędu 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 o liście 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 o liście 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 wyszukiwania za pomocą metody audienceLists.query.
Aby przetestować webhooki po wywołaniu metody audienceLists.create, możesz przeglądać logi przykładowej aplikacji webhooka Cloud Run i sprawdzać treść JSON każdego powiadomienia wysłanego przez Google Analytics.