Podstawy raportowania zadań

Za pomocą zadań raportu możesz rozpocząć długotrwałe żądanie asynchroniczne, aby utworzyć niestandardowy raport zawierający dane zdarzeń z Google Analytics.

Zasób Report Task wygenerowany na podstawie tej prośby może być używany do uzyskiwania dostępu do dostosowanych raportów przez wszystkich użytkowników, którzy mają uprawnienia do odczytu w Twojej usłudze w Google Analytics.

Spersonalizowany raport będzie dostępny przez 72 godziny od momentu jego przygotowania. Po tym okresie odpowiedni zasób zadania raportu i jego zawartość zostaną automatycznie usunięte.

Tworzenie zadania raportu

Interfejs Google Analytics Data API w wersji 1 używa asynchronicznego podejścia do tworzenia zadań raportu. Najpierw musisz wysłać żądanie do metody reportTasks.create w celu utworzenia zadania raportu. Następnie do pobrania wygenerowanego raportu niestandardowego używana jest metoda reportTasks.query.

Możesz też użyć reportTasks.get do pobierania metadanych konfiguracji dotyczących konkretnego zadania raportu oraz reportTasks.list do wyświetlania listy wszystkich zadań raportu w usłudze.

Wybierz podmiot raportujący

Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania 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 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 API udostępnia parametr property, który oczekuje ciągu znaków w formacie properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w przewodniku dla początkujących.

Prośba o utworzenie zadania raportu

Aby utworzyć zadanie raportu, wywołaj metodę reportTasks.create za pomocą obiektu ReportTask w prośbie. Wymagane są te parametry:

Przykładowe żądanie utworzenia zadania raportu:

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

Pobieranie stanu gotowości zadania raportu

Wygenerowanie raportu po zakończeniu połączenia reportTasks.create może potrwać kilka minut. Stan gotowości zadania raportu możesz uzyskać, wywołując metodę reportTasks.get.

Użyj nazwy zadania raportu (np. properties/1234567/reportTasks/123), którą otrzymasz w odpowiedzi reportTasks.create, aby określić zadanie raportu.

Przykład:

Żądanie HTTP

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

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

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

Pobieranie wygenerowanego raportu

Po wygenerowaniu zadania raportu utworzonego za pomocą metody reportTasks.create wywołaj metodę reportTasks.query i określ nazwę zadania raportu (np. properties/1234567/reportTasks/123).

Żądanie HTTP

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

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