Podstawowe informacje o zadaniach w raportach

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 zadania raportu wygenerowany na podstawie tej prośby może być używany do uzyskiwania dostępu do raportów niestandardowych przez wszystkich użytkowników, którzy mają dostęp do odczytu Twojej usługi w Google Analytics.

Raport niestandardowy 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ń związanych z raportami. 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 i 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 formacie 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 formacie properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w przewodniku dla początkujących.

Poproś 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.

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

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ń związanych z raportami możesz uzyskać, wywołując metodę reportTasks.list.

Pobieranie wygenerowanego raportu

Gdy zadanie raportu utworzone za pomocą metody reportTasks.create zostanie wygenerowane, 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"
  }
}