W tym dokumencie opisujemy cykliczne listy odbiorców, które są zaawansowaną funkcją Google Analytics Data API w wersji 1. Wprowadzenie do funkcji eksportowania list odbiorców znajdziesz w przewodniku po podstawach eksportu list odbiorców.
Cykliczne listy odbiorców generują listy odbiorców codziennie w miarę zmiany członkostwa, aby mieć pewność, że korzystasz z najnowszych danych.
Zwykłe (niecykliczne) listy odbiorców to statyczne listy użytkowników, którzy znajdują się na liście odbiorców w momencie jej generowania.
Codziennie twórz nową listę odbiorców
Przetwarzanie danych o odbiorcach z jednego dnia i aktualizowanie liczby członków może zająć różny czas. Nie można upewnić się, że dane listy odbiorców są aktualizowane w ciągu 24 godzin.
Na przykład nawet jeśli codziennie wysyłasz prośbę o opracowanie listy odbiorców o tej samej godzinie, w niektórych dniach będzie ona taka sama jak w poprzednim, a w innych będzie się różnić i będzie zawierać dodatkowy dzień zmian członkostwa.
Listy odbiorców są tworzone na podstawie danych zdarzeń z dnia poprzedzającego najnowsze zmiany w członkostwie. Jeśli utworzysz listę odbiorców przed codziennymi aktualizacjami członkostwa, będzie ona korzystać z danych z dwóch poprzednich dni. Jeśli utworzysz listę odbiorców po codziennej aktualizacji danych o członkostwie, będzie ona korzystać z danych z poprzedniego dnia.
Okresowe ankietowanie na cyklicznej liście odbiorców
Cykliczne listy odbiorców tworzy listy odbiorców tylko wtedy, gdy są dostępne dane z dodatkowego dnia. Dzięki temu nie musisz już zgadywać, kiedy utworzyć nowe listy odbiorców. Zamiast tego możesz przez cały dzień przeprowadzać tańsze ankiety na temat cyklicznej listy odbiorców, by sprawdzić, czy są dostępne dodatkowe dane.
Tworzenie cyklicznej listy odbiorców
Aby utworzyć cykliczną listę odbiorców, wywołaj metodę recurringAudienceLists.create
za pomocą obiektu RecurringAudienceList
w żądaniu. Wymagane są te parametry:
- Prawidłowa nazwa listy odbiorców w polu
audience
w formacieproperties/{propertyId}/audiences/{audienceId}
. Aby uzyskać tę wartość, możesz użyć metodyaudiences.list
w interfejsie Google Analytics Admin API w wersji 1. PoleAudience.name
odpowiedziaudiences.list
zawiera nazwę listy odbiorców. - Prawidłowa lista wymiarów w polu
dimensions
. Listę wymiarów obsługiwanych przez tę metodę znajdziesz w dokumentacji schematu eksportu odbiorców. Na liście odbiorców znajdują się tylko dane dotyczące wymiarów wymienionych w tym polu.
Oto przykładowa cykliczna prośba o utworzenie listy odbiorców:
Żądanie HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
Odpowiedź metody recurringAudienceLists.create
zawiera nazwę z pola name
(np. properties/1234567/recurringAudienceLists/123
). Można jej używać w kolejnych zapytaniach do pobierania metadanych konfiguracji tej cyklicznej listy odbiorców. Metadane konfiguracji zawierają nazwy zasobów instancji listy odbiorców utworzone na potrzeby tej cyklicznej listy odbiorców.
Odpowiedź HTTP
{
"name": "properties/1234567/recurringAudienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"activeDaysRemaining": 180,
"audienceLists": [
"properties/1234567/audienceLists/45678"
]
}
Metadane konfiguracji ankiety
Za pomocą metody recurringAudienceLists.get
możesz pobierać metadane konfiguracji konkretnej cyklicznej listy odbiorców. Metadane konfiguracji zawierają nazwy zasobów instancji listy odbiorców utworzone dla tej cyklicznej listy odbiorców.
Oto przykład:
Żądanie HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123
W odpowiedzi zwracana jest instancja RecurringAudienceList
. Zawiera on metadane konfiguracji, w tym nazwy zasobów instancji listy odbiorców utworzone na potrzeby tej cyklicznej listy odbiorców.
Odpowiedź HTTP
{
"name": "properties/1234567/recurringAudienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"activeDaysRemaining": 180,
"audienceLists": [
"properties/1234567/audienceLists/45678"
]
}
Aby wyświetlić wszystkie cykliczne listy odbiorców danej usługi, możesz użyć parametru recurringAudienceLists.list
.
Używaj webhooków, aby otrzymywać asynchroniczne powiadomienia o nowych listach odbiorców
Zamiast okresowo odpytywać za pomocą metody recurringAudienceLists.get
metadane konfiguracji pod kątem określonej cyklicznej listy odbiorców, możesz asynchronicznie otrzymywać powiadomienia webhooka, gdy lista odbiorców stanie się dostępna.
Aby skonfigurować powiadomienia webhooka, podczas tworzenia nowej cyklicznej listy odbiorców podaj pole webhookNotification
.
Więcej informacji o korzystaniu z webhooków w interfejsie Google Analytics Data API w wersji 1 znajdziesz w dokumentacji WebhookNotification
.
Pobieranie użytkowników z eksportu list odbiorców
Aby pobrać dane użytkowników w ramach eksportu list odbiorców, wywołaj metodę audienceExports.query
i podaj nazwę eksportu listy odbiorców pobraną z metadanych konfiguracji dostarczanych przez recurringAudienceLists.get
lub recurringAudienceLists.list
.
Żądanie HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query
Gdy eksport listy odbiorców jest gotowy, zwracana jest odpowiedź zawierająca listę użytkowników z danej listy:
Odpowiedź HTTP
{
"audienceExport": {
"name": "properties/1234567/audienceExports/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "ACTIVE",
"beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
},
"audienceRows": [
{
"dimensionValues": [
{
"value": "1000276123.1681742376"
}
]
},
{
"dimensionValues": [
{
"value": "1000374452.1668627377"
}
]
},
{
"dimensionValues": [
{
"value": "1000391956.1652750758"
}
]
},
{
"dimensionValues": [
{
"value": "1000410539.1682018694"
}
]
},
{
"dimensionValues": [
{
"value": "1000703969.1666725875"
}
]
}
],
"rowCount": 5
}