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 interfejsu Data API.
Powiadomienia webhooków to zaawansowana funkcja interfejsu Data API interfejsu Google Analytics. Wprowadzenie do funkcji eksportowania list odbiorców znajdziesz w artykule Tworzenie eksportu list odbiorców.
Bez webhooków trzeba okresowo przeprowadzać sondowanie interfejsu API, aby określić, kiedy żądanie zostanie zrealizowane.
Tworzenie przykładowej aplikacji webhooka za pomocą Cloud Run
Aby utworzyć przykładową aplikację webhooka za pomocą Google Cloud, możesz skorzystać z samouczka 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 wprowadzającego 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 wypisuje treść JSON powiadomienia webhooka i wartość tokena kanału oraz zwraca kod HTTP 200, aby zasygnalizować udaną operację.
Po zakończeniu samouczka wprowadzającego do Cloud Run i wdrożeniu aplikacji webhooka za pomocą polecenia gcloud run deploy zapisz adres URL, pod którym wdrożona jest usługa.
URL usługi zostanie wyświetlony 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ń webhooka z Google Analytics.
Utwórz listę odbiorców i włącz powiadomienia webhooka
Aby zażądać powiadomień webhooka, określ te wartości w obiekcie webhookNotification:
Identyfikator URI powiadomień serwera zawierający adres internetowy, na który będą wysyłane powiadomienia webhooka.
(Opcjonalnie) Dowolny ciąg znaków
channelTokenchroniący przed sfałszowaniem wiadomości. OkreślchannelTokenw nagłówku HTTPX-Goog-Channel-Tokenżądania POST webhooka.
Oto przykładowe żądanie przy użyciu 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, który potwierdza, że podany webhook odpowiedział w czasie krótszym 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, pojawi się komunikat o błędzie.
Oto przykładowy błąd, który może wystąpić:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Przetwarzaj powiadomienia webhooka
Żądanie POST do usługi webhooka zawiera w treści zarówno wersję JSON zasobu długo trwającej operacji, jak i pole sentTimestamp. Sygnatura czasowa wysłania określa w mikrosekundach czas wysłania żądania (w mikrosekundach). Możesz wykorzystać tę sygnaturę czasową do identyfikowania ponownie odtwarzanych powiadomień.
Podczas tworzenia listy odbiorców do webhooka wysyłane jest jedno 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 się nie powiedzie, operacjaaudienceLists.createzwróci błąd i szczegóły błędu webhooka. - Drugie żądanie POST jest wysyłane po zakończeniu tworzenia listy odbiorców. Tworzenie zostanie ukoń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 wykonania zapytania za pomocą metody audienceLists.query.
Aby przetestować webhooki po wywołaniu metody audienceLists.create, przejrzyj logi przykładowej aplikacji webhooka Cloud Run i przejrzyj treść JSON każdego powiadomienia wysłanego przez Google Analytics.