Podstawy raportowania zadań

Za pomocą zadań raportowania możesz rozpocząć długotrwałe żądanie asynchroniczne utworzenia niestandardowego raportu z danych o zdarzeniach Google Analytics.

Zasób zadania raportowania wygenerowany na podstawie tego żądania może być używany do uzyskiwania dostępu do niestandardowych raportów przez wszystkich użytkowników, którzy mają dostęp do odczytu w Twojej usłudze w Google Analytics.

Niestandardowy raport będzie dostępny przez 72 godziny od momentu jego utworzenia. Po tym czasie odpowiedni zasób zadania raportowania i jego zawartość zostaną automatycznie usunięte.

Tworzenie zadania raportowania

Interfejs Google Analytics Data API w wersji 1 używa asynchronicznego podejścia do tworzenia zadań raportowania. Najpierw musisz wysłać żądanie do metody reportTasks.create, aby utworzyć zadanie raportowania. Następnie użyj metody reportTasks.query, aby pobrać wygenerowany raport niestandardowy.

Możesz też użyć metody reportTasks.get , aby pobrać metadane konfiguracji dotyczące konkretnego zadania raportowania, oraz metody reportTasks.list , aby wyświetlić listę wszystkich zadań raportowania w usłudze.

Wybieranie jednostki raportowania

Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania URL w postaci properties/GA_PROPERTY_ID, np.:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

Raport jest generowany na podstawie danych o zdarzeniach 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 modyfikować ścieżki adresu URL żądania. Większość klientów interfejsu API udostępnia parametr property, który oczekuje ciągu znaków w postaci properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w krótkim przewodniku dla początkujących.

Wysyłanie prośby o utworzenie zadania raportowania

Aby utworzyć zadanie raportowania, wywołaj metodę reportTasks.create , używając w żądaniu obiektu ReportTask. Wymagane są te parametry:

Przykład żądania utworzenia zadania raportowania:

Żą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 raportowania w polu name (np. properties/1234567/reportTasks/123), której można użyć w kolejnych zapytaniach, aby uzyskać stan zadania raportowania i pobrać wynikowy raport.

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"
    }
  }
}

Sprawdzanie stanu gotowości zadania raportowania

Wygenerowanie raportu po wywołaniu metody reportTasks.create może potrwać kilka minut. Stan gotowości zadania raportowania możesz sprawdzić, wywołując reportTasks.get metodę.

Aby określić zadanie raportowania, użyj jego nazwy (np. properties/1234567/reportTasks/123) otrzymanej w odpowiedzi na wywołanie metody reportTasks.create.

Przykład:

Żądanie HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

Stan gotowości zadania raportowania jest zwracany w state polu odpowiedzi. Po zakończeniu generowania raportu stan zadania raportowania zmienia się z CREATING na ACTIVE.

Pole reportMetadata zawiera ogólne informacje o wygenerowanym raporcie, takie jak liczba wierszy i liczba 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ń raportowania możesz sprawdzić, wywołując reportTasks.list metodę.

Pobieranie wygenerowanego raportu

Gdy zadanie raportowania utworzone za pomocą reportTasks.create zostanie wygenerowane, wywołaj metodę reportTasks.query i podaj nazwę zadania raportowania (np. properties/1234567/reportTasks/123).

Żądanie HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Jeśli zadanie raportowania 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"
  }
}