Za pomocą zadań raportu możesz rozpocząć długotrwałe żądanie asynchroniczne, aby utworzyć niestandardowy raport z danymi zdarzeń Google Analytics.
Zasób zadania dotyczącego raportu wygenerowany na podstawie tego żądania może być używany przez wszystkich użytkowników z dostępem tylko do odczytu do usługi w Google Analytics w celu uzyskiwania dostępu do raportów dostosowanych.
Niestandardowy raport będzie dostępny przez 72 godziny od momentu jego utworzenia. Po upływie tego czasu odpowiedni zasób zadania raportu i jego zawartość zostaną automatycznie usunięte.
Tworzenie zadania dotyczącego raportu
Interfejs Google Analytics Data API w wersji 1 używa podejścia asynchronicznego do tworzenia zadań raportowania. Po pierwsze, aby utworzyć zadanie raportowania, musisz wysłać żądanie do metody reportTasks.create
. Następnie metoda reportTasks.query
służy do pobrania wygenerowanego raportu niestandardowego.
Dodatkowo możesz użyć parametru reportTasks.get
, aby pobrać metadane konfiguracji dotyczące konkretnego zadania raportowania, oraz parametru reportTasks.list
, aby wyświetlić listę wszystkich zadań raportowania w usłudze.
Wybierz podmiot raportowania
Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania w adresie URL w formie properties/GA_PROPERTY_ID
, np.:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
Raport jest generowany na podstawie danych zdarzeń Google Analytics zebranych w określonej usłudze w Google Analytics.
Jeśli używasz jednej z bibliotek klienta interfejsu Data API, nie musisz ręcznie manipulować ścieżką adresu URL żądania.
Większość klientów interfejsu API udostępnia parametr property
, który oczekuje ciągu znaków w formie properties/GA_PROPERTY_ID
.
Przykłady korzystania z bibliotek klienta znajdziesz w przewodniku dla początkujących.
Prośba o utworzenie zadania dotyczącego raportu
Aby utworzyć zadanie raportowania, wywołaj metodę reportTasks.create
za pomocą obiektu ReportTask
w prośbie. Wymagane są te parametry:
reportDefinition
pole opisujące definicję raportu niestandardowego. Struktura tego parametru jest podobna do definicji raportu używanej przez metody podstawowego raportowania.
Przykład żądania utworzenia zadania związanego z raportowaniem:
Żądanie HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
Odpowiedź metody reportTasks.create
zawiera nazwę zadania dotyczącego raportu w polu name
(np. properties/1234567/reportTasks/123
), która może być używana w kolejnych zapytaniach do uzyskiwania stanu zadania dotyczącego raportu i pobierania powstałego raportu.
Odpowiedź HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Pobieranie stanu gotowości zadania związanego z raportowaniem
Wygenerowanie raportu po wywołaniu może potrwać kilka minut.
reportTasks.create
Stan gotowości zadania raportowania możesz uzyskać, wywołując metodę reportTasks.get
.
Aby określić zadanie raportowania, użyj nazwy zadania raportowania (np. properties/1234567/reportTasks/123
), która została podana w odpowiedzi na zapytanie reportTasks.create
.
Przykład:
Żądanie HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
Stan gotowości zadania związanego z raportowaniem jest zwracany w polu state
odpowiedzi. Po zakończeniu generowania raportu stan zadania związanego z raportami zmieni się z CREATING
na ACTIVE
.
Pole reportMetadata
zawiera ogólne informacje o wygenerowanym raporcie, np. liczbę wierszy i wysokość wykorzystanych tokenów limitu.
Odpowiedź HTTP
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
Stan wszystkich zadań związanych z raportami możesz uzyskać, wywołując metodę reportTasks.list
.
Pobieranie wygenerowanego raportu
Po wygenerowaniu zadania związanego z raportowaniem utworzonego za pomocą metody reportTasks.create
wywołaj metodę reportTasks.query
i wskaż nazwę zadania związanego z raportowaniem (np. properties/1234567/reportTasks/123
).
Żądanie HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
Jeśli zadanie polegające na utworzeniu raportu jest gotowe, zwracana jest odpowiedź zawierająca wygenerowany raport:
Odpowiedź HTTP
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}